mvpy.math package

Submodules

mvpy.math.accuracy module

Functions to compute accuracy in a nice and vectorised manner using either numpy or torch.

mvpy.math.accuracy.accuracy(x: ndarray | Tensor, y: ndarray | Tensor) → ndarray | Tensor

Compute accuracy between x and y. Note that accuracy is always computed over the final dimension.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

yUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

Returns:

Union[np.ndarray, torch.Tensor]

Accuracy

Notes

Accuracy is defined as:

\[\text{accuracy}(x, y) = \frac{1}{N}\sum_i^N{1(x_i = y_i)}\]

Examples

>>> import torch
>>> from mvpy.math import accuracy
>>> x = torch.tensor([1, 0])
>>> y = torch.tensor([-1, 0])
>>> accuracy(x, y)
tensor([0.5])

The torch package contains data structures for multi-dimensional

mvpy.math.cosine module

Functions to compute cosine (dis-)similarity in a nice and vectorised manner using either numpy or torch.

mvpy.math.cosine.cosine(x: ndarray | Tensor, y: ndarray | Tensor, *args: Any) → ndarray | Tensor

Compute cosine similarities between x and y. Note that similarities are always computed over the final dimension.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

yUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

Returns:

Union[np.ndarray, torch.Tensor]

Similarities

Notes

Cosine similarity is defined as:

\[\text{cosine}(x, y) = \frac{\mathbf{x} \cdot \mathbf{y}}{\|\mathbf{x}\| \|\mathbf{y}\|}\]

Examples

>>> import torch
>>> from mvpy.math import cosine
>>> x = torch.tesor([1, 0])
>>> y = torch.tensor([-1, 0])
>>> cosine(x, y)
tensor([-1.])

mvpy.math.cosine.cosine_d(x: ndarray | Tensor, y: ndarray | Tensor, *args: Any) → ndarray | Tensor

Compute cosine distances between x and y. Note that distances are always computed over the final dimension.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

yUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

Returns:

Union[np.ndarray, torch.Tensor]

Distances

See also

mvpy.math.cosine()

Notes

Cosine distances are computed as \(1 - \text{cosine}(x, y)\).

Examples

>>> import torch
>>> from mvpy.math import cosine_d
>>> x = torch.tesor([1, 0])
>>> y = torch.tensor([-1, 0])
>>> cosine_d(x, y)
tensor([2.])

The torch package contains data structures for multi-dimensional

mvpy.math.crossvalidated module

Wrapper functions to compute cross-validated metrics from the metrics already in this package.

mvpy.math.crossvalidated.cv_euclidean(x: ndarray | Tensor, y: ndarray | Tensor) → ndarray | Tensor

Computes cross-validated euclidean distances between vectors in x and y.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Tensor ([[samples x ]samples x ]features)

yUnion[np.ndarray, torch.Tensor]

Tensor ([[samples x ]samples x ]features)

Returns:

Union[np.ndarray, torch.Tensor]

Cross-validated distances

Notes

Cross-validated euclidean distances are defined as:

\[d(x, y)^2 = \sum (x_{i} - y_{i})(x_{j} - y_{j})\]

where \(i\) and \(j\) refer to the indices in the cross-validation folds. Note that this is, therefore, technically a squared measure. For more information, see [1].

References

[1]

Walther, A., Nili, H., Ejaz, N., Alink, A., Kriegeskorte, N., & Diedrichsen, J. (2016). Reliability of dissimilarity measures for multi-voxel pattern analysis. NeuroImage, 137, 188-200. 10.1016/j.neuroimage.2015.12.012

Examples

>>> import torch
>>> from mvpy.math import cv_euclidean
>>> x = torch.randn(100, 10)
>>> y = torch.randn(100, 10)
>>> d = cv_euclidean(x, y)
>>> d.shape
torch.Size([100])

mvpy.math.crossvalidated.cv_mahalanobis(x: ndarray | Tensor, y: ndarray | Tensor, Σ: ndarray | Tensor) → ndarray | Tensor

Computes cross-validated mahalanobis distances between x and y. This is sometimes also referred to as the crossnobis distance.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix ([samples …] x features)

yUnion[np.ndarray, torch.Tensor]

Matrix ([samples …] x features)

ΣUnion[np.ndarray, torch.Tensor]

Precision matrix (features x features)

Returns:

Union[np.ndarray, torch.Tensor]

Vector or matrix of distances. Note that this will eliminate the trial dimension, too, during cross-validation.

Notes

Crossnobis distance is defined as:

\[d(x, y)^2 = (x_i - y_i)^T Σ^{-1} (x_j - y_j)\]

