org.apache.commons.math.stat.regression

## Class SimpleRegression

- java.lang.Object
- - org.apache.commons.math.stat.regression.SimpleRegression

All Implemented Interfaces:
  Serializable

    public class SimpleRegression
    extends Object
    implements Serializable

Estimates an ordinary least squares regression model with one independent variable.

`y = intercept + slope * x`

Standard errors for `intercept` and `slope` are available as well as ANOVA, r-square and Pearson's r statistics.

Observations (x,y pairs) can be added to the model one at a time or they can be provided in a 2-dimensional array. The observations are not stored in memory, so there is no limit to the number of observations that can be added to the model.

Usage Notes:

- When there are fewer than two observations in the model, or when there is no variation in the x values (i.e. all x values are the same) all statistics return `NaN`. At least two observations with different x coordinates are requred to estimate a bivariate regression model.
- getters for the statistics always compute values based on the current set of observations -- i.e., you can get statistics, then add more data and get updated statistics without using a new instance. There is no "compute" method that updates all statistics. Each of the getters performs the necessary computations to return the requested statistic.

Version:
  $Revision: 1042336 $ $Date: 2010-12-05 13:40:48 +0100 (dim. 05 déc. 2010) $
See Also:
  Serialized Form

### Field Summary

Fields
`private TDistribution` `distribution` the distribution used to compute inference statistics.
`private long` `n` number of observations
`private static long` `serialVersionUID` Serializable version identifier
`private double` `sumX` sum of x values
`private double` `sumXX` total variation in x (sum of squared deviations from xbar)
`private double` `sumXY` sum of products
`private double` `sumY` sum of y values
`private double` `sumYY` total variation in y (sum of squared deviations from ybar)
`private double` `xbar` mean of accumulated x values, used in updating formulas
`private double` `ybar` mean of accumulated y values, used in updating formulas

### Constructor Summary

Constructors
Constructor and Description
`SimpleRegression()` Create an empty SimpleRegression instance
`SimpleRegression(int degrees)` Create an empty SimpleRegression.
`SimpleRegression(TDistribution t)` Deprecated. in 2.2 (to be removed in 3.0). Please use the `other constructor` instead.

### Method Summary

Methods
`void` `addData(double[][] data)` Adds the observations represented by the elements in `data`.
`void` `addData(double x, double y)` Adds the observation (x,y) to the regression data set.
`void` `clear()` Clears all data from the model.
`double` `getIntercept()` Returns the intercept of the estimated regression line.
`private double` `getIntercept(double slope)` Returns the intercept of the estimated regression line, given the slope.
`double` `getInterceptStdErr()` Returns the standard error of the intercept estimate, usually denoted s(b0).
`double` `getMeanSquareError()` Returns the sum of squared errors divided by the degrees of freedom, usually abbreviated MSE.
`long` `getN()` Returns the number of observations that have been added to the model.
`double` `getR()` Returns Pearson's product moment correlation coefficient, usually denoted r.
`double` `getRegressionSumSquares()` Returns the sum of squared deviations of the predicted y values about their mean (which equals the mean of y).
`private double` `getRegressionSumSquares(double slope)` Computes SSR from b1.
`double` `getRSquare()` Returns the coefficient of determination, usually denoted r-square.
`double` `getSignificance()` Returns the significance level of the slope (equiv) correlation.
`double` `getSlope()` Returns the slope of the estimated regression line.
`double` `getSlopeConfidenceInterval()` Returns the half-width of a 95% confidence interval for the slope estimate.
`double` `getSlopeConfidenceInterval(double alpha)` Returns the half-width of a (100-100*alpha)% confidence interval for the slope estimate.
`double` `getSlopeStdErr()` Returns the standard error of the slope estimate, usually denoted s(b1).
`double` `getSumOfCrossProducts()` Returns the sum of crossproducts, xi*yi.
`double` `getSumSquaredErrors()` Returns the sum of squared errors (SSE) associated with the regression model.
`double` `getTotalSumSquares()` Returns the sum of squared deviations of the y values about their mean.
`double` `getXSumSquares()` Returns the sum of squared deviations of the x values about their mean.
`double` `predict(double x)` Returns the "predicted" `y` value associated with the supplied `x` value, based on the data that has been added to the model when this method is activated.
`void` `removeData(double[][] data)` Removes observations represented by the elements in `data`.
`void` `removeData(double x, double y)` Removes the observation (x,y) from the regression data set.
`void` `setDistribution(TDistribution value)` Deprecated. in 2.2 (to be removed in 3.0).

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

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

### Field Detail

#### serialVersionUID

    private static final long serialVersionUID

Serializable version identifier

See Also:
  Constant Field Values

#### distribution

    private TDistribution distribution

the distribution used to compute inference statistics.

#### sumX

    private double sumX

sum of x values

#### sumXX

    private double sumXX

total variation in x (sum of squared deviations from xbar)

#### sumY

    private double sumY

sum of y values

#### sumYY

    private double sumYY

total variation in y (sum of squared deviations from ybar)

#### sumXY

    private double sumXY

