org.apache.commons.math3.analysis.interpolation

## Class LoessInterpolator

- java.lang.Object
- - org.apache.commons.math3.analysis.interpolation.LoessInterpolator

All Implemented Interfaces:
  Serializable, UnivariateInterpolator

    public class LoessInterpolator
    extends Object
    implements UnivariateInterpolator, 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

Fields
`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

Constructors
Constructor and Description
`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

Methods
`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.