org.opensha.commons.data.function
Class EvenlyDiscretizedFunc

java.lang.Object
  extended by org.opensha.commons.data.function.AbstractXY_DataSet
      extended by org.opensha.commons.data.function.AbstractDiscretizedFunc
          extended by org.opensha.commons.data.function.EvenlyDiscretizedFunc
All Implemented Interfaces:
Serializable, Iterable<Point2D>, DiscretizedFunc, XY_DataSet, Named, PlotElement, XMLSaveable
Direct Known Subclasses:
EvenlyDiscrFuncWithParams, HistogramFunction, IncrementalMagFreqDist

public class EvenlyDiscretizedFunc
extends AbstractDiscretizedFunc

Title: EvenlyDiscretizedFunc

Description: Subclass of DiscretizedFunc and full implementation of DiscretizedFuncAPI. Assumes even spacing between the x points represented by the delta distance. Y Values are stored as doubles in an array of primitives. This allows replacement of values at specified indexes.

Note that the basic unit for this function framework are Point2D which contain x and y values. Since the x-values are evenly space there are no need to store them. They can be calculated on the fly based on index. So the internal storage saves space by only saving the y values, and reconstituting the Point2D values as needed.

Since the x values are not stored, what is stored instead is the x-min value, x-max value, and the delta spacing between x values. This is enough to calculate any x-value by index.

This function can be used to generate histograms. To do that, tolerance should be set greater than delta. Add methods should then be used to add to Y values for histograms. The x value is the mid-point of the histogram interval

Version:
1.0
Author:
Steven W. Rock
See Also:
Serialized Form

Field Summary
protected static String C
          Class name used for debbuging
protected static boolean D
          if true print out debugging statements
protected  double delta
          Distance between x points
protected  boolean first
          Helper boolean that indicates no values have been put into this function yet.
protected  double maxX
          The maximum x-value in this series
protected  double minX
          The minimum x-value in this series, pins the index values with delta
protected  int num
          Number of points in this function
protected  double[] points
          The internal storage collection of points, stored as a linked list
 
Fields inherited from class org.opensha.commons.data.function.AbstractDiscretizedFunc
tolerance, XML_METADATA_NAME, XML_METADATA_POINT_NAME, XML_METADATA_POINTS_NAME
 
Fields inherited from class org.opensha.commons.data.function.AbstractXY_DataSet
info, name, xAxisName, yAxisName
 
Constructor Summary
EvenlyDiscretizedFunc(double min, double max, int num)
          The other three input options to fully quantify the domain of this list, i.e.
EvenlyDiscretizedFunc(double min, int num, double delta)
          This is one of two constructor options to fully quantify the domain of this list, i.e.
 
Method Summary
 void add(double x, double y)
          This method can be used for generating histograms if tolerance is set greater than delta.
 void add(int index, double y)
          This method can be used for generating histograms if tolerance is set greater than delta.
 boolean areAllXValuesInteger(double tolerance)
          It finds out whether the X values are within tolerance of an integer value
 void clear()
          Sets all y values to NaN
 EvenlyDiscretizedFunc deepClone()
          Returns a copy of this and all points in this DiscretizedFunction.
 boolean equalXAndYValues(DiscretizedFunc function)
          Determines if two functions are the same by comparing that each point x value is the same, within tolerance, and that each y value is the same, including nulls.
 boolean equalXValues(DiscretizedFunc function)
          Determines if two functions are the same by comparing that each point x value is the same, within tolerance
 Point2D get(int index)
          Returns an x and y value in a Point2D based on index into the y-points array.
 int getClosestXIndex(double x)
          Returns the index of the supplied value (ignoring tolerance).
 double getClosestYtoX(double x)
          Get the Y value for the point with closest X.
 double getDelta()
          Returns the spacing between x-values
 int getIndex(Point2D point)
          Returns the index of this DataPoint based on it's x any y value both the x-value and y-values in list should match with that of point returns -1 if there is no such value in the list
 double getMaxX()
          Returns the maximum x-value in this series.
 double getMaxY()
          Returns the maximum y-value in this series.
 String getMetadataString()
          prints out the state of the list, such as number of points, the value of each point, etc.
 double getMinX()
          Returns the minimum x-value in this series.
 double getMinY()
          Returns the minimum y-value in this series.
 Iterator<Point2D> getPointsIterator()
          This function may be slow if there are many points in the list.
 double getX(int index)
          Returns the ith x element in this function.
 int getXIndex(double x)
          Returns the index of the supplied value provided it's within the tolerance of one of the discretized values.
