gov.usgs.earthquake.nshmp.data

Class Interpolator

java.lang.Object

gov.usgs.earthquake.nshmp.data.Interpolator

public abstract class Interpolator
extends Object

Utility class to perform linear and log interpolations. The methods of this class are designed to be fast and, as such, perform very little argument checking for monotonicity and the like.

Making some assumptions, interpolation is fairly straightforward. Most of the methods implemented here are designed to support interpolation (or derivation) of y-values keyed to monotonically increasing x-values. x-value interpolation is somewhat thornier. Assumptions and behaviors:

• No error checking for null, empty, single-valued arrays; or arrays of different lengths is performed. Buyer beware.
• X-value arrays are always assumed to be strictly monotonically ascending (no repeated values)
• Internally, binary search is used for y-value interpolation; linear search is used for x-value interpolation.
• Y-value interpolation will always extrapolate off the ends a sequence; this may change, or be configurable, in the future.
• X-value interpolation is predicated on x-values representing some form of cumulative distribution function, either increasing or decreasing (complementary), and must be specified as such. X-values are assumed to be increasing by default.
• X-value interpolation never extrapolates off the ends of a sequence and will always return 0 for out-of-range targets.

Presently, only single value interpolation of x-values is supported. The more common use case is to resample a sequence of y-values, which is supported.

Two static methods, findX(double, double, double, double, double) and findY(double, double, double, double, double), are the basis for all interpolation operations in this class. These two methods are point-order agnostic. TODO example; explain array swapping techniques for x-interpolation

Author:

Peter Powers

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Interpolator.Builder

Method Summary

Modifier and Type	Method and Description
static Interpolator.Builder	builder()
abstract double	findX(double[] xs, double[] ys, double y) Return an interpolated x-value corresponding to the supplied y-value in the supplied x- and y-value arrays.
static double	findX(double x1, double y1, double x2, double y2, double y) Return an interpolated or extrapolated x-value corresponding to the supplied y-value.
abstract double	findX(List<Double> xs, List<Double> ys, double y) Return an interpolated x-value corresponding to the supplied y-value in the supplied x- and y-value arrays.
abstract double	findX(XySequence xys, double y) Return an interpolated x-value corresponding to the supplied y-value in the supplied xy-sequence.
abstract double	findY(double[] xs, double[] ys, double x) Return an interpolated or extrapolated y-value corresponding to the supplied x-value in the supplied x- and y-value arrays.
abstract double[]	findY(double[] xs, double[] ys, double[] x) Return interpolated or extrapolated y-values using the supplied x- and y-value arrays.
static double	findY(double x1, double y1, double x2, double y2, double x) Return an interpolated or extrapolated y-value corresponding to the supplied x-value.
abstract double	findY(List<Double> xs, List<Double> ys, double x) Return an interpolated or extrapolated y-value corresponding to the supplied x-value in the supplied x- and y-value arrays.
abstract double[]	findY(List<Double> xs, List<Double> ys, double[] x) Return interpolated or extrapolated y-values using the supplied x- and y-value arrays.
abstract double	findY(XySequence xys, double x) Return an interpolated or extrapolated y-value corresponding to the supplied x-value in the supplied xy-sequence.
abstract double[]	findY(XySequence xys, double[] x) Return interpolated or extrapolated y-values using the supplied x- and y-value arrays.

Methods inherited from class java.lang.Object

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

Method Detail

findX

public static double findX(double x1,
                           double y1,
                           double x2,
                           double y2,
                           double y)

Return an interpolated or extrapolated x-value corresponding to the supplied y-value. If any supplied value is NaN, returned value will also be NaN. Method does not perform any input validation such that if the supplied points are coincident or define a horizontal line, the method may return Infinity, -Infinity, or NaN.

Parameters:

x1 - x-value of first point

y1 - y-value of first point

x2 - x-value of second point

y2 - y-value of second point

y - value at which to find x

Returns:

the interpolated x-value

findX

public abstract double findX(double[] xs,
                             double[] ys,
                             double y)

Return an interpolated x-value corresponding to the supplied y-value in the supplied x- and y-value arrays.

Parameters:

xs - x-values of a sequence

ys - y-values of a sequence

y - value at which to find x

Returns:

an interpolated x-value

findX

public abstract double findX(List<Double> xs,
                             List<Double> ys,
                             double y)

Return an interpolated x-value corresponding to the supplied y-value in the supplied x- and y-value arrays.

Parameters:

xs - x-values of a sequence

ys - y-values of a sequence

y - value at which to find x

Returns:

an interpolated x-value

findX

public abstract double findX(XySequence xys,
                             double y)

Return an interpolated x-value corresponding to the supplied y-value in the supplied xy-sequence.

Parameters:

xys - an xy-sequence

y - value at which to find x

Returns:

an interpolated x-value

findY

public static double findY(double x1,
                           double y1,
                           double x2,
                           double y2,
                           double x)

Return an interpolated or extrapolated y-value corresponding to the supplied x-value. If any supplied value is NaN, returned value will also be NaN. Method does not perform any input validation such that if the supplied points are coincident or define a vertical line, the method may return Infinity, -Infinity, or NaN.

Parameters:

x1 - x-value of first point

y1 - y-value of first point

x2 - x-value of second point

y2 - y-value of second point

x - value at which to find y

Returns:

an interpolated y-value

findY

public abstract double findY(double[] xs,
                             double[] ys,
                             double x)

Return an interpolated or extrapolated y-value corresponding to the supplied x-value in the supplied x- and y-value arrays.

Parameters:

xs - x-values of a sequence

ys - y-values of a sequence

x - value at which to find y

Returns:

an interpolated y-value

findY

public abstract double findY(List<Double> xs,
                             List<Double> ys,
                             double x)

Return an interpolated or extrapolated y-value corresponding to the supplied x-value in the supplied x- and y-value arrays.

Parameters:

xs - x-values of a sequence

ys - y-values of a sequence

x - value at which to find y

Returns:

an interpolated y-value

findY

public abstract double findY(XySequence xys,
                             double x)

Return an interpolated or extrapolated y-value corresponding to the supplied x-value in the supplied xy-sequence.

Parameters:

xys - an xy-sequence

x - value at which to find y

Returns:

an interpolated y-value

findY

public abstract double[] findY(double[] xs,
                               double[] ys,
                               double[] x)

Return interpolated or extrapolated y-values using the supplied x- and y-value arrays.

Parameters:

xs - x-values of a sequence

ys - y-values of a sequence

x - values at which to find y-values

Returns:

interpolated y-values

findY

public abstract double[] findY(List<Double> xs,
                               List<Double> ys,
                               double[] x)

Return interpolated or extrapolated y-values using the supplied x- and y-value arrays.

Parameters:

xs - x-values of a sequence

ys - y-values of a sequence

x - values at which to find y-values

Returns:

interpolated y-values

findY

public abstract double[] findY(XySequence xys,
                               double[] x)

Return interpolated or extrapolated y-values using the supplied x- and y-value arrays.

Parameters:

xys - an xy-sequence

x - values at which to find y-values

Returns:

interpolated y-values

builder

public static Interpolator.Builder builder()