org.apache.commons.math.optimization
Class LeastSquaresConverter

java.lang.Object
  extended by org.apache.commons.math.optimization.LeastSquaresConverter
All Implemented Interfaces:
MultivariateRealFunction

public class LeastSquaresConverter
extends java.lang.Object
implements MultivariateRealFunction

This class converts vectorial objective functions to scalar objective functions when the goal is to minimize them.

This class is mostly used when the vectorial objective function represents a theoretical result computed from a point set applied to a model and the models point must be adjusted to fit the theoretical result to some reference observations. The observations may be obtained for example from physical measurements whether the model is built from theoretical considerations.

This class computes a possibly weighted squared sum of the residuals, which is a scalar value. The residuals are the difference between the theoretical model (i.e. the output of the vectorial objective function) and the observations. The class implements the MultivariateRealFunction interface and can therefore be minimized by any optimizer supporting scalar objectives functions.This is one way to perform a least square estimation. There are other ways to do this without using this converter, as some optimization algorithms directly support vectorial objective functions.

This class support combination of residuals with or without weights and correlations.

Since:
2.0
Version:
$Revision: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $
See Also:
MultivariateRealFunction, MultivariateVectorialFunction

Field Summary
private  MultivariateVectorialFunction function
          Underlying vectorial function.
private  double[] observations
          Observations to be compared to objective function to compute residuals.
private  RealMatrix scale
          Optional scaling matrix (weight and correlations) for the residuals.
private  double[] weights
          Optional weights for the residuals.
 
Constructor Summary
LeastSquaresConverter(MultivariateVectorialFunction function, double[] observations)
          Build a simple converter for uncorrelated residuals with the same weight.
LeastSquaresConverter(MultivariateVectorialFunction function, double[] observations, double[] weights)
          Build a simple converter for uncorrelated residuals with the specific weights.
LeastSquaresConverter(MultivariateVectorialFunction function, double[] observations, RealMatrix scale)
          Build a simple converter for correlated residuals with the specific weights.
 
Method Summary
 double value(double[] point)
          Compute the value for the function at the given point.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

function

private final MultivariateVectorialFunction function
Underlying vectorial function.


observations

private final double[] observations
Observations to be compared to objective function to compute residuals.


weights

private final double[] weights
Optional weights for the residuals.


scale

private final RealMatrix scale
Optional scaling matrix (weight and correlations) for the residuals.

Constructor Detail

LeastSquaresConverter

public LeastSquaresConverter(MultivariateVectorialFunction function,
                             double[] observations)
Build a simple converter for uncorrelated residuals with the same weight.

Parameters:
function - vectorial residuals function to wrap
observations - observations to be compared to objective function to compute residuals

LeastSquaresConverter

public LeastSquaresConverter(MultivariateVectorialFunction function,
                             double[] observations,
                             double[] weights)
                      throws java.lang.IllegalArgumentException
Build a simple converter for uncorrelated residuals with the specific weights.

The scalar objective function value is computed as:

 objective = ∑weighti(observationi-objectivei)2
 

Weights can be used for example to combine residuals with different standard deviations. As an example, consider a residuals array in which even elements are angular measurements in degrees with a 0.01° standard deviation and odd elements are distance measurements in meters with a 15m standard deviation. In this case, the weights array should be initialized with value 1.0/(0.012) in the even elements and 1.0/(15.02) in the odd elements (i.e. reciprocals of variances).

The array computed by the objective function, the observations array and the weights array must have consistent sizes or a FunctionEvaluationException will be triggered while computing the scalar objective.

Parameters:
function - vectorial residuals function to wrap
observations - observations to be compared to objective function to compute residuals
weights - weights to apply to the residuals
Throws:
java.lang.IllegalArgumentException - if the observations vector and the weights vector dimensions don't match (objective function dimension is checked only when the value(double[]) method is called)

LeastSquaresConverter

public LeastSquaresConverter(MultivariateVectorialFunction function,
                             double[] observations,
                             RealMatrix scale)
                      throws java.lang.IllegalArgumentException
Build a simple converter for correlated residuals with the specific weights.

The scalar objective function value is computed as:

 objective = yTy with y = scale×(observation-objective)
 

The array computed by the objective function, the observations array and the the scaling matrix must have consistent sizes or a FunctionEvaluationException will be triggered while computing the scalar objective.

Parameters:
function - vectorial residuals function to wrap
observations - observations to be compared to objective function to compute residuals
scale - scaling matrix
Throws:
java.lang.IllegalArgumentException - if the observations vector and the scale matrix dimensions don't match (objective function dimension is checked only when the value(double[]) method is called)
Method Detail

value

public double value(double[] point)
             throws FunctionEvaluationException
Compute the value for the function at the given point.

Specified by:
value in interface MultivariateRealFunction
Parameters:
point - point at which the function must be evaluated
Returns:
function value for the given point
Throws:
FunctionEvaluationException - if the function evaluation fails


Copyright (c) 2003-2012 Apache Software Foundation