Covariance (patrimoine de base SIRIUS 4.13 API)

java.lang.Object
- fr.cnes.sirius.patrius.covariance.Covariance

```
public class Covariance
extends Object
```
Covariance representation.
The covariance matrix is stored in a SymmetricPositiveMatrix object.
The covariance columns/rows are described by a list of parameter descriptors.

Author:

Hugo Veuillez (CNES), Pierre Seimandi (GMV)

Field Summary

Fields
Modifier and Type	Field and Description
`protected static String`	`DEFAULT_FIELD_SEPARATOR` Default field separator for the `toString()` methods.
`protected static String`	`DEFAULT_NAME_SEPARATOR` Default name separator for the `toString()` methods.

Constructor Summary

Constructors
Constructor and Description
`Covariance(SymmetricPositiveMatrix covarianceMatrixIn)` Creates a new instance using the specified covariance matrix.
`Covariance(SymmetricPositiveMatrix covarianceMatrixIn, Collection<ParameterDescriptor> parameterDescriptorsIn)` Creates a new instance using the specified covariance matrix and parameter descriptors.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Covariance`	`add(SymmetricPositiveMatrix m)` Adds the symmetric positive semi-definite matrix M to this covariance matrix and returns a new Covariance instance associated with the computed matrix and the same parameter descriptors.
`Covariance`	`copy()` Gets a copy of this Covariance instance.
`boolean`	`equals(Object object)`
`double`	`getCorrelationCoefficient(int row, int column)` Gets the correlation coefficient ρ_i,j for the specified row and column indexes.
`double`	`getCorrelationCoefficient(ParameterDescriptor parameterDescriptor1, ParameterDescriptor parameterDescriptor2)` Gets the correlation coefficient ρ_i,j associated with the specified parameter descriptors, the first parameter* descriptor being mapped to the rows of the covariance matrix (index "i"), while the second parameter descriptor is mapped to the columns of the covariance matrix (index "j").
`SymmetricPositiveMatrix`	`getCorrelationCoefficientsMatrix()` Gets the correlation matrix.
`SymmetricPositiveMatrix`	`getCovarianceMatrix()` Gets the covariance matrix.
`double`	`getMahalanobisDistance(RealVector point)` Gets the Mahalanobis distance of a point with respect to this covariance matrix, assuming its mean value is zero.
`double`	`getMahalanobisDistance(RealVector point, RealVector mean)` Gets the Mahalanobis distance of a point with respect to this covariance matrix.
`ParameterDescriptor`	`getParameterDescriptor(int index)` Gets the parameter descriptors associated with the specified row/column of the covariance matrix.
`List<ParameterDescriptor>`	`getParameterDescriptors()` Gets the parameter descriptors associated with the rows/columns of the covariance matrix.
`int`	`getSize()` Gets the size of the covariance matrix.
`double`	`getStandardDeviation(int index)` Gets the standard deviation σ_i = sqrt(C_i,i) for the specified row/column index.
`double`	`getStandardDeviation(ParameterDescriptor parameterDescriptor)` Gets the standard deviation σ_i = sqrt(C_i,i) associated with the specified parameter descriptor.
`DiagonalMatrix`	`getStandardDeviationMatrix()` Gets the standard deviation matrix.
`Covariance`	`getSubCovariance(Collection<ParameterDescriptor> selectedParameterDescriptors)` Extracts the parts of the covariance associated with the specified parameter descriptors.
`Covariance`	`getSubCovariance(int[] indices)` Extracts the parts of the covariance associated with the specified row/column indices.
`double`	`getVariance(int index)` Gets the variance σ_i = C_i,i for the specified row/column index.
`double`	`getVariance(ParameterDescriptor parameterDescriptor)` Gets the variance σ_i = C_i,i associated with the specified parameter descriptor.
`DiagonalMatrix`	`getVarianceMatrix()` Gets the variance matrix.
`int`	`hashCode()`
`protected int`	`indexOf(ParameterDescriptor parameterDescriptor)` Gets the index of a given parameter descriptor in the list stored internally.
`Covariance`	`positiveScalarMultiply(double d)` Multiplies this covariance matrix by a positive scalar.
`Covariance`	`quadraticMultiplication(RealMatrix m)` Gets the result of the quadratic multiplication M×C×M^T, where C is this covariance matrix and M is the provided matrix, and associates the computed matrix with default parameter descriptors.
`Covariance`	`quadraticMultiplication(RealMatrix m, boolean isTranspose)` Gets the result of the quadratic multiplication M×C×M^T, where C is this covariance matrix and M or M^T is the provided matrix, and associates the computed matrix with default parameter descriptors.
`Covariance`	`quadraticMultiplication(RealMatrix m, Collection<ParameterDescriptor> newParameterDescriptors)` Gets the result of the quadratic multiplication M×C×M^T, where C is this covariance matrix and M is the provided matrix, and associates the computed matrix with the specified parameter descriptors.
`Covariance`	`quadraticMultiplication(RealMatrix m, Collection<ParameterDescriptor> newParameterDescriptors, boolean isTranspose)` Gets the result of the quadratic multiplication M×C×M^T, where C is this covariance matrix and M or M^T is the provided matrix, and associates the computed matrix with the specified parameter descriptors.
`String`	`toString()` Returns a string representation of this instance which includes the name of the class and the names of the associated parameter descriptors (the covariance matrix itself is not printed).
`String`	`toString(RealMatrixFormat realMatrixFormat)` Returns a string representation of this instance which includes the name of the class (if requested), the names of the associated parameter descriptors and the the covariance matrix (if the specified matrix format is not `null`).
`String`	`toString(RealMatrixFormat realMatrixFormat, String nameSeparator, String fieldSeparator, boolean printClassName, boolean reverseOrder)` Returns a string representation of this instance which includes the name of the class (if requested), the names of the associated parameter descriptors and the the covariance matrix (if the specified matrix format is not `null`).

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_FIELD_SEPARATOR
```
protected static final String DEFAULT_FIELD_SEPARATOR
```
    Default field separator for the toString() methods.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_NAME_SEPARATOR
```
protected static final String DEFAULT_NAME_SEPARATOR
```
    Default name separator for the toString() methods.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Covariance
```
public Covariance(SymmetricPositiveMatrix covarianceMatrixIn)
```
    Creates a new instance using the specified covariance matrix.
    The rows/columns of the covariance matrix are automatically associated with default parameter descriptors. These descriptors are comprised of a single field descriptor ( PARAMETER_NAME), mapped to the string "p" + i, where i is the index of the corresponding row/column in the covariance matrix.
    
    Parameters:
    
    covarianceMatrixIn - the covariance matrix
    
    Throws:
    
    NullPointerException - if the provided covariance matrix is null
    
    See Also:
    
    ParameterUtils.buildDefaultParameterDescriptors(int)
  - Covariance
```
public Covariance(SymmetricPositiveMatrix covarianceMatrixIn,
                  Collection<ParameterDescriptor> parameterDescriptorsIn)
