org.opensha.commons.data.function
Class ArbitrarilyDiscretizedFunc

java.lang.Object
  org.opensha.commons.data.function.AbstractXY_DataSet
      org.opensha.commons.data.function.AbstractDiscretizedFunc
          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)