MillerUpdatingRegression (Apache Commons Math 3.3 API)

org.apache.commons.math3.stat.regression

## Class MillerUpdatingRegression

- java.lang.Object
- - org.apache.commons.math3.stat.regression.MillerUpdatingRegression

- All Implemented Interfaces:
    UpdatingMultipleLinearRegression

      public class MillerUpdatingRegression
      extends Object
      implements UpdatingMultipleLinearRegression

  This class is a concrete implementation of the `UpdatingMultipleLinearRegression` interface.

  The algorithm is described in:

       Algorithm AS 274: Least Squares Routines to Supplement Those of Gentleman
       Author(s): Alan J. Miller
       Source: Journal of the Royal Statistical Society.
       Series C (Applied Statistics), Vol. 41, No. 2
       (1992), pp. 458-478
       Published by: Blackwell Publishing for the Royal Statistical Society
       Stable URL: http://www.jstor.org/stable/2347583

  This method for multiple regression forms the solution to the OLS problem by updating the QR decomposition as described by Gentleman.

  Since:
    3.0
  Version:
    $Id: MillerUpdatingRegression.java 1547633 2013-12-03 23:03:06Z tn $

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MillerUpdatingRegression(int numberOfVariables, boolean includeConstant)` Primary constructor for the MillerUpdatingRegression.
    `MillerUpdatingRegression(int numberOfVariables, boolean includeConstant, double errorTolerance)` This is the augmented constructor for the MillerUpdatingRegression class.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addObservation(double[] x, double y)` Adds an observation to the regression model.
    `void` | `addObservations(double[][] x, double[] y)` Adds multiple observations to the model.
    `void` | `clear()` As the name suggests, clear wipes the internals and reorders everything in the canonical order.
    `double` | `getDiagonalOfHatMatrix(double[] row_data)` Gets the diagonal of the Hat matrix also known as the leverage matrix.
    `long` | `getN()` Gets the number of observations added to the regression model.
    `int[]` | `getOrderOfRegressors()` Gets the order of the regressors, useful if some type of reordering has been called.
    `double[]` | `getPartialCorrelations(int in)` In the original algorithm only the partial correlations of the regressors is returned to the user.
    `boolean` | `hasIntercept()` A getter method which determines whether a constant is included.
    `RegressionResults` | `regress()` Conducts a regression on the data in the model, using all regressors.
    `RegressionResults` | `regress(int numberOfRegressors)` Conducts a regression on the data in the model, using a subset of regressors.
    `RegressionResults` | `regress(int[] variablesToInclude)` Conducts a regression on the data in the model, using regressors in array Calling this method will change the internal order of the regressors and care is required in interpreting the hatmatrix.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### MillerUpdatingRegression

          public MillerUpdatingRegression(int numberOfVariables,
                                  boolean includeConstant,
                                  double errorTolerance)
                                   throws ModelSpecificationException

      This is the augmented constructor for the MillerUpdatingRegression class.
      Parameters:
        `numberOfVariables` - number of regressors to expect, not including constant
        `includeConstant` - include a constant automatically
        `errorTolerance` - zero tolerance, how machine zero is determined
      Throws:
        `ModelSpecificationException` - if `numberOfVariables is less than 1`

    - #### MillerUpdatingRegression

          public MillerUpdatingRegression(int numberOfVariables,
                                  boolean includeConstant)
                                   throws ModelSpecificationException

      Primary constructor for the MillerUpdatingRegression.
      Parameters:
        `numberOfVariables` - maximum number of potential regressors
        `includeConstant` - include a constant automatically
      Throws:
        `ModelSpecificationException` - if `numberOfVariables is less than 1`

  - ### Method Detail

    - #### hasIntercept

          public boolean hasIntercept()

      A getter method which determines whether a constant is included.
      Specified by:
        `hasIntercept` in interface `UpdatingMultipleLinearRegression`
      Returns:
        true regression has an intercept, false no intercept

    - #### getN

          public long getN()

      Gets the number of observations added to the regression model.
      Specified by:
        `getN` in interface `UpdatingMultipleLinearRegression`
      Returns:
        number of observations

    - #### addObservation

          public void addObservation(double[] x,
                            double y)
                              throws ModelSpecificationException

      Adds an observation to the regression model.
      Specified by:
        `addObservation` in interface `UpdatingMultipleLinearRegression`
      Parameters:
        `x` - the array with regressor values
        `y` - the value of dependent variable given these regressors
      Throws:
        `ModelSpecificationException` - if the length of `x` does not equal the number of independent variables in the model

    - #### addObservations

          public void addObservations(double[][] x,
                             double[] y)
                               throws ModelSpecificationException

      Adds multiple observations to the model.
      Specified by:
        `addObservations` in interface `UpdatingMultipleLinearRegression`
      Parameters:
        `x` - observations on the regressors
        `y` - observations on the regressand
      Throws:
        `ModelSpecificationException` - if `x` is not rectangular, does not match the length of `y` or does not contain sufficient data to estimate the model

    - #### clear

          public void clear()

      As the name suggests, clear wipes the internals and reorders everything in the canonical order.
      Specified by:
        `clear` in interface `UpdatingMultipleLinearRegression`

    - #### getPartialCorrelations

          public double[] getPartialCorrelations(int in)

      In the original algorithm only the partial correlations of the regressors is returned to the user. In this implementation, we have

           corr =
           {
             corrxx - lower triangular
             corrxy - bottom row of the matrix
           }
           Replaces subroutines PCORR and COR of:
           ALGORITHM AS274  APPL. STATIST. (1992) VOL.41, NO. 2

      Calculate partial correlations after the variables in rows 1, 2, ..., IN have been forced into the regression. If IN = 1, and the first row of R represents a constant in the model, then the usual simple correlations are returned.

      If IN = 0, the value returned in array CORMAT for the correlation of variables Xi & Xj is:

           sum ( Xi.Xj ) / Sqrt ( sum (Xi^2) . sum (Xj^2) )

      On return, array CORMAT contains the upper triangle of the matrix of partial correlations stored by rows, excluding the 1's on the diagonal. e.g. if IN = 2, the consecutive elements returned are: (3,4) (3,5) ... (3,ncol), (4,5) (4,6) ... (4,ncol), etc. Array YCORR stores the partial correlations with the Y-variable starting with YCORR(IN+1) = partial correlation with the variable in position (IN+1).

      Parameters:
        `in` - how many of the regressors to include (either in canonical order, or in the current reordered state)
      Returns:
        an array with the partial correlations of the remainder of regressors with each other and the regressand, in lower triangular form

    - #### getDiagonalOfHatMatrix

          public double getDiagonalOfHatMatrix(double[] row_data)

      Gets the diagonal of the Hat matrix also known as the leverage matrix.
      Parameters:
        `row_data` - returns the diagonal of the hat matrix for this observation
      Returns:
        the diagonal element of the hatmatrix

    - #### getOrderOfRegressors

          public int[] getOrderOfRegressors()

      Gets the order of the regressors, useful if some type of reordering has been called. Calling regress with int[]{} args will trigger a reordering.
      Returns:
        int[] with the current order of the regressors

    - #### regress

          public RegressionResults regress()
                                    throws ModelSpecificationException

      Conducts a regression on the data in the model, using all regressors.
      Specified by:
        `regress` in interface `UpdatingMultipleLinearRegression`
      Returns:
        RegressionResults the structure holding all regression results
      Throws:
        `ModelSpecificationException` - - thrown if number of observations is less than the number of variables

    - #### regress

          public RegressionResults regress(int numberOfRegressors)
                                    throws ModelSpecificationException

      Conducts a regression on the data in the model, using a subset of regressors.
      Parameters:
        `numberOfRegressors` - many of the regressors to include (either in canonical order, or in the current reordered state)
      Returns:
        RegressionResults the structure holding all regression results
      Throws:
        `ModelSpecificationException` - - thrown if number of observations is less than the number of variables or number of regressors requested is greater than the regressors in the model

    - #### regress

          public RegressionResults regress(int[] variablesToInclude)
                                    throws ModelSpecificationException

      Conducts a regression on the data in the model, using regressors in array Calling this method will change the internal order of the regressors and care is required in interpreting the hatmatrix.
      Specified by:
        `regress` in interface `UpdatingMultipleLinearRegression`
      Parameters:
        `variablesToInclude` - array of variables to include in regression
      Returns:
        RegressionResults the structure holding all regression results
      Throws:
        `ModelSpecificationException` - - thrown if number of observations is less than the number of variables, the number of regressors requested is greater than the regressors in the model or a regressor index in regressor array does not exist

Copyright © 2003–2014 The Apache Software Foundation. All rights reserved.