```
    Creates a new instance using the specified covariance matrix and parameter descriptors.
    The provided parameter descriptors are automatically associated with the rows/colums of the covariance matrix (in the order they are returned by the collection's iterator). The number of parameter descriptors must match the size the covariance matrix. If the provided collection is null or empty, default parameter descriptors are used instead. These default descriptors are comprised of a single field descriptor ( PARAMETER_NAME), mapped to the string "p" + i, where i is the index of the corresponding row/column in the covariance matrix.
    
    Note that this constructor performs a shallow copy of the provided parameter descriptors. The covariance matrix itself is passed by reference.
    
    Parameters:
    
    covarianceMatrixIn - the covariance matrix
    
    parameterDescriptorsIn - the parameter descriptors associated with the covariance matrix
    
    Throws:
    
    IllegalArgumentException - if the provided covariance matrix is null, if the number of parameter descriptors does not match the size of the covariance matrix, or if the collection of parameter descriptors contains any duplicate
    
    See Also:
    
    ParameterUtils.buildDefaultParameterDescriptors(int)
- Method Detail
  - indexOf
```
protected int indexOf(ParameterDescriptor parameterDescriptor)
```
    Gets the index of a given parameter descriptor in the list stored internally.
    
    Parameters:
    
    parameterDescriptor - the parameter descriptor whose index must be retrieved
    
    Returns:
    
    the index of the parameter descriptor in the list stored internally.
    
    Throws:
    
    IllegalArgumentException - if the parameter descriptor is not associated with this covariance matrix
  - getSize
```
public int getSize()
```
    Gets the size of the covariance matrix.
    
    Returns:
    
    the size of the covariance matrix
  - getCovarianceMatrix
```
public SymmetricPositiveMatrix getCovarianceMatrix()
```
    Gets the covariance matrix.
    A covariance matrix is symmetric positive semi-definite by definition. Whether these properties are actually respected depends on the implementation of SymmetricPositiveMatrix used to store the matrix.
    
    Note that this method provides a direct access to the covariance matrix stored internally, which is possibly mutable.
    
    Returns:
    
    the covariance matrix
  - getParameterDescriptors
```
public List<ParameterDescriptor> getParameterDescriptors()
```
    Gets the parameter descriptors associated with the rows/columns of the covariance matrix.
    Note that this methods returns a shallow copy of the list of parameter descriptors stored internally. However, this list provides a direct access to the parameter descriptors stored by this instance, which are mutable.
    
    Returns:
    
    the parameter descriptors associated with the covariance matrix
  - getParameterDescriptor
```
public ParameterDescriptor getParameterDescriptor(int index)
```
    Gets the parameter descriptors associated with the specified row/column of the covariance matrix.
    Note that this method provides a direct access to the parameter descriptors stored internally, which are mutable.
    
    Parameters:
    
    index - the row/column index of the parameter descriptor to be retrieved
    
    Returns:
    
    the parameter descriptors associated with the covariance matrix
  - getSubCovariance
```
public Covariance getSubCovariance(int[] indices)
```
    Extracts the parts of the covariance associated with the specified row/column indices.
    This method extracts the specified rows/columns associated in order to build a new Covariance instance. The provided index array may contain duplicates, but an exception will be thrown if it any of the indices is not a valid row/column index. This method can be used to extract any submatrix and/or to perform a symmetric reordering of the rows/columns of the covariance matrix.
    
    Important:
    Since a parameter descriptor cannot be associated with multiple rows/columns of the covariance, the provided index array must not contain any duplicate (an exception will be thrown if that occurs).
    
    Parameters:
    
    indices - the indices of the rows/columns to be extracted
    
    Returns:
    
    the part of the covariance associated with the specified indices
    
    Throws:
    
    IllegalArgumentException - if one of the specified indices is not a valid row/column index for this covariance matrix, or the provided index array contains any duplicate
  - getSubCovariance
```
public Covariance getSubCovariance(Collection<ParameterDescriptor> selectedParameterDescriptors)
```
    Extracts the parts of the covariance associated with the specified parameter descriptors.
    This method extracts the rows/columns associated with the specified parameter descriptors in order to build a new Covariance instance. The provided collection may contain duplicates, but an exception will be thrown if any of the parameter descriptors is not associated with this covariance. This method can be used to extract any submatrix and/or to perform a symmetric reordering of the rows/columns of the covariance matrix.
    
    Important:
    Since a parameter descriptor cannot be associated with multiple rows/columns of the covariance matrix, the provided collection must not contain any duplicate (an exception will be thrown if that occurs).
    
    Parameters:
    
    selectedParameterDescriptors - the parameter descriptors associated with the rows/columns to be extracted
    
    Returns:
    
    the part of the covariance associated with the specified parameter descriptors
    
    Throws:
    
    IllegalArgumentException - if one of the provided parameter descriptors is not associated with this covariance matrix, or if the provided collection contains any duplicate
  - getVarianceMatrix
```
public DiagonalMatrix getVarianceMatrix()
```
    Gets the variance matrix.
    The variance matrix is a diagonal matrix which contains the diagonal elements of the covariance matrix.
    
    Returns:
    
    the variance matrix
  - getVariance
```
public double getVariance(int index)
```
    Gets the variance σ_i = C_i,i for the specified row/column index.
    
    Parameters:
    
    index - the row/column index
    
    Returns:
    
    the variance for the specified row/column index
    
    Throws:
    
    IllegalArgumentException - if the provided index is not valid
  - getVariance
```
public double getVariance(ParameterDescriptor parameterDescriptor)
```
    Gets the variance σ_i = C_i,i associated with the specified parameter descriptor.
    
    Parameters:
    
    parameterDescriptor - the parameter descriptor
    
    Returns:
    
    the variance for the specified parameter descriptor
    
    Throws:
    
    IllegalArgumentException - if the provided collection is null or if the parameter descriptor is not associated with this covariance matrix
  - getStandardDeviationMatrix
```
public DiagonalMatrix getStandardDeviationMatrix()
```
    Gets the standard deviation matrix.
    The standard deviation matrix is a diagonal matrix which contains the square root of the diagonal elements of this covariance matrix.
    
    Returns:
    
    the standard deviation matrix
  - getStandardDeviation
```
public double getStandardDeviation(int index)
```
    Gets the standard deviation σ_i = sqrt(C_i,i) for the specified row/column index.
    
    Parameters:
    
    index - the row/column index
    
    Returns:
    
    the standard deviation for the specified row/column index
    
    Throws:
    
    OutOfRangeException - if the provided index is not valid
  - getStandardDeviation
```
public double getStandardDeviation(ParameterDescriptor parameterDescriptor)
```
    Gets the standard deviation σ_i = sqrt(C_i,i) associated with the specified parameter descriptor.
    
    Parameters:
    
    parameterDescriptor - the parameter descriptor
    
    Returns:
    
    the standard deviation of the specified parameter descriptor
    
    Throws:
    
    IllegalArgumentException - if the parameter descriptor is not associated with this covariance matrix
  - getCorrelationCoefficientsMatrix
```
public SymmetricPositiveMatrix getCorrelationCoefficientsMatrix()
```
    Gets the correlation matrix.
    The correlation matrix is a symmetric positive matrix which contains the correlation coefficients of this covariance matrix. The correlation coefficients for the diagonal elements are equal to 1 by definition. For off-diagonal elements, they are equal to C_i,j/σ_iσ_j, where σ_i and σ_j are the standard deviations for the i^th and j^th elements.
    
    Returns:
    
    the correlation coefficients matrix
  - getCorrelationCoefficient
```
public double getCorrelationCoefficient(int row,
                                        int column)