protected  int getXIndexBefore(double x)
          Returns the x index that is before the given X value.
 int getXindexForMaxY()
          Returns the x index for the maximum y-value in this series.
 double getY(double x)
          Returns they-value associated with this x-value.
 double getY(int index)
          Returns the ith y element in this function.
 void set(double x, double y)
          Sets the y-value at a specified index.
 void set(double min, double max, int num)
          Three input options to fully quantify the domain of this list, i.e.
 void set(double min, int num, double delta)
          Fully quantify the domain of this list, i.e.
 void set(int index, double y)
          this function will throw an exception if the index is not within the range of 0 to num -1
 void set(Point2D point)
          Calls set( x value, y value ).
 int size()
          Returns the number of points in this series
 String toString()
          Standard java function, usually used for debugging, prints out the state of the list, such as number of points, the value of each point, etc.
protected  boolean withinTolerance(double x, double xx)
          Returns true if two values are within tolerance to be considered equal.
 
Methods inherited from class org.opensha.commons.data.function.AbstractDiscretizedFunc
calcSumOfY_Vals, equals, fromXMLMetadata, getFirstInterpolatedX_inLogXLogYDomain, getFirstInterpolatedX, getInterpolatedY_inLogXLogYDomain, getInterpolatedY_inLogYDomain, getInterpolatedY, getTolerance, hasX, loadFuncFromSimpleFile, loadFuncFromSimpleFile, scale, setTolerance, toXMLMetadata, toXMLMetadata, writeSimpleFuncFile, writeSimpleFuncFile
 
Methods inherited from class org.opensha.commons.data.function.AbstractXY_DataSet
getClosestXtoY, getDatasetsToPlot, getInfo, getName, getPlotNumColorList, getXAxisName, getXValuesIterator, getYAxisName, getYValuesIterator, iterator, setInfo, setName, setXAxisName, setYAxisName, xValues, yValues
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.opensha.commons.data.function.XY_DataSet
getClosestXtoY, getInfo, getXAxisName, getXValuesIterator, getYAxisName, getYValuesIterator, setInfo, setName, setXAxisName, setYAxisName, xValues, yValues
 
Methods inherited from interface org.opensha.commons.gui.plot.PlotElement
getDatasetsToPlot, getPlotNumColorList
 
Methods inherited from interface org.opensha.commons.data.Named
getName
 
Methods inherited from interface java.lang.Iterable
iterator
 

Field Detail

C

protected static final String C
Class name used for debbuging

See Also:
Constant Field Values

D

protected static final boolean D
if true print out debugging statements

See Also:
Constant Field Values

points

protected double[] points
The internal storage collection of points, stored as a linked list


minX

protected double minX
The minimum x-value in this series, pins the index values with delta


maxX

protected double maxX
The maximum x-value in this series


delta

protected double delta
Distance between x points


num

protected int num
Number of points in this function


first

protected boolean first
Helper boolean that indicates no values have been put into this function yet. Used only internally.

Constructor Detail

EvenlyDiscretizedFunc

public EvenlyDiscretizedFunc(double min,
                             int num,
                             double delta)
This is one of two constructor options to fully quantify the domain of this list, i.e. the x-axis.

Parameters:
min - - Starting x value
num - - number of points in list
delta - - distance between x values

EvenlyDiscretizedFunc

public EvenlyDiscretizedFunc(double min,
                             double max,
                             int num)
The other three input options to fully quantify the domain of this list, i.e. the x-axis.

Parameters:
min - - Starting x value
num - - number of points in list
max - - Ending x value
Method Detail

set

public void set(double min,
                int num,
                double delta)
Fully quantify the domain of this list, i.e. the x-axis. This function clears the list of points previously in this function

Parameters:
min - - Starting x value
num - - number of points in list
delta - - distance between x values

set

public void set(double min,
                double max,
                int num)
Three input options to fully quantify the domain of this list, i.e. the x-axis. This function clears the list of points previously in this function

Parameters:
min - - Starting x value
num - - number of points in list
max - - Ending x value

clear

public void clear()
Sets all y values to NaN


withinTolerance

protected boolean withinTolerance(double x,
                                  double xx)
Returns true if two values are within tolerance to be considered equal. Used internally


getDelta

public double getDelta()
Returns the spacing between x-values


size

public int size()
Returns the number of points in this series


getMinX

public double getMinX()
Returns the minimum x-value in this series. Since the value is stored, lookup is very quick


getMaxX

public double getMaxX()
Returns the maximum x-value in this series. Since the value is stored, lookup is very quick


getMinY

public double getMinY()
Returns the minimum y-value in this series. Since the value could appear aywhere along the x-axis, each point needs to be examined, lookup is slower the larger the dataset.

Note: An alternative would be to check for the min value every time a point is inserted and store the miny value. This would only slightly slow down the insert, but greatly speed up the lookup.


getMaxY

public double getMaxY()
Returns the maximum y-value in this series. Since the value could appear aywhere along the x-axis, each point needs to be examined, lookup is slower the larger the dataset.

Note: An alternative would be to check for the min value every time a point is inserted and store the miny value. This would only slightly slow down the insert, but greatly speed up the lookup.


getXindexForMaxY