where \(x\) and \(y\) are the matrices to compute the distance between, and \(Σ\) is the covariance matrix. Note that here \(i\) and \(j\) refer to folds of a cross-validation. Note also that, principally, this metric is a squared measure. For more information, see [2].

References

[2]

Diedrichsen, J., Provost, S., & Zareamoghaddam, H. (2016). On the distribution of cross-validated Mahalanobis distances. arXiv. 10.48550/arXiv.1607.01371

Examples

>>> import torch
>>> from mvpy.estimators import Covariance
>>> from mvpy.math import cv_mahalanobis
>>> x, y = torch.normal(0, 1, (100, 50, 60)), torch.normal(0, 1, (100, 50, 60))
>>> Σ = Covariance().fit(torch.cat((x, y), 0).swapaxes(1, 2)).covariance_
>>> Σ = torch.linalg.inv(Σ)
>>> d = cv_mahalanobis(x, y, Σ)
>>> d.shape
torch.Size([50])

The torch package contains data structures for multi-dimensional

mvpy.math.euclidean module

Functions to compute euclidean distances in a nice and vectorised manner using either numpy or torch.

mvpy.math.euclidean.euclidean(x: ndarray | Tensor, y: ndarray | Tensor, *args: Any) → ndarray | Tensor

Computes euclidean distances between x and y.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix ([samples …] x features)

yUnion[np.ndarray, torch.Tensor]

Matrix ([samples …] x features)

Returns:

Union[np.ndarray, torch.Tensor]

Vector or matrix of euclidean distances

Notes

Euclidean distances are defined as:

\[d(x, y) = \sqrt{\sum_{i=1}^n (x_i - y_i)^2}\]

where \(x_i\) and \(y_i\) are the \(i\)-th elements of \(x\) and \(y\), respectively.

Examples

>>> import torch
>>> import mvpy as mv
>>> x, y = torch.normal(0, 1, (10, 50)), torch.normal(0, 1, (10, 50))
>>> d = mv.math.euclidean(x, y)
>>> d.shape
torch.Size([10])

The torch package contains data structures for multi-dimensional

mvpy.math.kernel_linear module

Functions to compute 2D linear kernels (as used in, for example, SVC).

mvpy.math.kernel_linear.kernel_linear(x: ndarray | Tensor, y: ndarray | Tensor, *args: Any) → ndarray | Tensor

Compute the linear kernel function.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix x of shape (n_samples, n_features).

yUnion[np.ndarray, torch.Tensor]

Matrix y of shape (n_samples, n_features).

Returns:

kUnion[np.ndarray, torch.Tensor]

Kernel matrix of shape (n_samples, n_samples).

Notes

The linear kernel is computed as:

\[\kappa(x, y) = x y^T\]

Note that, unlike other math functions, this is specifically for 2D inputs and outputs.

The torch package contains data structures for multi-dimensional

mvpy.math.kernel_poly module

Functions to compute 2D polynomial kernels (as used in, for example, SVC).

Functional interface.

mvpy.math.kernel_poly.kernel_poly(x: ndarray | Tensor, y: ndarray | Tensor, γ: float, coef0: float, degree: float, *args: Any) → ndarray | Tensor

Compute the polynomial kernel function.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix x of shape (n_samples, n_features).

yUnion[np.ndarray, torch.Tensor]

Matrix y of shape (n_samples, n_features).

γfloat

Gamma parameter as float.

coef0float

Coefficient parameter as float.

degreefloat

Degree of the polynomial as float.

Returns:

kUnion[np.ndarray, torch.Tensor]

Kernel matrix of shape (n_samples, n_samples).

Notes

The polynomial kernel is computed as:

\[\kappa(x, y) = (c_0 + \gamma x y^T)^d\]

Note that, unlike other math functions, this is specifically for 2D inputs and outputs.

The torch package contains data structures for multi-dimensional

mvpy.math.kernel_rbf module

Functions to compute 2D rbf kernels (as used in, for example, SVC).

Functional interface.

mvpy.math.kernel_rbf.kernel_rbf(x: ndarray | Tensor, y: ndarray | Tensor, γ: float, *args: Any) → ndarray | Tensor

Compute the radial basis kernel function.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix x of shape (n_samples, n_features).

yUnion[np.ndarray, torch.Tensor]

Matrix y of shape (n_samples, n_features).

γfloat

Gamma parameter as float.

Returns:

kUnion[np.ndarray, torch.Tensor]

Kernel matrix of shape (n_samples, n_samples).

vert vert^2

Note that, unlike other math functions, this is specifically for 2D inputs and outputs.

The torch package contains data structures for multi-dimensional

mvpy.math.kernel_sigmoid module

Functions to compute 2D sigmoid kernels (as used in, for example, SVC).

Functional interface.

