org.apache.commons.math3.analysis.interpolation

## Class LoessInterpolator

- java.lang.Object
- - 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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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