public int getXindexForMaxY()
Returns the x index for the maximum y-value in this series. Since the value could appear aywhere along the x-axis, each point needs to be examined, lookup is slower the larger the dataset.


get

public Point2D get(int index)
Returns an x and y value in a Point2D based on index into the y-points array. The index is based along the x-axis.


getX

public double getX(int index)
Returns the ith x element in this function. Returns null if index is negative or greater than number of points. The index is based along the x-axis.


getY

public double getY(int index)
Returns the ith y element in this function. Returns null if index is negative or greater than number of points. The index is based along the x-axis.


getY

public double getY(double x)
Returns they-value associated with this x-value. First the index of the x-value is calculated, within tolerance. Then they value is obtained by it's index into the storage array. Returns null if x is not one of the x-axis points.


getXIndex

public int getXIndex(double x)
Returns the index of the supplied value provided it's within the tolerance of one of the discretized values.

See Also:
getClosestXIndex(double)

getClosestXIndex

public int getClosestXIndex(double x)
Returns the index of the supplied value (ignoring tolerance). It should be noted that this method uses a very small internal scale factor to provide accurate results. Double precision errors can result in x-values that fall on the boundary between adjacent function values. This may cause the value to be associated with the index below, when in fact boundary values should be associated with the index above. This is the convention followed in other data analysis software (e.g. Matlab). Values well outside the range spanned by the function are associated with index of the min or max function value as appropriate.


set

public void set(Point2D point)
Calls set( x value, y value ). An IllegalArgumentException is thrown if the x value is not an x-axis point.


set

public void set(double x,
                double y)
Sets the y-value at a specified index. The x-value index is first calculated, then the y-value is set in it's array. A DataPoint2DException is thrown if the x value is not an x-axis point.


add

public void add(double x,
                double y)
This method can be used for generating histograms if tolerance is set greater than delta. Adds to the y-value at a specified index. The x-value index is first calculated, then the y-value is added in it's array. The specified x value is the mid-point of the histogram interval. IllegalArgumentException is thrown if the x value is not an x-axis point.


set

public void set(int index,
                double y)
this function will throw an exception if the index is not within the range of 0 to num -1


add

public void add(int index,
                double y)
This method can be used for generating histograms if tolerance is set greater than delta. Adds to the y-value at a specified index. The specified x value is the mid-point of the histogram interval. this function will throw an exception if the index is not within the range of 0 to num -1


getPointsIterator

public Iterator<Point2D> getPointsIterator()
This function may be slow if there are many points in the list. It has to reconstitute all the Point2D x-values by index, only y values are stored internally in this function type. A Point2D is built for each y value and added to a local ArrayList. Then the iterator of the local ArrayList is returned.


getXIndexBefore

protected int getXIndexBefore(double x)
Description copied from class: AbstractDiscretizedFunc
Returns the x index that is before the given X value. If a point exists at this x value, the index before that point should be returned. Return value is undefined if x < minX or x > maxX, error checking should be done externally.

Returns:

getClosestYtoX

public double getClosestYtoX(double x)
Description copied from interface: XY_DataSet
Get the Y value for the point with closest X. If multiple points are equidistant, the smaller X will be returned.

Specified by:
getClosestYtoX in interface XY_DataSet
Overrides:
getClosestYtoX in class AbstractXY_DataSet
Returns:

deepClone

public EvenlyDiscretizedFunc deepClone()
Returns a copy of this and all points in this DiscretizedFunction. A copy, or clone has all values the same, but is a different java class instance. That means you can change the copy without affecting the original instance.

This is a deep clone so all fields and all data points are copies.


equalXValues

public boolean equalXValues(DiscretizedFunc function)
Determines if two functions are the same by comparing that each point x value is the same, within tolerance


areAllXValuesInteger

public boolean areAllXValuesInteger(double tolerance)
It finds out whether the X values are within tolerance of an integer value

Specified by:
areAllXValuesInteger in interface XY_DataSet
Overrides:
areAllXValuesInteger in class AbstractXY_DataSet
Parameters:
tol - tolerance value to consider rounding errors
Returns:
true if all X values are within the tolerance of an integer value else returns false

equalXAndYValues

public boolean equalXAndYValues(DiscretizedFunc function)
Determines if two functions are the same by comparing that each point x value is the same, within tolerance, and that each y value is the same, including nulls.


toString

public String toString()
Standard java function, usually used for debugging, prints out the state of the list, such as number of points, the value of each point, etc.

Specified by:
toString in interface XY_DataSet
Overrides:
toString in class Object
Returns:

getMetadataString

public String getMetadataString()
Description copied from interface: XY_DataSet
prints out the state of the list, such as number of points, the value of each point, etc.

Returns:
value of each point in the function in String format

getIndex

public int getIndex(Point2D point)
Returns the index of this DataPoint based on it's x any y value both the x-value and y-values in list should match with that of point returns -1 if there is no such value in the list