```
    Gets the correlation coefficient ρ_i,j for the specified row and column indexes.
    If i is equal to j, ρ_i,j is equal to 1 by definition. Otherwise, ρ_i,j is equal to C_i,j / (σ_i*σ_j). If the division cannot be computed because σ_i*σ_j is too small, ρ_i,j is set to 0.
    
    Parameters:
    
    row - the row index
    
    column - the column index
    
    Returns:
    
    the correlation coefficient for the specified row and column
    
    Throws:
    
    IllegalArgumentException - if one of the provided row/column indexes is not valid
  - getCorrelationCoefficient
```
public double getCorrelationCoefficient(ParameterDescriptor parameterDescriptor1,
                                        ParameterDescriptor parameterDescriptor2)
```
    Gets the correlation coefficient ρ_i,j associated with the specified parameter descriptors, the first parameter* descriptor being mapped to the rows of the covariance matrix (index "i"), while the second parameter descriptor is mapped to the columns of the covariance matrix (index "j").
    If i is equal to j, ρ_i,j is equal to 1 by definition. Otherwise, ρ_i,j is equal to C_i,j / (σ_i*σ_j). If the division cannot be computed because σ_i*σ_j is too small, ρ_i,j is set to 0.
    
    Parameters:
    
    parameterDescriptor1 - the first parameter descriptor
    
    parameterDescriptor2 - the second parameter descriptor
    
    Returns:
    
    the correlation coefficient associated with the provided parameter descriptors
    
    Throws:
    
    IllegalArgumentException - if one of the parameter descriptors is not associated with this covariance matrix
  - quadraticMultiplication
```
public Covariance quadraticMultiplication(RealMatrix m)
```
    Gets the result of the quadratic multiplication M×C×M^T, where C is this covariance matrix and M is the provided matrix, and associates the computed matrix with default parameter descriptors.
    
    Parameters:
    
    m - the matrix M
    
    Returns:
    
    M×C×M^T
    
    Throws:
    
    NullArgumentException - if the matrix M is @null
    
    DimensionMismatchException - if this matrix and the matrices M and M^T are not multiplication compatible
  - quadraticMultiplication
```
public Covariance quadraticMultiplication(RealMatrix m,
                                          boolean isTranspose)
