org.apache.commons.math3.analysis.interpolation
Class LoessInterpolator

java.lang.Object
  extended by org.apache.commons.math3.analysis.interpolation.LoessInterpolator
All Implemented Interfaces:
java.io.Serializable, UnivariateInterpolator

public class LoessInterpolator
extends java.lang.Object
implements UnivariateInterpolator, java.io.Serializable

Implements the Local Regression Algorithm (also Loess, Lowess) for interpolation of real univariate functions.

For reference, see William S. Cleveland - Robust Locally Weighted Regression and Smoothing Scatterplots

This class implements both the loess method and serves as an interpolation adapter to it, allowing one to build a spline on the obtained loess fit.

Since:
2.0
Version:
$Id: LoessInterpolator.java 1379904 2012-09-01 23:54:52Z erans $
See Also:
Serialized Form

Field Summary
private  double accuracy
          If the median residual at a certain robustness iteration is less than this amount, no more iterations are done.
private  double bandwidth
          The bandwidth parameter: when computing the loess fit at a particular point, this fraction of source points closest to the current point is taken into account for computing a least-squares regression.
static double DEFAULT_ACCURACY
          Default value for accuracy.
static double DEFAULT_BANDWIDTH
          Default value of the bandwidth parameter.
static int DEFAULT_ROBUSTNESS_ITERS
          Default value of the number of robustness iterations.
private  int robustnessIters
          The number of robustness iterations parameter: this many robustness iterations are done.
private static long serialVersionUID
          serializable version identifier.
 
