## org.apache.commons.math.analysis.interpolation
Class LoessInterpolator

    java.lang.Object
      org.apache.commons.math.analysis.interpolation.LoessInterpolator

All Implemented Interfaces:
  java.io.Serializable, UnivariateRealInterpolator

    public class LoessInterpolator

extends java.lang.Object
implements UnivariateRealInterpolator, 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 to build a spline on the obtained loess fit.

Since:
  2.0
Version:
  $Revision: 925812 $ $Date: 2010-03-21 11:49:31 -0400 (Sun, 21 Mar 2010) $
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)` Constructs a new `LoessInterpolator` with given bandwidth and number of robustness iterations.
`LoessInterpolator(double bandwidth, int robustnessIters, double accuracy)` Constructs a new `LoessInterpolator` with given bandwidth, number of robustness iterations and accuracy.

Method Summary
`private static void` `checkAllFiniteReal(double[] values, java.lang.String pattern)` Check that all elements of an array are finite real numbers.
`private static void` `checkStrictlyIncreasing(double[] xval)` Check that elements of the abscissae array are in a strictly increasing order.
`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)` Returns 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)
                      throws MathException

  Constructs 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`.
  Throws:
    `MathException` - if bandwidth does not lie in the interval [0,1] or if robustnessIters is negative.
  See Also:
    `LoessInterpolator(double, int, double)`

### LoessInterpolator

    public LoessInterpolator(double bandwidth,
                             int robustnessIters,
                             double accuracy)
                      throws MathException

  Constructs 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:
    `MathException` - if bandwidth does not lie in the interval [0,1] or if robustnessIters is negative.
  Since:
    2.1
  See Also:
    `LoessInterpolator(double, int)`

Method Detail

### interpolate

    public final PolynomialSplineFunction interpolate(double[] xval,
                                                      double[] yval)
                                               throws MathException

  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 `UnivariateRealInterpolator`
  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:
    `MathException` - if some of the following conditions are false:
    - Arguments and values are of the same size that is greater than zero
    - The arguments are in a strictly increasing order
    - All arguments and values are finite real numbers

### smooth

    public final double[] smooth(double[] xval,
                                 double[] yval,
                                 double[] weights)
                          throws MathException

  Compute a weighted loess fit on the data at the original abscissae.

  Parameters:
    `xval` - the arguments for the interpolation points
    `yval` - the values for the interpolation points
    `weights` - point weights: coefficients by which the robustness weight of a point is multiplied
  Returns:
    values of the loess fit at corresponding original abscissae
  Throws:
    `MathException` - if some of the following conditions are false:
    - Arguments and values are of the same size that is greater than zero
    - The arguments are in a strictly increasing order
    - All arguments and values are finite real numbers
  Since:
    2.1

### smooth

    public final double[] smooth(double[] xval,
                                 double[] yval)
                          throws MathException

  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:
    `MathException` - if some of the following conditions are false:
    - Arguments and values are of the same size that is greater than zero
    - The arguments are in a strictly increasing order
    - All arguments and values are finite real numbers

### 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` - the 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 also

    `(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)

  Returns the smallest index j such that j > i && (j==weights.length || weights[j] != 0)

  Parameters:
    `weights` - weights array
    `i` - the index from which to start search; must be < weights.length
  Returns:
    the smallest index j such that j > i && (j==weights.length || weights[j] != 0)

### tricube

    private static double tricube(double x)

  Compute the tricube weight function

  Parameters:
    `x` - the argument
  Returns:
    (1-|x|^3)^3

### checkAllFiniteReal

    private static void checkAllFiniteReal(double[] values,
                                           java.lang.String pattern)
                                    throws MathException

  Check that all elements of an array are finite real numbers.

  Parameters:
    `values` - the values array
    `pattern` - pattern of the error message
  Throws:
    `MathException` - if one of the values is not a finite real number

### checkStrictlyIncreasing

    private static void checkStrictlyIncreasing(double[] xval)
                                         throws MathException

  Check that elements of the abscissae array are in a strictly increasing order.

  Parameters:
    `xval` - the abscissae array
  Throws:
    `MathException` - if the abscissae array is not in a strictly increasing order

Copyright (c) 2003-2010 Apache Software Foundation