mvpy.math.kernel_sigmoid.kernel_sigmoid(x: ndarray | Tensor, y: ndarray | Tensor, γ: float, coef0: float, *args: Any) → ndarray | Tensor

Compute the sigmoid kernel function.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix x of shape (n_samples, n_features).

yUnion[np.ndarray, torch.Tensor]

Matrix y of shape (n_samples, n_features).

γfloat

Gamma parameter as float.

coef0float

Coefficient parameter as float.

Returns:

kUnion[np.ndarray, torch.Tensor]

Kernel matrix of shape (n_samples, n_samples).

Notes

The sigmoid kernel is computed as:

\[\kappa(x, y) = anh(c_0 + \gamma x y^T)\]

Note that, unlike other math functions, this is specifically for 2D inputs and outputs.

The torch package contains data structures for multi-dimensional

mvpy.math.mahalanobis module

Functions to compute mahalanobis distances in a nice and vectorised manner using either numpy or torch.

mvpy.math.mahalanobis.mahalanobis(x: ndarray | Tensor, y: ndarray | Tensor, Σ: ndarray | Tensor, *args: Any) → ndarray | Tensor

Computes mahalanobis distance between x and y using inverse covariance matrix Σ.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix ([samples …] x features)

yUnion[np.ndarray, torch.Tensor]

Matrix ([samples …] x features)

ΣUnion[np.ndarray, torch.Tensor]

Precision matrix (features x features)

Returns:

Union[np.ndarray, torch.Tensor]

Vector or matrix of distances.

Notes

Mahalanobis distance is defined as:

\[d(x, y) = \sqrt{(x - y)^T Σ^{-1} (x - y)}\]

where \(x\) and \(y\) are the matrices to compute the distance between, and \(Σ\) is the covariance matrix.

Examples

>>> import torch
>>> from mvpy.math import mahalanobis
>>> from mvpy.estimators import Covariance
>>> x, y = torch.normal(0, 1, (10, 50)), torch.normal(0, 1, (10, 50))
>>> Σ = Covariance().fit(torch.cat((x, y), 0)).covariance_
>>> Σ = torch.linalg.inv(Σ)
>>> d = mahalanobis(x, y, Σ)
>>> d.shape
torch.Size([10])

The torch package contains data structures for multi-dimensional

mvpy.math.pearsonr module

Functions to compute Pearson correlation or distance in a nice and vectorised manner using either numpy or torch.

mvpy.math.pearsonr.pearsonr(x: ndarray | Tensor, y: ndarray | Tensor, *args: Any) → ndarray | Tensor

Computes pearson correlations between x and y. Note that correlations are always computed over the final dimension.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix ([samples …] x features)

yUnion[np.ndarray, torch.Tensor]

Matrix ([samples …] x features)

Returns:

Union[np.ndarray, torch.Tensor]

Vector or matrix of pearson correlations

Notes

Pearson correlations are defined as:

\[r = \frac{\sum{(x_i - \bar{x})(y_i - \bar{y})}}{\sqrt{\sum{(x_i - \bar{x})^2} \sum{(y_i - \bar{y})^2}}}\]

where \(x_i\) and \(y_i\) are the \(i\)-th elements of \(x\) and \(y\), respectively.

Examples

>>> import torch
>>> from mvpy.math import pearsonr
>>> x = torch.tensor([1, 2, 3])
>>> y = torch.tensor([4, 5, 6])
>>> pearsonr(x, y)
tensor(1., dtype=torch.float64)

mvpy.math.pearsonr.pearsonr_d(x: ndarray | Tensor, y: ndarray | Tensor, *args: Any) → ndarray | Tensor

Computes Pearson distance between x and y. Note that distances are always computed over the final dimension in your inputs.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

yUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

Returns:

Union[np.ndarray, torch.Tensor]

Distances

See also

mvpy.math.pearsonr()

Notes

Pearson distance is defined as \(1 - \text{pearsonr}(x, y)\).

Examples

>>> import torch
>>> from mvpy.math import pearsonr_d
>>> x = torch.tensor([1, 2, 3])
>>> y = torch.tensor([-1, -2, -3])
>>> pearsonr_d(x, y)
tensor(2.0, dtype=torch.float64)

The torch package contains data structures for multi-dimensional

mvpy.math.r2 module

Functions to rank data in a nice and vectorised manner using either numpy or torch.

mvpy.math.r2.r2(y: ndarray | Tensor, y_h: ndarray | Tensor) → ndarray | Tensor

Rank data in x along its final feature dimension. Ties are computed as averages.

Parameters:

yUnion[np.ndarray, torch.Tensor]

True outcomes of shape ([n_samples, ...,] n_features).

y_hUnion[np.ndarray, torch.Tensor]

Predicted outcomes of shape ([n_samples, ...,] n_features).

Returns:

