Trait ndarray_stats::CorrelationExt

pub trait CorrelationExt<A, S>
where
    S: Data<Elem = A>,
{
    // Required methods
    fn cov(&self, ddof: A) -> Result<Array2<A>, EmptyInput>
       where A: Float + FromPrimitive;
    fn pearson_correlation(&self) -> Result<Array2<A>, EmptyInput>
       where A: Float + FromPrimitive;
    fn __private__(&self, _: PrivateMarker);
}

Extension trait for ArrayBase providing functions to compute different correlation measures.

Required Methods

fn cov(&self, ddof: A) -> Result<Array2<A>, EmptyInput>

where A: Float + FromPrimitive,

Return the covariance matrix C for a 2-dimensional array of observations M.

Let (r, o) be the shape of M:

• r is the number of random variables;
• o is the number of observations we have collected for each random variable.

Every column in M is an experiment: a single observation for each random variable. Each row in M contains all the observations for a certain random variable.

The parameter ddof specifies the “delta degrees of freedom”. For example, to calculate the population covariance, use ddof = 0, or to calculate the sample covariance (unbiased estimate), use ddof = 1.

The covariance of two random variables is defined as:

               1       n
cov(X, Y) = ――――――――   ∑ (xᵢ - x̅)(yᵢ - y̅)
            n - ddof  i=1

where

    1   n
x̅ = ―   ∑ xᵢ
    n  i=1

and similarly for ̅y.

If M is empty (either zero observations or zero random variables), it returns Err(EmptyInput).

Panics if ddof is negative or greater than or equal to the number of observations, or if the type cast of n_observations from usize to A fails.

Example

use ndarray::{aview2, arr2};
use ndarray_stats::CorrelationExt;

let a = arr2(&[[1., 3., 5.],
               [2., 4., 6.]]);
let covariance = a.cov(1.).unwrap();
assert_eq!(
   covariance,
   aview2(&[[4., 4.], [4., 4.]])
);

fn pearson_correlation(&self) -> Result<Array2<A>, EmptyInput>

where A: Float + FromPrimitive,

Return the Pearson correlation coefficients for a 2-dimensional array of observations M.

Let (r, o) be the shape of M:

• r is the number of random variables;
• o is the number of observations we have collected for each random variable.

Every column in M is an experiment: a single observation for each random variable. Each row in M contains all the observations for a certain random variable.

The Pearson correlation coefficient of two random variables is defined as:

             cov(X, Y)
rho(X, Y) = ――――――――――――
            std(X)std(Y)

Let R be the matrix returned by this function. Then

R_ij = rho(X_i, X_j)

If M is empty (either zero observations or zero random variables), it returns Err(EmptyInput).

Panics if the type cast of n_observations from usize to A fails or if the standard deviation of one of the random variables is zero and division by zero panics for type A.

Example

use approx;
use ndarray::arr2;
use ndarray_stats::CorrelationExt;
use approx::AbsDiffEq;

let a = arr2(&[[1., 3., 5.],
               [2., 4., 6.]]);
let corr = a.pearson_correlation().unwrap();
let epsilon = 1e-7;
assert!(
    corr.abs_diff_eq(
        &arr2(&[
            [1., 1.],
            [1., 1.],
        ]),
        epsilon
    )
);

fn __private__(&self, _: PrivateMarker)

This method makes this trait impossible to implement outside of ndarray-stats so that we can freely add new methods, etc., to this trait without breaking changes.

We don’t anticipate any other crates needing to implement this trait, but if you do have such a use-case, please let us know.

Warning This method is not considered part of the public API, and client code should not rely on it being present. It may be removed in a non-breaking release.

Implementations on Foreign Types

impl<A: 'static, S> CorrelationExt<A, S> for ArrayBase<S, Ix2>

where S: Data<Elem = A>,

fn cov(&self, ddof: A) -> Result<Array2<A>, EmptyInput>

where A: Float + FromPrimitive,

fn pearson_correlation(&self) -> Result<Array2<A>, EmptyInput>

where A: Float + FromPrimitive,

fn __private__(&self, _: PrivateMarker)

Implementors