```
    Gets the result of the quadratic multiplication M×C×M^T, where C is this covariance matrix and M or M^T is the provided matrix, and associates the computed matrix with default parameter descriptors.
    
    Parameters:
    
    m - the matrix M
    
    isTranspose - if true, assume the matrix provided is M^T, otherwise assume it is M
    
    Returns:
    
    M×C×M^T
    
    Throws:
    
    NullArgumentException - if the matrix M is @null
    
    DimensionMismatchException - if this matrix and the matrices M and M^T are not multiplication compatible
  - quadraticMultiplication
```
public Covariance quadraticMultiplication(RealMatrix m,
                                          Collection<ParameterDescriptor> newParameterDescriptors)
```
    Gets the result of the quadratic multiplication M×C×M^T, where C is this covariance matrix and M is the provided matrix, and associates the computed matrix with the specified parameter descriptors.
    
    Parameters:
    
    m - the matrix M
    
    newParameterDescriptors - the parameter descriptors to be associated with the computed covariance matrix
    
    Returns:
    
    M×C×M^T
    
    Throws:
    
    NullArgumentException - if the matrix M is @null
    
    DimensionMismatchException - if this matrix and the matrices M and M^T are not multiplication compatible
    
    IllegalArgumentException - if the number of parameter descriptors does not match the size of the covariance matrix, or if the collection of parameter descriptors contains any duplicate
  - quadraticMultiplication
```
public Covariance quadraticMultiplication(RealMatrix m,
                                          Collection<ParameterDescriptor> newParameterDescriptors,
                                          boolean isTranspose)
