gov.usgs.earthquake.nshmp.data

Class XySequence

java.lang.Object

gov.usgs.earthquake.nshmp.data.XySequence

All Implemented Interfaces:

Iterable<XyPoint>

public abstract class XySequence
extends Object
implements Iterable<XyPoint>

Sequence of xy-value pairs that is iterable ascending in x. Once created, the x-values of a sequence are immutable. This class provides static operations to create instances of sequences that have both mutable and immutable y-values. All data supplied to these operations is defensively copied unless it is not necessary to do so. For instance, *copyOf() variants should be used where possible as x-values will never be replicated in memory.

Although this class is not final, it can not be subclassed. Mutable instances of this class are not thread-safe for operations that alter y-values.

Author:

Peter Powers

Method Summary

Modifier and Type	Method and Description
XySequence	add(double term) Add a term to the y-values of this sequence in place.
XySequence	add(double[] ys) Add the supplied y-values to the y-values of this sequence in place.
XySequence	add(XySequence sequence) Add the y-values of a sequence to the y-values of this sequence in place.
<E extends Enum<E>> void	addToMap(E key, Map<E,XySequence> map) Adds this sequence to any exisiting sequence for key in the supplied map.
XySequence	clear() Sets all y-values to 0.
XySequence	complement() Sets the y-values of this sequence to their complement in place [ 1 - y].
static XySequence	copyOf(XySequence sequence) Create a mutable copy of the supplied sequence.
static XySequence	create(Collection<? extends Number> xs, Collection<? extends Number> ys) Create a new sequence with mutable y-values from the supplied value collections.
static XySequence	create(double[] xs, double[] ys) Create a new sequence with mutable y-values from the supplied value arrays.
static XySequence	createImmutable(Collection<? extends Number> xs, Collection<? extends Number> ys) Create a new, immutable sequence from the supplied value collections.
static XySequence	createImmutable(double[] xs, double[] ys) Create a new, immutable sequence from the supplied value arrays.
static XySequence	emptyCopyOf(XySequence sequence) Create a mutable copy of the supplied sequence with all y-values reset to zero.
static XySequence	immutableCopyOf(XySequence sequence) Create an immutable copy of the supplied sequence.
abstract boolean	isClear() Returns true if all y-values are 0.0; false otherwise.
Iterator<XyPoint>	iterator() Returns an iterator over the XyPoints in this sequence.
XyPoint	max() The last XyPoint in this sequence.
XyPoint	min() The first XyPoint in this sequence.
XySequence	multiply(double scale) Multiply (scale) the y-values of this sequence in place.
XySequence	multiply(XySequence sequence) Multiply the y-values of this sequence by the y-values of another sequence in place.
static XySequence	resampleTo(XySequence sequence, double[] xs) Deprecated.
void	set(int index, double value) Sets the y-value at index.
abstract int	size() Returns the number or points in this sequence.
String	toString() Returns a readable string representation of this sequence.
XySequence	transform(Function<Double,Double> function) Transforms all y-values in place using the supplied Function.
abstract XySequence	trim() Returns a new, immutable sequence that has had all leading and trailing zero-valued points (y = 0) removed.
abstract double	x(int index) Returns the x-value at index.
List<Double>	xValues() Returns an immutable List of the sequence x-values.
abstract double	y(int index) Returns the y-value at index.
List<Double>	yValues() Returns an immutable List of the sequence y-values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

create

public static XySequence create(double[] xs,
                                double[] ys)

Create a new sequence with mutable y-values from the supplied value arrays. If the supplied y-value array is null, all y-values are initialized to 0.

Parameters:

xs - x-values to initialize sequence with

ys - y-values to initialize sequence with; may be null

Returns:

a mutable, double[]-backed sequence

Throws:

NullPointerException - if xs are null

IllegalArgumentException - if xs and ys are not the same size

IllegalArgumentException - if xs does not increase monotonically or contains repeated values

createImmutable

public static XySequence createImmutable(double[] xs,
                                         double[] ys)

Create a new, immutable sequence from the supplied value arrays. Unlike create(double[], double[]), the supplied y-value array may not be null.

Parameters:

xs - x-values to initialize sequence with

ys - y-values to initialize sequence with

Returns:

an immutable, double[]-backed sequence

Throws:

NullPointerException - if xs or ys are null

IllegalArgumentException - if xs and ys are not the same size

IllegalArgumentException - if xs does not increase monotonically or contains repeated values

create

public static XySequence create(Collection<? extends Number> xs,
                                Collection<? extends Number> ys)

Create a new sequence with mutable y-values from the supplied value collections. If the y-value collection is null, all y-values are initialized to 0.

Parameters:

xs - x-values to initialize sequence with

ys - y-values to initialize sequence with; may be null

Returns:

a mutable, double[]-backed sequence

Throws:

NullPointerException - if xs are null

IllegalArgumentException - if xs and ys are not the same size

IllegalArgumentException - if xs does not increase monotonically or contains repeated values

createImmutable

public static XySequence createImmutable(Collection<? extends Number> xs,
                                         Collection<? extends Number> ys)

Create a new, immutable sequence from the supplied value collections. Unlike create(Collection, Collection) , the supplied y-value collection may not be null.

Parameters:

