org.opensha.commons.data.function
Class ArbitrarilyDiscretizedFunc

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.ArbitrarilyDiscretizedFunc
All Implemented Interfaces:
Serializable, Iterable<Point2D>, DiscretizedFunc, XY_DataSet, Named, PlotElement, XMLSaveable
Direct Known Subclasses:
ArbDiscrEmpiricalDistFunc, ArbDiscrFuncWithParams

public class ArbitrarilyDiscretizedFunc
extends AbstractDiscretizedFunc
implements Serializable

Title: ArbitrarilyDiscretizedFunc

Description: This class is a sublcass implementation of a DiscretizedFunc that stores the data internaly as a sorted TreeMap of DataPoint2D. This subclass distinguishes itself by the fact that it assumes no spacing interval along the x-axis. Consecutive points can be spread out or bunched up in no predicatable order. For at least the default comparator (DataPoint2DComparator), the tolerance determines whether the set() methods add the point (if x value is more than tolerance away from that of all existing points) or whether they replace an existing point (if within tolerance). A tolerance of less than about 1e-16 is effectively about 1e-16 due to the numerical precision of floating point arithmetic (1.0 - (1.0+1e-16) = 1.0).

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

Field Summary
protected static String C
           
protected static boolean D
           
protected  Point2DToleranceSortedList points
          The set of DataPoints2D that conprise the discretized function.
 
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
ArbitrarilyDiscretizedFunc()
          No-Arg Constructor that uses the default DataPoint2DToleranceComparator comparator.
ArbitrarilyDiscretizedFunc(AbstractDiscretizedFunc func)
          Creates an ArbitrarilyDiscretizedFunc from an DiscretizedFunc
ArbitrarilyDiscretizedFunc(Point2DComparator comparator)
          Constructor that takes a Point2D Comparator.
ArbitrarilyDiscretizedFunc(Point2DToleranceSortedList points)
           
ArbitrarilyDiscretizedFunc(String name)
          Creates a default arbitrarily discretized function with the given name
 
Method Summary
 void clear()
          Clear all the X and Y values from this function
 ArbitrarilyDiscretizedFunc deepClone()
          This function returns a new copy of this list, including copies of all the points.
 boolean equalXValues(DiscretizedFunc function)
          Determines if two functions are the same by comparing that each point x value is the same.
 Point2D get(int index)
          Returns the nth (x,y) point in the Function, else null if this index point doesn't exist
 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 imput 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 Y value given an x value - within tolerance, returns null if not found
 double getInterpExterpY_inLogYDomain(double x)
           
 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)
          Given the imput x value, finds the two sequential x values with the closest x values, then calculates an interpolated y value for this x value, fitted to the curve.
 double getMaxX()
          return the maximum x value along the x-axis.
 double getMaxY()
          Return the maximum y value along the y-axis.
 String getMetadataString()
          prints out the state of the list, such as number of points, the value of each point, etc.
 double getMinX()
          return the minimum x value along the x-axis.
 double getMinY()
          Return the minimum y value along the y-axis.
 int getNum()
          returns the number of points in this function list
 Iterator<Point2D> getPointsIterator()
          Returns an iterator over all datapoints in the list.
 double getX(int index)
          Returns the x value of a point given the index
 int getXIndex(double x)
          Returns the x value of a point given the index or -1 if not found
 double[] getXVals()
           
 double getY(double x)
          returns the Y value given an x value - within tolerance, returns null if not found
 double getY(int index)
          Returns the y value of a point given the index
 double[] getYVals()
           
 ArbitrarilyDiscretizedFunc getYY_Function(DiscretizedFunc function)
          This function creates a new ArbitrarilyDiscretizedFunc whose X values are the Y values of the calling function and Y values are the Y values of the function passed as argument.
 boolean hasPoint(double x, double y)
          Determinces if a DataPoit2D exists in the treemap base on it's x value lookup.
 boolean hasPoint(Point2D point)
          Determinces if a DataPoit2D exists in the treemap base on it's x value lookup.
 Iterator<Point2D> iterator()
           
static void main(String[] args)
           
 void set(double x, double y)
          Either adds a new DataPoint, or replaces an existing one, within tolerance, created from the input x and y values.
 void set(int index, double y)
          Replaces a y value for an existing point, accessed by index.
 void set(Point2D point)
          Either adds a new DataPoint, or replaces an existing one, within tolerance
 void setTolerance(double newTolerance)
          Sets the tolerance of this function.
 String toDebugString()
          Almost the same as toString() but used specifically in a debugging context.
 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.
 
Methods inherited from class org.opensha.commons.data.function.AbstractDiscretizedFunc
calcSumOfY_Vals, equals, fromXMLMetadata, getTolerance, loadFuncFromSimpleFile, loadFuncFromSimpleFile, scale, toXMLMetadata, toXMLMetadata, writeSimpleFuncFile, writeSimpleFuncFile
 