```
    Gets the result of the quadratic multiplication M×C×M^T, where C is this covariance matrix and M or M^T is the provided matrix, and associates the computed matrix with the specified parameter descriptors.
    
    Parameters:
    
    m - the matrix M
    
    newParameterDescriptors - the parameter descriptors to be associated with the computed covariance matrix
    
    isTranspose - if true, assume the matrix provided is M^T, otherwise assume it is M
    
    Returns:
    
    M×C×M^T
    
    Throws:
    
    NullArgumentException - if the matrix M is @null
    
    DimensionMismatchException - if this matrix and the matrix M or M^T is not multiplication compatible
    
    IllegalArgumentException - if the provided matrix M is null, if the number of parameter descriptors does not match the size of the covariance matrix, or if the collection of parameter descriptors contains any duplicate
  - add
```
public Covariance add(SymmetricPositiveMatrix m)
```
    Adds the symmetric positive semi-definite matrix M to this covariance matrix and returns a new Covariance instance associated with the computed matrix and the same parameter descriptors.
    
    Parameters:
    
    m - the covariance matrix M to be added
    
    Returns:
    
    a new Covariance instance whose matrix is the sum of the two covariance matrices
    
    Throws:
    
    NullArgumentException - if the matrix M is @null
    
    MatrixDimensionMismatchException - if the two matrices are not addition compatible
  - positiveScalarMultiply
```
public Covariance positiveScalarMultiply(double d)
```
    Multiplies this covariance matrix by a positive scalar.
    
    Parameters:
    
    d - the scalar by which the matrix is multiplied (≥0)
    
    Returns:
    
    this covariance matrix multiplied by the provided scalar
    
    Throws:
    
    NotPositiveException - if the provided scalar is negative
  - getMahalanobisDistance
```
public double getMahalanobisDistance(RealVector point)
```
    Gets the Mahalanobis distance of a point with respect to this covariance matrix, assuming its mean value is zero.
    The Mahalanobis distance is defined by:
    dM(P) = sqrt(P^T x C^-1 x P)
    with P the point and C the covariance matrix (centered on 0).
    
    Parameters:
    
    point - the point P
    
    Returns:
    
    the Mahalanobis distance of the provided point with respect to this covariance matrix
    
    Throws:
    
    SingularMatrixException - if the covariance matrix is singular
    
    DimensionMismatchException - if the provided vector do not have the same size as the covariance matrix
    
    ArithmeticException - if the computed Mahalanobis distance is negative
    
    See Also:
    
    Mahalanobis distance (wikipedia)
  - getMahalanobisDistance
```
public double getMahalanobisDistance(RealVector point,
                                     RealVector mean)