Constructor Summary
LoessInterpolator()
          Constructs a new LoessInterpolator with a bandwidth of DEFAULT_BANDWIDTH, DEFAULT_ROBUSTNESS_ITERS robustness iterations and an accuracy of {#link #DEFAULT_ACCURACY}.
LoessInterpolator(double bandwidth, int robustnessIters)
          Construct a new LoessInterpolator with given bandwidth and number of robustness iterations.
LoessInterpolator(double bandwidth, int robustnessIters, double accuracy)
          Construct a new LoessInterpolator with given bandwidth, number of robustness iterations and accuracy.
 
Method Summary
private static void checkAllFiniteReal(double[] values)
          Check that all elements of an array are finite real numbers.
 PolynomialSplineFunction interpolate(double[] xval, double[] yval)
          Compute an interpolating function by performing a loess fit on the data at the original abscissae and then building a cubic spline with a SplineInterpolator on the resulting fit.
private static int nextNonzero(double[] weights, int i)
          Return the smallest index j such that j > i && (j == weights.length || weights[j] != 0).
 double[] smooth(double[] xval, double[] yval)
          Compute a loess fit on the data at the original abscissae.
 double[] smooth(double[] xval, double[] yval, double[] weights)
          Compute a weighted loess fit on the data at the original abscissae.
private static double tricube(double x)
          Compute the tricube weight function
private static void updateBandwidthInterval(double[] xval, double[] weights, int i, int[] bandwidthInterval)
          Given an index interval into xval that embraces a certain number of points closest to xval[i-1], update the interval so that it embraces the same number of points closest to xval[i], ignoring zero weights.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_BANDWIDTH

public static final double DEFAULT_BANDWIDTH
Default value of the bandwidth parameter.

See Also:
Constant Field Values

DEFAULT_ROBUSTNESS_ITERS

public static final int DEFAULT_ROBUSTNESS_ITERS
Default value of the number of robustness iterations.

See Also:
Constant Field Values

DEFAULT_ACCURACY

public static final double DEFAULT_ACCURACY
Default value for accuracy.

Since:
2.1
See Also:
Constant Field Values

serialVersionUID

private static final long serialVersionUID
serializable version identifier.

See Also:
Constant Field Values

bandwidth

private final double bandwidth
The bandwidth parameter: when computing the loess fit at a particular point, this fraction of source points closest to the current point is taken into account for computing a least-squares regression.

A sensible value is usually 0.25 to 0.5.


robustnessIters

private final int robustnessIters
The number of robustness iterations parameter: this many robustness iterations are done.

A sensible value is usually 0 (just the initial fit without any robustness iterations) to 4.


accuracy

private final double accuracy
If the median residual at a certain robustness iteration is less than this amount, no more iterations are done.

Constructor Detail

LoessInterpolator

public LoessInterpolator()
Constructs a new LoessInterpolator with a bandwidth of DEFAULT_BANDWIDTH, DEFAULT_ROBUSTNESS_ITERS robustness iterations and an accuracy of {#link #DEFAULT_ACCURACY}. See LoessInterpolator(double, int, double) for an explanation of the parameters.


LoessInterpolator

public LoessInterpolator(double bandwidth,
                         int robustnessIters)
Construct a new LoessInterpolator with given bandwidth and number of robustness iterations.

Calling this constructor is equivalent to calling {link LoessInterpolator(bandwidth, robustnessIters, LoessInterpolator.DEFAULT_ACCURACY)

Parameters:
bandwidth - when computing the loess fit at a particular point, this fraction of source points closest to the current point is taken into account for computing a least-squares regression.
A sensible value is usually 0.25 to 0.5, the default value is DEFAULT_BANDWIDTH.
robustnessIters - This many robustness iterations are done.
A sensible value is usually 0 (just the initial fit without any robustness iterations) to 4, the default value is DEFAULT_ROBUSTNESS_ITERS.
See Also:
LoessInterpolator(double, int, double)

LoessInterpolator

public LoessInterpolator(double bandwidth,
                         int robustnessIters,
                         double accuracy)
                  throws OutOfRangeException,
                         NotPositiveException
Construct a new LoessInterpolator with given bandwidth, number of robustness iterations and accuracy.

Parameters:
bandwidth - when computing the loess fit at a particular point, this fraction of source points closest to the current point is taken into account for computing a least-squares regression.
A sensible value is usually 0.25 to 0.5, the default value is DEFAULT_BANDWIDTH.
robustnessIters - This many robustness iterations are done.
A sensible value is usually 0 (just the initial fit without any robustness iterations) to 4, the default value is DEFAULT_ROBUSTNESS_ITERS.
accuracy - If the median residual at a certain robustness iteration is less than this amount, no more iterations are done.
Throws:
OutOfRangeException - if bandwidth does not lie in the interval [0,1].
NotPositiveException - if robustnessIters is negative.
Since:
2.1
See Also:
LoessInterpolator(double, int)
Method Detail

interpolate

public final PolynomialSplineFunction interpolate(double[] xval,
                                                  double[] yval)
                                           throws NonMonotonicSequenceException,
                                                  DimensionMismatchException,
                                                  NoDataException,
                                                  NotFiniteNumberException,
                                                  NumberIsTooSmallException
Compute an interpolating function by performing a loess fit on the data at the original abscissae and then building a cubic spline with a SplineInterpolator on the resulting fit.

Specified by:
interpolate in interface UnivariateInterpolator
Parameters:
xval - the arguments for the interpolation points
yval - the values for the interpolation points
Returns:
A cubic spline built upon a loess fit to the data at the original abscissae
Throws:
NonMonotonicSequenceException - if xval not sorted in strictly increasing order.
DimensionMismatchException - if xval and yval have different sizes.
NoDataException - if xval or yval has zero size.
NotFiniteNumberException - if any of the arguments and values are not finite real numbers.
NumberIsTooSmallException - if the bandwidth is too small to accomodate the size of the input data (i.e. the bandwidth must be larger than 2/n).

smooth

public final double[] smooth(double[] xval,
                             double[] yval,
                             double[] weights)
                      throws NonMonotonicSequenceException,
                             DimensionMismatchException,
                             NoDataException,
                             NotFiniteNumberException,
                             NumberIsTooSmallException
Compute a weighted loess fit on the data at the original abscissae.

Parameters:
xval - Arguments for the interpolation points.
yval - Values for the interpolation points.
weights - point weights: coefficients by which the robustness weight of a point is multiplied.
Returns:
the values of the loess fit at corresponding original abscissae.
Throws:
NonMonotonicSequenceException - if xval not sorted in strictly increasing order.
DimensionMismatchException - if xval and yval have different sizes.
NoDataException - if xval or yval has zero size.
NotFiniteNumberException - if any of the arguments and values are not finite real numbers.
NumberIsTooSmallException - if the bandwidth is too small to accomodate the size of the input data (i.e. the bandwidth must be larger than 2/n).
Since:
2.1

smooth

public final double[] smooth(double[] xval,
                             double[] yval)
                      throws NonMonotonicSequenceException,
                             DimensionMismatchException,
                             NoDataException,
                             NotFiniteNumberException,
                             NumberIsTooSmallException
Compute a loess fit on the data at the original abscissae.

Parameters:
xval - the arguments for the interpolation points
yval - the values for the interpolation points
Returns:
values of the loess fit at corresponding original abscissae
Throws:
NonMonotonicSequenceException - if xval not sorted in strictly increasing order.
DimensionMismatchException - if xval and yval have different sizes.
NoDataException - if xval or yval has zero size.
NotFiniteNumberException - if any of the arguments and values are not finite real numbers.
NumberIsTooSmallException - if the bandwidth is too small to accomodate the size of the input data (i.e. the bandwidth must be larger than 2/n).

updateBandwidthInterval

private static void updateBandwidthInterval(double[] xval,
                                            double[] weights,
                                            int i,
                                            int[] bandwidthInterval)
Given an index interval into xval that embraces a certain number of points closest to xval[i-1], update the interval so that it embraces the same number of points closest to xval[i], ignoring zero weights.

Parameters:
xval - Arguments array.
weights - Weights array.
i - Index around which the new interval should be computed.
bandwidthInterval - a two-element array {left, right} such that: (left==0 or xval[i] - xval[left-1] > xval[right] - xval[i]) and (right==xval.length-1 or xval[right+1] - xval[i] > xval[i] - xval[left]). The array will be updated.

nextNonzero

private static int nextNonzero(double[] weights,
                               int i)
Return the smallest index j such that j > i && (j == weights.length || weights[j] != 0).

Parameters:
weights - Weights array.
i - Index from which to start search.
Returns:
the smallest compliant index.

tricube

private static double tricube(double x)
Compute the tricube weight function

Parameters:
x - Argument.
Returns:
(1 - |x|3)3 for |x| < 1, 0 otherwise.

checkAllFiniteReal

private static void checkAllFiniteReal(double[] values)
Check that all elements of an array are finite real numbers.

Parameters:
values - Values array.
Throws:
NotFiniteNumberException - if one of the values is not a finite real number.


Copyright (c) 2003-2013 Apache Software Foundation