sum of products

#### n

    private long n

number of observations

#### xbar

    private double xbar

mean of accumulated x values, used in updating formulas

#### ybar

    private double ybar

mean of accumulated y values, used in updating formulas

### Constructor Detail

#### SimpleRegression

    public SimpleRegression()

Create an empty SimpleRegression instance

#### SimpleRegression

    @Deprecated
    public SimpleRegression(TDistribution t)

Deprecated. in 2.2 (to be removed in 3.0). Please use the `other constructor` instead.
Create an empty SimpleRegression using the given distribution object to compute inference statistics.

Parameters:
  `t` - the distribution used to compute inference statistics.
Since:
  1.2

#### SimpleRegression

    public SimpleRegression(int degrees)

Create an empty SimpleRegression.

Parameters:
  `degrees` - Number of degrees of freedom of the distribution used to compute inference statistics.
Since:
  2.2

### Method Detail

#### addData

    public void addData(double x,
               double y)

Adds the observation (x,y) to the regression data set.

Uses updating formulas for means and sums of squares defined in "Algorithms for Computing the Sample Variance: Analysis and Recommendations", Chan, T.F., Golub, G.H., and LeVeque, R.J. 1983, American Statistician, vol. 37, pp. 242-247, referenced in Weisberg, S. "Applied Linear Regression". 2nd Ed. 1985.

Parameters:
  `x` - independent variable value
  `y` - dependent variable value

#### removeData

    public void removeData(double x,
                  double y)

Removes the observation (x,y) from the regression data set.

Mirrors the addData method. This method permits the use of SimpleRegression instances in streaming mode where the regression is applied to a sliding "window" of observations, however the caller is responsible for maintaining the set of observations in the window.

The method has no effect if there are no points of data (i.e. n=0)

Parameters:
  `x` - independent variable value
  `y` - dependent variable value

#### addData

    public void addData(double[][] data)

Adds the observations represented by the elements in `data`.

`(data[0][0],data[0][1])` will be the first observation, then `(data[1][0],data[1][1])`, etc.

This method does not replace data that has already been added. The observations represented by `data` are added to the existing dataset.

To replace all data, use `clear()` before adding the new data.

Parameters:
  `data` - array of observations to be added

#### removeData

    public void removeData(double[][] data)

Removes observations represented by the elements in `data`.

If the array is larger than the current n, only the first n elements are processed. This method permits the use of SimpleRegression instances in streaming mode where the regression is applied to a sliding "window" of observations, however the caller is responsible for maintaining the set of observations in the window.

To remove all data, use `clear()`.

Parameters:
  `data` - array of observations to be removed

#### clear

    public void clear()

Clears all data from the model.

#### getN

    public long getN()

Returns the number of observations that have been added to the model.

Returns:
  n number of observations that have been added.

#### predict

    public double predict(double x)

Returns the "predicted" `y` value associated with the supplied `x` value, based on the data that has been added to the model when this method is activated.

`predict(x) = intercept + slope * x`

Preconditions:

- At least two observations (with at least two different x values) must have been added before invoking this method. If this method is invoked before a model can be estimated, `Double,NaN` is returned.

Parameters:
  `x` - input `x` value
Returns:
  predicted `y` value

#### getIntercept

    public double getIntercept()

Returns the intercept of the estimated regression line.

The least squares estimate of the intercept is computed using the normal equations. The intercept is sometimes denoted b0.

Preconditions:

- At least two observations (with at least two different x values) must have been added before invoking this method. If this method is invoked before a model can be estimated, `Double,NaN` is returned.

Returns:
  the intercept of the regression line

#### getSlope

    public double getSlope()

Returns the slope of the estimated regression line.

The least squares estimate of the slope is computed using the normal equations. The slope is sometimes denoted b1.

Preconditions:

- At least two observations (with at least two different x values) must have been added before invoking this method. If this method is invoked before a model can be estimated, `Double.NaN` is returned.

Returns:
  the slope of the regression line

#### getSumSquaredErrors

    public double getSumSquaredErrors()

Returns the sum of squared errors (SSE) associated with the regression model.

The sum is computed using the computational formula

`SSE = SYY - (SXY * SXY / SXX)`

where `SYY` is the sum of the squared deviations of the y values about their mean, `SXX` is similarly defined and `SXY` is the sum of the products of x and y mean deviations.

The sums are accumulated using the updating algorithm referenced in `addData(double, double)`.

The return value is constrained to be non-negative - i.e., if due to rounding errors the computational formula returns a negative result, 0 is returned.

Preconditions:

- At least two observations (with at least two different x values) must have been added before invoking this method. If this method is invoked before a model can be estimated, `Double,NaN` is returned.

Returns:
  sum of squared errors associated with the regression model

#### getTotalSumSquares

    public double getTotalSumSquares()

Returns the sum of squared deviations of the y values about their mean.

This is defined as SSTO here.

If `n < 2`, this returns `Double.NaN`.

Returns:
  sum of squared deviations of y values

#### getXSumSquares

    public double getXSumSquares()