```
    Gets the Mahalanobis distance of a point with respect to this covariance matrix.
    The Mahalanobis distance is defined by:
    dM(P,M) = sqrt((P-M)^T x C^-1 x (P-M))
    with P the point and C the covariance matrix centered on M.
    
    Parameters:
    
    point - the point
    
    mean - the mean value of the covariance
    
    Returns:
    
    the Mahalanobis distance of the provided point with respect to this covariance matrix
    
    Throws:
    
    SingularMatrixException - if the covariance matrix is singular
    
    DimensionMismatchException - if the provided vectors have different sizes, or if they do not have the same size as the covariance matrix
    
    ArithmeticException - if the computed Mahalanobis distance is negative
    
    See Also:
    
    Mahalanobis distance (wikipedia)
  - toString
```
public String toString()
```
    Returns a string representation of this instance which includes the name of the class and the names of the associated parameter descriptors (the covariance matrix itself is not printed).
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    string representation of this instance
  - toString
```
public String toString(RealMatrixFormat realMatrixFormat)
```
    Returns a string representation of this instance which includes the name of the class (if requested), the names of the associated parameter descriptors and the the covariance matrix (if the specified matrix format is not null).
    
    Parameters:
    
    realMatrixFormat - the format to use when printing the covariance matrix
    
    Returns:
    
    string representation of this instance
  - toString
```
public String toString(RealMatrixFormat realMatrixFormat,
                       String nameSeparator,
                       String fieldSeparator,
                       boolean printClassName,
                       boolean reverseOrder)
```
    Returns a string representation of this instance which includes the name of the class (if requested), the names of the associated parameter descriptors and the the covariance matrix (if the specified matrix format is not null).
    
    Parameters:
    
    realMatrixFormat - the format to use when printing the covariance matrix
    
    nameSeparator - the string to use as a separator between the names of the parameter descriptors
    
    fieldSeparator - the string to use as a separator between the field values of a parameter descriptor
    
    printClassName - whether or not the name of this class should be printed
    
    reverseOrder - whether or not the field values of each parameter descriptor should be printed in reverse order
    
    Returns:
    
    string representation of this instance
  - copy
```
public Covariance copy()
```
    Gets a copy of this Covariance instance.
    This method performs a shallow copy of the parameter descriptors list and a deep copy of the covariance matrix.
    
    Returns:
    
    a copy of this Covariance instance
    
    See Also:
    
    ParameterDescriptor.copy()
  - equals
```
public boolean equals(Object object)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object

Class Covariance

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_FIELD_SEPARATOR

DEFAULT_NAME_SEPARATOR

Constructor Detail

Covariance

Covariance

Method Detail

indexOf

getSize

getCovarianceMatrix

getParameterDescriptors

getParameterDescriptor

getSubCovariance

getSubCovariance

getVarianceMatrix

getVariance

getVariance

getStandardDeviationMatrix

getStandardDeviation

getStandardDeviation

getCorrelationCoefficientsMatrix

getCorrelationCoefficient

getCorrelationCoefficient

quadraticMultiplication

quadraticMultiplication

quadraticMultiplication

quadraticMultiplication

add

positiveScalarMultiply

getMahalanobisDistance

getMahalanobisDistance

toString

toString

toString

copy

equals

hashCode