xs - x-values to initialize sequence with

ys - y-values to initialize sequence with

Returns:

an immutable, double[]-backed sequence

Throws:

NullPointerException - if xs or ys are null

IllegalArgumentException - if xs and ys are not the same size

IllegalArgumentException - if xs does not increase monotonically or contains repeated values

copyOf

public static XySequence copyOf(XySequence sequence)

Create a mutable copy of the supplied sequence.

Parameters:

sequence - to copy

Returns:

a mutable copy of the supplied sequence

Throws:

NullPointerException - if the supplied sequence is null

emptyCopyOf

public static XySequence emptyCopyOf(XySequence sequence)

Create a mutable copy of the supplied sequence with all y-values reset to zero.

Parameters:

sequence - to copy

Returns:

a mutable copy of the supplied sequence

Throws:

NullPointerException - if the supplied sequence is null

immutableCopyOf

public static XySequence immutableCopyOf(XySequence sequence)

Create an immutable copy of the supplied sequence.

Parameters:

sequence - to copy

Returns:

an immutable copy of the supplied sequence

Throws:

NullPointerException - if the supplied sequence is null

resampleTo

@Deprecated
public static XySequence resampleTo(XySequence sequence,
                                                double[] xs)

Deprecated.

Create a resampled version of the supplied sequence. Method resamples via linear interpolation and does not extrapolate beyond the domain of the source sequence; y-values with x-values outside the domain of the source sequence are set to 0.

Parameters:

sequence - to resample

xs - resample values

Returns:

a resampled sequence

x

public abstract double x(int index)

Returns the x-value at index.

Parameters:

index - to retrieve

Returns:

the x-value at index

Throws:

IndexOutOfBoundsException - if the index is out of range ( index < 0 || index >= size())

y

public abstract double y(int index)

Returns the y-value at index.

Parameters:

index - to retrieve

Returns:

the y-value at index

Throws:

IndexOutOfBoundsException - if the index is out of range ( index < 0 || index >= size())

set

public void set(int index,
                double value)

Sets the y-value at index.

Parameters:

index - of y-value to set.

value - to set

Throws:

IndexOutOfBoundsException - if the index is out of range ( index < 0 || index >= size())

size

public abstract int size()

Returns the number or points in this sequence.

Returns:

the sequence size

xValues

public List<Double> xValues()

Returns an immutable List of the sequence x-values.

Returns:

the List of x-values

yValues

public List<Double> yValues()

Returns an immutable List of the sequence y-values.

Returns:

the List of y-values

iterator

public Iterator<XyPoint> iterator()

Returns an iterator over the XyPoints in this sequence. For immutable implementations, the XyPoint.set(double) method of a returned point throws an UnsupportedOperationException.

Specified by:

iterator in interface Iterable<XyPoint>

min

public XyPoint min()

The first XyPoint in this sequence.

max

public XyPoint max()

The last XyPoint in this sequence.

toString

public String toString()

Returns a readable string representation of this sequence.

Overrides:

toString in class Object

add

public XySequence add(double term)

Add a term to the y-values of this sequence in place.

Parameters:

term - to add

Returns:

this sequence, for use inline

add

public XySequence add(double[] ys)

Add the supplied y-values to the y-values of this sequence in place.

Parameters:

ys - y-values to add

Returns:

this sequence, for use inline

add

public XySequence add(XySequence sequence)

Add the y-values of a sequence to the y-values of this sequence in place.

Parameters:

sequence - to add

Returns:

this sequence, for use inline

Throws:

IllegalArgumentException - if sequence.xValues() != this.xValues()

multiply

public XySequence multiply(double scale)

Multiply (scale) the y-values of this sequence in place.

Parameters:

scale - factor

Returns:

this sequence, for use inline

multiply

public XySequence multiply(XySequence sequence)

Multiply the y-values of this sequence by the y-values of another sequence in place.

Parameters:

sequence - to multiply this sequence by

Returns:

this sequence, for use inline

Throws:

IllegalArgumentException - if sequence.xValues() != this.xValues()

complement

public XySequence complement()

Sets the y-values of this sequence to their complement in place [ 1 - y]. Assumes this is a probability function limited to the domain [0 1].

Returns:

this sequence, for use inline

clear

public XySequence clear()

Sets all y-values to 0.

Returns:

this sequence, for use inline

isClear

public abstract boolean isClear()

Returns true if all y-values are 0.0; false otherwise. a

trim

public abstract XySequence trim()

Returns a new, immutable sequence that has had all leading and trailing zero-valued points (y = 0) removed. Any zero-valued points in the middle of this sequence are ignored.

Throws:

IllegalStateException - if this.isClear() as empty sequences are not permitted

transform

public XySequence transform(Function<Double,Double> function)

Transforms all y-values in place using the supplied Function.

Parameters:

function - for transform

Returns:

this sequence, for use inline

addToMap

public final <E extends Enum<E>> void addToMap(E key,
                                               Map<E,XySequence> map)

Adds this sequence to any exisiting sequence for key in the supplied map. If key does not exist in the map, method puts a mutable copy of this in the map.

Parameters:

key - for sequence to add

map - of sequences to add to

Throws:

IllegalArgumentException - if the x-values of added sequences to not match those of existing sequences