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
 DiscretizedFunc 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.
 ArrayList<Double> getAllInterpolatedX(double y)
          Given the input y value, finds all interpolated x-axis values where y equals the given value (using linear interpolation between neighboring points).
 int getClosestXIndex(double x)
          Returns the index of the supplied value (ignoring tolerance).
 double getClosestY(double x)
          Get the Y value for the point with closest X
 double getDelta()
          Returns the spacing between x-values
 double getFirstInterpolatedX_afterXindex(double y, int xIndex)
          Given the input y value, finds the two sequential x values with the closest y values, then calculates an interpolated x value for this y value, fitted to the curve.
 double getFirstInterpolatedX_inLogXLogYDomain(double y)
          Given the input y value, finds the two sequential x values with the closest y values, then calculates an interpolated x value for this y value, fitted to the curve.
 double getFirstInterpolatedX(double y)
          Given the input y value, finds the two sequential x values with the closest y values, then calculates an interpolated x value for this y value, fitted to the curve.
 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 getInterpolatedY_inLogXLogYDomain(double x)
          This function interpolates the y-axis value corresponding to the given value of x.
 double getInterpolatedY_inLogYDomain(double x)
          This function interpolates the y-axis value corresponding to the given value of x.
 double getInterpolatedY(double x)
          This function interpolates the y-axis value corresponding to the given value of x
 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.
 int getNum()
          Returns the number of points 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.
 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.
 boolean hasPoint(double x, double y)
          Returns true if the x value is withing tolerance of an x-value in this list, and the y value is equal to y value in the list.
 boolean hasPoint(Point2D point)
          Returns true if the x value is withing tolerance of an x-value in this list, and the y value is equal to y value in the list.
 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 ).
 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, getTolerance, loadFuncFromSimpleFile, loadFuncFromSimpleFile, scale, setTolerance, toXMLMetadata, toXMLMetadata, writeSimpleFuncFile, writeSimpleFuncFile
 
Methods inherited from class org.opensha.commons.data.function.AbstractXY_DataSet
getClosestX, 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
getClosestX, 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


getNum

public int getNum()
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)
              throws Point2DException
Returns the index of the supplied value provided it's within the tolerance of one of the discretized values.

Throws:
Point2DException
See Also:
getClosestXIndex(double)

getClosestXIndex

public int getClosestXIndex(double x)
                     throws Point2DException
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.

Throws:
Point2DException

set

public void set(Point2D point)
         throws Point2DException
Calls set( x value, y value ). A DataPoint2DException is thrown if the x value is not an x-axis point.

Throws:
Point2DException

set

public void set(double x,
                double y)
         throws Point2DException
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.

Throws:
Point2DException

add

public void add(double x,
                double y)
         throws Point2DException
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. DataPoint2DException is thrown if the x value is not an x-axis point.

Throws:
Point2DException

set

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

Throws:
Point2DException

add

public void add(int index,
                double y)
         throws Point2DException
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

Throws:
Point2DException

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.


getFirstInterpolatedX

public double getFirstInterpolatedX(double y)
Given the input y value, finds the two sequential x values with the closest y values, then calculates an interpolated x value for this y value, fitted to the curve.

Since there may be multiple y values with the same value, this function just matches the first found.

Parameters:
y(value - for which interpolated first x value has to be found
Returns:
x(this is the interpolated x based on the given y value)

getAllInterpolatedX

public ArrayList<Double> getAllInterpolatedX(double y)
Given the input y value, finds all interpolated x-axis values where y equals the given value (using linear interpolation between neighboring points). Values are increasing in x and the list is empty if none are found.

Parameters:
y(value - for which interpolated first x value has to be found
Returns:
ArrayList of interpolated x-axis values

getFirstInterpolatedX_afterXindex

public double getFirstInterpolatedX_afterXindex(double y,
                                                int xIndex)
Given the input y value, finds the two sequential x values with the closest y values, then calculates an interpolated x value for this y value, fitted to the curve. This is only done after the given xIndex (and not including)

Since there may be multiple y values with the same value, this function just matches the first found.

Parameters:
y(value - for which interpolated first x value has to be found
Returns:
x(this is the interpolated x based on the given y value)

getFirstInterpolatedX_inLogXLogYDomain

public double getFirstInterpolatedX_inLogXLogYDomain(double y)
Given the input y value, finds the two sequential x values with the closest y values, then calculates an interpolated x value for this y value, fitted to the curve. The interpolated Y value returned is in the linear space but the interpolation is done in the log space. Since there may be multiple y values with the same value, this function just matches the first found starting at the x-min point along the x-axis.

Parameters:
y - : Y value in the linear space coressponding to which we are required to find the interpolated x value in the log space.
Returns:
x(this is the interpolated x based on the given y value)

getInterpolatedY

public double getInterpolatedY(double x)
This function interpolates the y-axis value corresponding to the given value of x

Parameters:
x(value - for which interpolated first y value has to be found
Returns:
y(this is the interpolated y based on the given x value)

getClosestY

public double getClosestY(double x)
Description copied from interface: XY_DataSet
Get the Y value for the point with closest X

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

getInterpolatedY_inLogXLogYDomain

public double getInterpolatedY_inLogXLogYDomain(double x)
This function interpolates the y-axis value corresponding to the given value of x. the interpolation of the Y value is done in the log space for x and y values. The Y value returned is in the linear space but the interpolation is done in the log space.

Parameters:
x - : X value in the linear space corresponding to which we are required to find the interpolated y value in log space.
Returns:
y(this is the interpolated y in linear space based on the given x value)

getInterpolatedY_inLogYDomain

public double getInterpolatedY_inLogYDomain(double x)
This function interpolates the y-axis value corresponding to the given value of x. the interpolation of the Y value is done in the log space y values. The Y value returned is in the linear space but the interpolation is done in the log space.

Parameters:
x - : X value in the linear space corresponding to which we are required to find the interpolated y value in log space.
Returns:
y(this is the interpolated y in linear space based on the given x value)

deepClone

public DiscretizedFunc 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

hasPoint

public boolean hasPoint(Point2D point)
Returns true if the x value is withing tolerance of an x-value in this list, and the y value is equal to y value in the list.


hasPoint

public boolean hasPoint(double x,
                        double y)
Returns true if the x value is withing tolerance of an x-value in this list, and the y value is equal to y value in the list.


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