osl_dynamics.inference.metrics

Metrics for evaluating model performance.

Module Contents

Functions

alpha_correlation(alpha_1, alpha_2)	Calculates the correlation between mixing coefficient time series.
confusion_matrix(state_time_course_1, state_time_course_2)	Calculate the confusion_matrix of two state time courses.
dice_coefficient(sequence_1, sequence_2)	Calculates the Dice coefficient.
frobenius_norm(A, B)	Calculates the Frobenius norm of the difference of two matrices.
pairwise_frobenius_distance(matrices)	Calculates the pairwise Frobenius distance of a set of matrices.
pairwise_matrix_correlations(matrices[, remove_diagonal])	Calculate the correlation between (flattened) covariance matrices.
riemannian_distance(M1, M2[, threshold])	Calculate the Riemannian distance between two matrices.
pairwise_riemannian_distances(matrices[, threshold])	Calculate the Riemannian distance between matrices.
pairwise_rv_coefficient(matrices[, remove_diagonal])	Calculate the RV coefficient for two matrices.
pairwise_congruence_coefficient(matrices[, ...])	Computes the congruence coefficient between matrices.
pairwise_l2_distance(arrays[, batch_dims])	Calculate the pairwise L2 distance

osl_dynamics.inference.metrics.alpha_correlation(alpha_1, alpha_2)

Calculates the correlation between mixing coefficient time series.

Parameters:

• alpha_1 (np.ndarray) – First alpha time series. Shape must be (n_samples, n_modes).

• alpha_2 (np.ndarray) – Second alpha time series. Shape must be (n_samples, n_modes).

Returns:

corr – Correlation of each mode in the corresponding alphas. Shape is (n_modes,).

Return type:

np.ndarray

osl_dynamics.inference.metrics.confusion_matrix(state_time_course_1, state_time_course_2)

Calculate the confusion_matrix of two state time courses.

For two state time courses, calculate the confusion matrix (i.e. the disagreement between the state selection for each sample). If either sequence is two dimensional, it will first have argmax(axis=1) applied to it. The produces the expected result for a one-hot encoded sequence but other inputs are not guaranteed to behave.

Parameters:

• state_time_course_1 (np.ndarray) – Mode time course. Shape must be (n_samples, n_states) or (n_samples,).

• state_time_course_2 (np.ndarray) – Mode time course. Shape must be (n_samples, n_states) or (n_samples,).

Returns:

cm – Confusion matrix. Shape is (n_states, n_states).

Return type:

np.ndarray

osl_dynamics.inference.metrics.dice_coefficient(sequence_1, sequence_2)

Calculates the Dice coefficient.

The Dice coefficient is 2 times the number of equal elements (equivalent to true-positives) divided by the sum of the total number of elements.

Parameters:

• sequence_1 (np.ndarray) – A sequence containing either 1D discrete or 2D continuous data. Shape must be (n_samples, n_states) or (n_samples,).

• sequence_2 (np.ndarray) – A sequence containing either 1D discrete or 2D continuous data. Shape must be (n_samples, n_states) or (n_samples,).

Returns:

dice – The Dice coefficient of the two sequences.

Return type:

float

osl_dynamics.inference.metrics.frobenius_norm(A, B)

Calculates the Frobenius norm of the difference of two matrices.

The Frobenius norm is calculated as \(\sqrt{\displaystyle\sum_{ij} |a_{ij} - b_{ij}|^2}\).

Parameters:

• A (np.ndarray) – First matrix. Shape must be (n_modes, n_channels, n_channels) or (n_channels, n_channels).

• B (np.ndarray) – Second matrix. Shape must be (n_modes, n_channels, n_channels) or (n_channels, n_channels)`.

Returns:

norm – The Frobenius norm of the difference of A and B. If A and B are stacked matrices, we sum the Frobenius norm of each sub-matrix.

Return type:

float

osl_dynamics.inference.metrics.pairwise_frobenius_distance(matrices)

Calculates the pairwise Frobenius distance of a set of matrices.

Parameters:

matrices (np.ndarray) – The set of matrices. Shape must be (n_matrices, n_channels, n_channels).

Returns:

pairwise_distance – Matrix of pairwise Frobenius distance. Shape is (n_matrices, n_matrices).

Return type:

np.ndarray

See also

frobenius_norm

osl_dynamics.inference.metrics.pairwise_matrix_correlations(matrices, remove_diagonal=False)

Calculate the correlation between (flattened) covariance matrices.

Parameters:

• matrices (np.ndarray) – Matrices. Shape must be (M, N, N).

• remove_diagonal (bool, optional) – Should we remove the diagonal before calculating the correction?

Returns:

correlations – Pairwise Pearson correlation between elements of each flattened matrix. Shape is (M, M).

Return type:

np.ndarray

osl_dynamics.inference.metrics.riemannian_distance(M1, M2, threshold=0.001)

Calculate the Riemannian distance between two matrices.

The Riemannian distance is defined as \(d = \sqrt{\displaystyle\sum \log(\mathrm{eig}(M_1 * M_2))}\).

Parameters:

• M1 (np.ndarray) – First matrix. Shape must be (N, N).

• M2 (np.ndarray) – Second matrix. Shape must be (N, N).

• threshold (float, optional) – Threshold to apply when there are negative eigenvalues. Must be positive.

Returns:

d – Riemannian distance.

Return type:

float

osl_dynamics.inference.metrics.pairwise_riemannian_distances(matrices, threshold=0.001)

Calculate the Riemannian distance between matrices.

Parameters:

• matrices (np.ndarray) – Matrices. Shape must be (M, N, N).

• threshold (float, optional) – Threshold to apply when there are negative eigenvalues. Must be positive.

Returns:

riemannian_distances – Matrix containing the pairwise Riemannian distances between matrices. Shape is (M, M).

Return type:

np.ndarray

See also

riemannian_distance

osl_dynamics.inference.metrics.pairwise_rv_coefficient(matrices, remove_diagonal=False)

Calculate the RV coefficient for two matrices.

Parameters:

• matrices (np.ndarray) – Set of matrices. Shape must be (M, N, N).

• remove_diagonal (bool, optional) – Should we remove the diagonal before calculating the correction?

Returns:

rv_coefficients – Matrix of pairwise RV coefficients. Shape is (M, M).

Return type:

np.ndarray

osl_dynamics.inference.metrics.pairwise_congruence_coefficient(matrices, remove_diagonal=False)

Computes the congruence coefficient between matrices.

Parameters:

• matrices (np.ndarray) – Set of symmetric semi-positive definite matrices. Shape is (M, N, N).

• remove_diagonal (bool, optional) – Should we remove the diagonal before calculating the correction?

Returns:

congruence_coefficient – Matrix of pairwise congruence coefficients. Shape is (M, M).

Return type:

np.ndarray

osl_dynamics.inference.metrics.pairwise_l2_distance(arrays, batch_dims=0)

Calculate the pairwise L2 distance along the first axis after batch_dims.

Parameters:

• arrays (np.ndarray) – Set of arrays. Shape is (…, n_sessions, …).

• batch_dims (int, optional) – Number of batch dimensions.

Returns:

pairwise_distance – Matrix of pairwise L2 distance. Shape is (…, n_sessions, n_sessions).

Return type:

np.ndarray