rUnion[np.ndarray, torch.Tensor]

R2 scores of shape ([n_samples, ...]).

Examples

>>> import torch
>>> from mvpy.math import rank
>>> y = torch.tensor([1.0, 2.0, 3.0])
>>> y_h = torch.tensor([1.0, 2.0, 3.0])
>>> r2(x)
tensor([1.0])

The torch package contains data structures for multi-dimensional

mvpy.math.rank module

Functions to rank data in a nice and vectorised manner using either numpy or torch.

mvpy.math.rank.rank(x: ndarray | Tensor) → ndarray | Tensor

Rank data in x along its final feature dimension. Ties are computed as averages.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Unranked data ([samples x …] x features).

Returns:

rUnion[np.ndarray, torch.Tensor]

Ranked data ([samples x …] x features).

Examples

>>> import torch
>>> from mvpy.math import rank
>>> x = torch.tensor([2, 0.5, 1, 1])
>>> rank(x)
tensor([4.0000, 1.0000, 2.5000, 2.5000])

The torch package contains data structures for multi-dimensional

mvpy.math.roc_auc module

Functions to compute roc-auc in a nice and vectorised manner using either numpy or torch.

mvpy.math.roc_auc.roc_auc(y_true: ndarray | Tensor, y_score: ndarray | Tensor) → ndarray | Tensor

Compute ROC AUC score between y_true and y_score. Note that ROC AUC is always computed over the final dimension.

Parameters:

y_trueUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

y_scoreUnion[np.ndarray, torch.Tensor]

Vector/Matrix/Tensor

Returns:

Union[np.ndarray, torch.Tensor]

Accuracy

Notes

ROC AUC is computed using the Mann-Whitney U formula:

\[\text{ROCAUC}(y, \hat{y}) = \frac{R_{+} - \frac{P * (P + 1)}{2}}}{P * N}\]

where \(R_{+}\) is the sum of ranks for positive classes, \(P\) is the number of positive samples, and \(N\) is the number of negative samples.

In the case that labels are not binary, we create unique binary labels by one-hot encoding the labels and then take the macro-average over classes.

Examples

>>> import torch
>>> from mvpy.math import roc_auc
>>> y_true = torch.tensor([1., 0.])
>>> y_score = torch.tensor([-1., 1.])
>>> roc_auc(y_true, y_score)
tensor(0.)

>>> import torch
>>> from mvpy.math import roc_auc
>>> y_true = torch.tensor([0., 1., 2.])
>>> y_score = torch.tensor([[-1., 1., 1.], [1., -1., 1.], [1., 1., -1.]])
>>> roc_auc(y_true, y_score)
tensor(0.)

The torch package contains data structures for multi-dimensional

mvpy.math.spearmanr module

Functions to compute Spearman correlation or distance in a nice and vectorised manner using either numpy or torch.

mvpy.math.spearmanr.spearmanr(x: ndarray | Tensor, y: ndarray | Tensor, *args: Any) → ndarray | Tensor

Compute Spearman correlation between x and y. Note that correlations are always computed over the final dimension in your inputs.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix to compute correlation with.

yUnion[np.ndarray, torch.Tensor]

Matrix to compute correlation with.

Returns:

Union[np.ndarray, torch.Tensor]

Spearman correlations.

See also

mvpy.math.pearsonr()

mvpy.math.rank()

Notes

Spearman correlations are defined as Pearson correlations between the ranks of x and y.

Examples

>>> import torch
>>> from mvpy.math import spearmanr
>>> x = torch.tensor([1, 5, 9])
>>> y = torch.tensor([1, 50, 60])
>>> spearmanr(x, y)
tensor(1., dtype=torch.float64)

mvpy.math.spearmanr.spearmanr_d(x: ndarray | Tensor, y: ndarray | Tensor, *args: Any) → ndarray | Tensor

Compute Spearman distance between x and y. Note that distances are always computed over the final dimension in your inputs.

Parameters:

xUnion[np.ndarray, torch.Tensor]

Matrix to compute distance with.

yUnion[np.ndarray, torch.Tensor]

Matrix to compute distance with.

Returns:

Union[np.ndarray, torch.Tensor]

Spearman distances.

See also

mvpy.math.spearmanr()

mvpy.math.pearsonr()

mvpy.math.rank()

Notes

Spearman distances are defined as \(1 - \text{spearmanr}(x, y)\).

Examples

>>> import torch
>>> from mvpy.math import spearmanr
>>> x = torch.tensor([1, 5, 9])
>>> y = torch.tensor([1, 50, 60])
>>> spearmanr_d(x, y)
tensor(0., dtype=torch.float64)

The torch package contains data structures for multi-dimensional

Module contents

Wrapper functions to compute cross-validated metrics from