Returns the sum of squared deviations of the x values about their mean. If `n < 2`, this returns `Double.NaN`.

Returns:
  sum of squared deviations of x values

#### getSumOfCrossProducts

    public double getSumOfCrossProducts()

Returns the sum of crossproducts, xi*yi.

Returns:
  sum of cross products

#### getRegressionSumSquares

    public double getRegressionSumSquares()

Returns the sum of squared deviations of the predicted y values about their mean (which equals the mean of y).

This is usually abbreviated SSR or SSM. It is defined as SSM here

Preconditions:

- At least two observations (with at least two different x values) must have been added before invoking this method. If this method is invoked before a model can be estimated, `Double.NaN` is returned.

Returns:
  sum of squared deviations of predicted y values

#### getMeanSquareError

    public double getMeanSquareError()

Returns the sum of squared errors divided by the degrees of freedom, usually abbreviated MSE.

If there are fewer than three data pairs in the model, or if there is no variation in `x`, this returns `Double.NaN`.

Returns:
  sum of squared deviations of y values

#### getR

    public double getR()

Returns Pearson's product moment correlation coefficient, usually denoted r.

Preconditions:

- At least two observations (with at least two different x values) must have been added before invoking this method. If this method is invoked before a model can be estimated, `Double,NaN` is returned.

Returns:
  Pearson's r

#### getRSquare

    public double getRSquare()

Returns the coefficient of determination, usually denoted r-square.

Preconditions:

- At least two observations (with at least two different x values) must have been added before invoking this method. If this method is invoked before a model can be estimated, `Double,NaN` is returned.

Returns:
  r-square

#### getInterceptStdErr

    public double getInterceptStdErr()

Returns the standard error of the intercept estimate, usually denoted s(b0).

If there are fewer that three observations in the model, or if there is no variation in x, this returns `Double.NaN`.

Returns:
  standard error associated with intercept estimate

#### getSlopeStdErr

    public double getSlopeStdErr()

Returns the standard error of the slope estimate, usually denoted s(b1).

If there are fewer that three data pairs in the model, or if there is no variation in x, this returns `Double.NaN`.

Returns:
  standard error associated with slope estimate

#### getSlopeConfidenceInterval

    public double getSlopeConfidenceInterval()
                                      throws MathException

Returns the half-width of a 95% confidence interval for the slope estimate.

The 95% confidence interval is

`(getSlope() - getSlopeConfidenceInterval(), getSlope() + getSlopeConfidenceInterval())`

If there are fewer that three observations in the model, or if there is no variation in x, this returns `Double.NaN`.

Usage Note:
The validity of this statistic depends on the assumption that the observations included in the model are drawn from a Bivariate Normal Distribution.

Returns:
  half-width of 95% confidence interval for the slope estimate
Throws:
  `MathException` - if the confidence interval can not be computed.

#### getSlopeConfidenceInterval

    public double getSlopeConfidenceInterval(double alpha)
                                      throws MathException

Returns the half-width of a (100-100*alpha)% confidence interval for the slope estimate.

The (100-100*alpha)% confidence interval is

`(getSlope() - getSlopeConfidenceInterval(), getSlope() + getSlopeConfidenceInterval())`

To request, for example, a 99% confidence interval, use `alpha = .01`

Usage Note:
The validity of this statistic depends on the assumption that the observations included in the model are drawn from a Bivariate Normal Distribution.

Preconditions:

- If there are fewer that three observations in the model, or if there is no variation in x, this returns `Double.NaN`.
- `(0 < alpha < 1)`; otherwise an `IllegalArgumentException` is thrown.

Parameters:
  `alpha` - the desired significance level
Returns:
  half-width of 95% confidence interval for the slope estimate
Throws:
  `MathException` - if the confidence interval can not be computed.

#### getSignificance

    public double getSignificance()
                           throws MathException

Returns the significance level of the slope (equiv) correlation.

Specifically, the returned value is the smallest `alpha` such that the slope confidence interval with significance level equal to `alpha` does not include `0`. On regression output, this is often denoted `Prob(|t| > 0)`

Usage Note:
The validity of this statistic depends on the assumption that the observations included in the model are drawn from a Bivariate Normal Distribution.

If there are fewer that three observations in the model, or if there is no variation in x, this returns `Double.NaN`.

Returns:
  significance level for slope/correlation
Throws:
  `MathException` - if the significance level can not be computed.

#### getIntercept

    private double getIntercept(double slope)

Returns the intercept of the estimated regression line, given the slope.

Will return `NaN` if slope is `NaN`.

Parameters:
  `slope` - current slope
Returns:
  the intercept of the regression line

#### getRegressionSumSquares

    private double getRegressionSumSquares(double slope)

Computes SSR from b1.

Parameters:
  `slope` - regression slope estimate
Returns:
  sum of squared deviations of predicted y values

#### setDistribution

    @Deprecated
    public void setDistribution(TDistribution value)

Deprecated. in 2.2 (to be removed in 3.0).
Modify the distribution used to compute inference statistics.

Parameters:
  `value` - the new distribution
Since:
  1.2