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, y)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

• y (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

Returns:

Accuracy

Return type:

Union[np.ndarray, torch.Tensor]

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])

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, y, *args)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

• y (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

Returns:

Similarities

Return type:

Union[np.ndarray, torch.Tensor]

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, y, *args)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

• y (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

Returns:

Distances

Return type:

Union[np.ndarray, torch.Tensor]

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.])

See also

mvpy.math.cosine()

mvpy.math.crossvalidated module

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

mvpy.math.crossvalidated.cv_euclidean(x, y)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Tensor ([[samples x ]samples x ]features)

• y (Union[np.ndarray, torch.Tensor]) – Tensor ([[samples x ]samples x ]features)

Returns:

Cross-validated distances

Return type:

Union[np.ndarray, torch.Tensor]

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, y, Σ)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Matrix ([samples …] x features)

• y (Union[np.ndarray, torch.Tensor]) – Matrix ([samples …] x features)

• Σ (Union[np.ndarray, torch.Tensor]) – Precision matrix (features x features)

Returns:

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

Return type:

Union[np.ndarray, torch.Tensor]

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])

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, y, *args)

Computes euclidean distances between x and y.

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Matrix ([samples …] x features)

• y (Union[np.ndarray, torch.Tensor]) – Matrix ([samples …] x features)

Returns:

Vector or matrix of euclidean distances

Return type:

Union[np.ndarray, torch.Tensor]

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])

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, y, Σ, *args)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Matrix ([samples …] x features)

• y (Union[np.ndarray, torch.Tensor]) – Matrix ([samples …] x features)

• Σ (Union[np.ndarray, torch.Tensor]) – Precision matrix (features x features)

Returns:

Vector or matrix of distances.

Return type:

Union[np.ndarray, torch.Tensor]

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])

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, y, *args)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Matrix ([samples …] x features)

• y (Union[np.ndarray, torch.Tensor]) – Matrix ([samples …] x features)

Returns:

Vector or matrix of pearson correlations

Return type:

Union[np.ndarray, torch.Tensor]

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, y, *args)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

• y (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

Returns:

Distances

Return type:

Union[np.ndarray, torch.Tensor]

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)

See also

mvpy.math.pearsonr()

mvpy.math.rank module

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

mvpy.math.rank.rank(x)

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

Parameters:

x (Union[np.ndarray, torch.Tensor]) – Unranked data ([samples x …] x features).

Returns:

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

Return type:

Union[np.ndarray, torch.Tensor]

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])

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, y_score)

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

Parameters:

• y_true (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

• y_score (Union[np.ndarray, torch.Tensor]) – Vector/Matrix/Tensor

Returns:

Accuracy

Return type:

Union[np.ndarray, torch.Tensor]

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.)

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, y, *args)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Matrix to compute correlation with.

• y (Union[np.ndarray, torch.Tensor]) – Matrix to compute correlation with.

Returns:

Spearman correlations.

Return type:

Union[np.ndarray, torch.Tensor]

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)

See also

mvpy.math.pearsonr(), mvpy.math.rank()

mvpy.math.spearmanr.spearmanr_d(x, y, *args)

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

Parameters:

• x (Union[np.ndarray, torch.Tensor]) – Matrix to compute distance with.

• y (Union[np.ndarray, torch.Tensor]) – Matrix to compute distance with.

Returns:

Spearman distances.

Return type:

Union[np.ndarray, torch.Tensor]

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)

See also

mvpy.math.spearmanr(), mvpy.math.pearsonr(), mvpy.math.rank()

Module contents