Methods inherited from class org.opensha.commons.data.function.AbstractXY_DataSet
areAllXValuesInteger, getClosestX, getClosestY, getDatasetsToPlot, getInfo, getName, getPlotNumColorList, getXAxisName, getXValuesIterator, getYAxisName, getYValuesIterator, 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
areAllXValuesInteger, getClosestX, getClosestY, 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
 

Field Detail

C

protected static final String C
See Also:
Constant Field Values

D

protected static final boolean D
See Also:
Constant Field Values

points

protected Point2DToleranceSortedList points
The set of DataPoints2D that conprise the discretized function. These are stored in a Point2D TreeMap so they are sorted on the X-Values.

This TreeMap will not allow identical DataPoint2D. A comparator and equals() is used to determine equality. Since you can specify any comparator you want, this ArbitrarilyDiscretizedFunc can be adopted for most purposes.

Note: SWR: I had to make a special org.opensha. version of the Java TreeMap and subclass DataPoint2DTreeMap to access internal objects in the Java TreeMap. Java's Treemap had internal objects hidden as private, I exposed them to subclasses by making them protected in org.opensha.data.TreeMap. This was neccessary for index access to the points in the TreeMap. Seems like a poor oversight on the part of Java.

Constructor Detail

ArbitrarilyDiscretizedFunc

public ArbitrarilyDiscretizedFunc(AbstractDiscretizedFunc func)
Creates an ArbitrarilyDiscretizedFunc from an DiscretizedFunc

Parameters:
func -

ArbitrarilyDiscretizedFunc

public ArbitrarilyDiscretizedFunc(Point2DComparator comparator)
Constructor that takes a Point2D Comparator. The comparator is used for sorting the DataPoint2D. Using the no-arg constructor instantiates the default Comparator that compares only x-values within tolerance to determine if two points are equal.

The passed in comparator must be an implementor of DataPoint2DComparatorAPI. These comparators know they are dealing with a Point2D and usually only compare the x-values for sorting. Special comparators may wish to sort on both the x and y values, i.e. the data points are geographical locations.


ArbitrarilyDiscretizedFunc

public ArbitrarilyDiscretizedFunc()
No-Arg Constructor that uses the default DataPoint2DToleranceComparator comparator. The comparator is used for sorting the DataPoint2D. This default Comparator compares only x-values within tolerance to determine if two points are equal.

The default tolerance of 0 is used. This means that two x-values must be exactly equal doubles to be considered equal.


ArbitrarilyDiscretizedFunc

public ArbitrarilyDiscretizedFunc(String name)
Creates a default arbitrarily discretized function with the given name

Parameters:
name -

ArbitrarilyDiscretizedFunc

public ArbitrarilyDiscretizedFunc(Point2DToleranceSortedList points)
Method Detail

setTolerance

public void setTolerance(double newTolerance)
                  throws InvalidRangeException
Sets the tolerance of this function. Overides the default function in the abstract class in that it calls setTolerance in the tree map which updates the comparator in there. These field getters and setters provide the basic information to describe a function. All functions have a name, information string, and a tolerance level that specifies how close two points have to be along the x axis to be considered equal. A tolerance of less than about 1e-16 is effectively about 1e-16 due to the numerical precision of floating point arithmetic (1.0 - (1.0+1e-16) = 1.0).

Specified by:
setTolerance in interface DiscretizedFunc
Overrides:
setTolerance in class AbstractDiscretizedFunc
Throws:
InvalidRangeException

getNum

public int getNum()
returns the number of points in this function list

Specified by:
getNum in interface XY_DataSet

getMinX

public double getMinX()
return the minimum x value along the x-axis. Since the values are sorted this is a very quick lookup

Specified by:
getMinX in interface XY_DataSet

getMaxX

public double getMaxX()
return the maximum x value along the x-axis. Since the values are sorted this is a very quick lookup

Specified by:
getMaxX in interface XY_DataSet

getMinY

public double getMinY()
Return the minimum y value along the y-axis. This value is calculated every time a Point2D is added to the list and cached as a variable so this function returns very quickly. Slows down adding new points slightly. I assume that most of the time these lists will be created once, then used for plotting and in other functions, in other words more lookups than inserts.

Specified by:
getMinY in interface XY_DataSet

getMaxY

public double getMaxY()
Return the maximum y value along the y-axis. This value is calculated every time a Point2D is added to the list and cached as a variable so this function returns very quickly. Slows down adding new points slightly. I assume that most of the time these lists will be created once, then used for plotting and in other functions, in other words more lookups than inserts.

Specified by:
getMaxY in interface XY_DataSet

get

public Point2D get(int index)
Returns the nth (x,y) point in the Function, else null if this index point doesn't exist

Specified by:
get in interface XY_DataSet

getX

public double getX(int index)
Returns the x value of a point given the index

Specified by:
getX in interface XY_DataSet

getY

public double getY(int index)
Returns the y value of a point given the index

Specified by:
getY in interface XY_DataSet

getY

public double getY(double x)
returns the Y value given an x value - within tolerance, returns null if not found

Specified by:
getY in interface DiscretizedFunc

getIndex

public int getIndex(Point2D point)
returns the Y value given an x value - within tolerance, returns null if not found

Specified by:
getIndex in interface DiscretizedFunc

getXIndex

public int getXIndex(double x)
Returns the x value of a point given the index or -1 if not found

Specified by:
getXIndex in interface DiscretizedFunc

set

public void set(Point2D point)
         throws Point2DException
Either adds a new DataPoint, or replaces an existing one, within tolerance

Specified by:
set in interface XY_DataSet
Throws:
Point2DException

set

public void set(double x,
                double y)
         throws Point2DException
Either adds a new DataPoint, or replaces an existing one, within tolerance, created from the input x and y values.

Specified by:
set in interface XY_DataSet
Throws:
Point2DException

set

public void set(int index,
                double y)
         throws Point2DException
Replaces a y value for an existing point, accessed by index. If no DataPoint exists nothing is done.

Specified by:
set in interface XY_DataSet
Throws:
Point2DException

hasPoint

public boolean hasPoint(Point2D point)
Determinces if a DataPoit2D exists in the treemap base on it's x value lookup. Returns true if found, else false if point not in list.

Specified by:
hasPoint in interface XY_DataSet

hasPoint

public boolean hasPoint(double x,
                        double y)
Determinces if a DataPoit2D exists in the treemap base on it's x value lookup. Returns true if found, else false if point not in list.

Specified by:
hasPoint in interface XY_DataSet

getPointsIterator

public Iterator<Point2D> getPointsIterator()
Returns an iterator over all datapoints in the list. Results returned in sorted order. Returns null if no points present.

Returns:

iterator

public Iterator<Point2D> iterator()
Specified by:
iterator in interface Iterable<Point2D>
Overrides:
iterator in class AbstractXY_DataSet

getFirstInterpolatedX

public double getFirstInterpolatedX(double y)
Given the imput 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.

Specified by:
getFirstInterpolatedX in interface DiscretizedFunc
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.

Specified by:
getFirstInterpolatedX_inLogXLogYDomain in interface DiscretizedFunc
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)
Given the imput x value, finds the two sequential x values with the closest x values, then calculates an interpolated y value for this x value, fitted to the curve.

Specified by:
getInterpolatedY in interface DiscretizedFunc
Parameters:
x(value - for which interpolated first y value has to be found
Returns:
y(this is the interpolated x based on the given x value)

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. If both bounding y values are zero, then zero is returned. If only one of the bounding y values is zero, that value is converted to Double.MIN_VALUE. If the interpolated y value is Double.MIN_VALUE, it is converted to 0.0.

Specified by:
getInterpolatedY_inLogXLogYDomain in interface DiscretizedFunc
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-y space. The Y value returned is in the linear space.

Specified by:
getInterpolatedY_inLogYDomain in interface DiscretizedFunc
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)

getInterpExterpY_inLogYDomain

public double getInterpExterpY_inLogYDomain(double x)

deepClone

public ArbitrarilyDiscretizedFunc deepClone()
This function returns a new copy of this list, including copies of all the points. A shallow clone would only create a new DiscretizedFunc instance, but would maintain a reference to the original points.

Since this is a clone, you can modify it without changing the original.

Specified by:
deepClone in interface DiscretizedFunc
Specified by:
deepClone in interface XY_DataSet
Returns:

equalXValues

public boolean equalXValues(DiscretizedFunc function)
Determines if two functions are the same by comparing that each point x value is the same. This requires the two lists to have the same number of points.


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.

Specified by:
getMetadataString in interface XY_DataSet
Returns:
value of each point in the function in String format

toDebugString

public String toDebugString()
Almost the same as toString() but used specifically in a debugging context. Formatted slightly different

Returns:

getYY_Function

public ArbitrarilyDiscretizedFunc getYY_Function(DiscretizedFunc function)
This function creates a new ArbitrarilyDiscretizedFunc whose X values are the Y values of the calling function and Y values are the Y values of the function passed as argument.

Parameters:
function - DiscretizedFuncAPI function whose Y values will the Y values of the new ArbitrarilyDiscretizedFunc.
Returns:
ArbitrarilyDiscretizedFunc new ArbitrarilyDiscretizedFunc

clear

public void clear()
Clear all the X and Y values from this function


getXVals

public double[] getXVals()

getYVals

public double[] getYVals()

main

public static void main(String[] args)