API reference

pyRiemann provides a three-part API: Modules with scikit-learn compatible estimators and transformers, Geometry Functions implementing low-level Riemannian geometry operations on SPD/HPD matrices, and Utility Functions for visualization and miscellaneous helpers.

Modules

Scikit-learn compatible estimators and transformers for BCI and SPD matrix pipelines.

Module

SPD Estimation

Covariance, cross-spectra, coherence, and kernel matrix estimators.

10 classes

Module

Embedding

Spectral embedding, locally linear embedding, and t-SNE for SPD manifolds.

3 classes, 2 functions

Module

Classification

MDM, FgMDM, TSClassifier, SVC, and nearest convex hull classifiers.

7 classes, 1 function

Module

Regression

KNN and SVR regressors operating on SPD manifolds.

2 classes

Module

Clustering

K-means, mean shift, Gaussian mixture, and Potato artifact detection.

6 classes

Module

Tangent Space

Projection to and from the tangent space with FGDA.

2 classes

Module

Spatial Filtering

Xdawn, CSP, SPoC, bilinear filter, and AJDC spatial filters.

5 classes

Module

Preprocessing

Whitening transform for SPD matrices.

1 class

Module

Channel Selection

Electrode selection and flat channel removal for EEG.

2 classes

Module

Transfer Learning

Domain adaptation with TLCenter, TLRotate, MDWM, and more.

9 classes, 2 functions

Module

Stats

Permutation tests for distances and classification models.

2 classes

Module

Datasets

Synthetic data generators and oversampling for SPD matrices.

1 class, 6 functions

Geometry Functions

Low-level Riemannian geometry functions for distances, means, geodesics, kernels, and matrix operations on SPD/HPD matrices.

Geometry

Covariance

Covariance estimation, cross-spectrum, normalization, and processing.

11 functions

Geometry

Distances

Riemann, LogEuclid, Wasserstein, and other SPD distance functions.

14 functions

Geometry

Means

Riemannian, Euclidean, log-Euclidean, harmonic, and other mean estimators.

16 functions

Geometry

Medians

Euclidean and Riemannian geometric median estimators.

2 functions

Geometry

Geodesics

Shortest paths on the SPD manifold for various metrics.

8 functions

Geometry

Kernels

Riemannian, Euclidean, and log-Euclidean kernel functions.

4 functions

Geometry

Tangent Space

Exponential, logarithmic maps, inner products and parallel transports.

19 functions

Geometry

Base

Matrix exponential, logarithm, square root, and power functions.

9 functions

Geometry

Approx. Joint Diag.

Pham, RJD, and UWEDGE algorithms for joint diagonalization.

4 functions

Geometry

Matrix Tests

Tests for symmetry, positive definiteness, and Hermitian properties.

12 functions

Utility Functions

Visualization and miscellaneous helpers.

Utils

Visualization

Plotting for embeddings, cospectra, covariance ellipses, and waveforms.

6 functions

---

SPD Matrices Estimation

Covariances([estimator])	Estimation of covariance matrices.
ERPCovariances([classes, estimator, svd])	Estimate special form covariance matrices for ERP.
XdawnCovariances([nfilter, applyfilters, ...])	Estimate special form covariance matrices for ERP combined with Xdawn.
BlockCovariances(block_size[, estimator])	Estimation of block covariance matrices.
CrossSpectra([window, overlap, fmin, fmax, fs])	Estimation of cross-spectral matrices.
CoSpectra([window, overlap, fmin, fmax, fs])	Estimation of co-spectral matrices.
Coherences([window, overlap, fmin, fmax, ...])	Estimation of squared coherence matrices.
TimeDelayCovariances([delays, estimator])	Estimation of covariance matrices with time delay matrices.
Kernels([metric, n_jobs])	Estimation of kernel matrices between channels of time series.
Shrinkage([shrinkage])	Regularization of SPD/HPD matrices by shrinkage.

Embedding

locally_linear_embedding(X, *[, ...])	Perform a Locally Linear Embedding (LLE) of SPD matrices.
barycenter_weights(X, Y, indices[, metric, ...])	Compute barycenter weights of X from Y along the first axis.
SpectralEmbedding([n_components, metric, eps])	Spectral Embedding of SPD/HPD matrices.
LocallyLinearEmbedding([n_components, ...])	Locally Linear Embedding of SPD matrices.
TSNE([n_components, perplexity, metric, ...])	T-distributed Stochastic Neighbor Embedding (t-SNE) of SPD/HPD matrices.

Classification

MDM([metric, n_jobs])	Classification by Minimum Distance to Mean.
FgMDM([metric, tsupdate, n_jobs])	Classification by Minimum Distance to Mean with geodesic filtering.
TSClassifier([metric, tsupdate, clf])	Classification in the tangent space.
KNearestNeighbor([n_neighbors, metric, n_jobs])	Classification by k-nearest neighbors.
SVC(*[, metric, kernel_fct, Cref, C, ...])	Classification by support-vector machine.
MeanField([power_list, method_combination, ...])	Classification by Mean Field.
NearestConvexHull([metric, n_jobs, method])	Classification by Nearest Convex Hull.

class_distinctiveness(X, y[, exponent, ...])

Measure class distinctiveness between classes of SPD/HPD matrices.

Regression

KNearestNeighborRegressor([n_neighbors, metric])	Regression by k-nearest-neighbors.
SVR(*[, metric, kernel_fct, Cref, tol, C, ...])	Regression by support-vector machine.

Clustering

Kmeans([n_clusters, max_iter, metric, ...])	Clustering by k-means with SPD/HPD matrices as inputs.
KmeansPerClassTransform([n_clusters])	Clustering by k-means for each class with SPD/HPD matrices as inputs.
MeanShift([kernel, bandwidth, metric, tol, ...])	Clustering by mean shift with SPD/HPD matrices as inputs.
GaussianMixture([n_components, metric, ...])	Gaussian mixture model.
Potato([metric, threshold, n_iter_max, ...])	Artifact detection with the Riemannian Potato.
PotatoField([n_potatoes, p_threshold, ...])	Artifact detection with the Riemannian Potato Field.

Tangent Space

TangentSpace([metric, tsupdate])	Tangent space projection.
FGDA([metric, tsupdate])	Fisher geodesic discriminant analysis.

Spatial Filtering

Xdawn([nfilter, classes, estimator, ...])	Xdawn algorithm.
CSP([nfilter, metric, log, ajd_method])	CSP spatial filtering with covariance matrices as inputs.
SPoC([nfilter, metric, log, ajd_method])	SPoC spatial filtering with covariance matrices as inputs.
BilinearFilter(filters[, log])	Bilinear spatial filter.
AJDC([window, overlap, fmin, fmax, fs, ...])	AJDC algorithm.

Preprocessing

Whitening([metric, dim_red, verbose])

Whitening, and optional unsupervised dimension reduction.

Channel selection

ElectrodeSelection([nelec, metric, n_jobs])	Channel selection based on a Riemannian geometry criterion.
FlatChannelRemover()	Flat channel removal.

Transfer Learning

encode_domains(X, y, domain)	Encode the domains of the data in the labels.
decode_domains(X_enc, y_enc)	Decode the domains of the data in the labels.
TLSplitter(target_domain, cv)	Class for handling the cross-validation splits of multi-domain data.
TLEstimator(target_domain, estimator[, ...])	Transfer learning wrapper for estimators.
TLClassifier(target_domain, estimator[, ...])	Transfer learning wrapper for classifiers.
TLRegressor(target_domain, estimator[, ...])	Transfer learning wrapper for regressors.
TLDummy()	No transformation for transfer learning.
TLCenter(target_domain[, metric])	Centering for transfer learning.
TLScale(target_domain[, final_dispersion, ...])	Scaling for transfer learning.
TLRotate(target_domain[, weights, metric, ...])	Rotation for transfer learning.
MDWM(domain_tradeoff, target_domain[, ...])	Classification by Minimum Distance to Weighted Mean.

Stats

PermutationDistance([n_perms, metric, mode, ...])	Permutation test based on distance.
PermutationModel([n_perms, model, cv, ...])	Permutation test using any scikit-learn model for scoring.

Datasets

make_gaussian_blobs([n_matrices, n_dim, ...])	Generate SPD matrices for two classes.
make_outliers(n_matrices, mean, sigma[, ...])	Generate outlier matrices.
make_matrices(n_matrices, n_dim, kind[, rs, ...])	Generate matrices with specific properties.
make_masks(n_masks, n_dim0, n_dim1_min[, rs])	Generate masks defined as semi-orthogonal matrices.
sample_gaussian_spd(n_matrices, mean, sigma)	Sample a Riemannian Gaussian distribution.
make_classification_transfer(n_matrices[, ...])	Generate 2x2 SPD matrices for two classes in source and target domains.
RandomOverSampler([metric, ...])	Random over-sampling for SPD/HPD matrices.

Geometry Functions

Geometry functions are low-level building blocks that implement the core Riemannian geometry operations on SPD/HPD matrices (covariance estimation, distances, means, medians, geodesics, kernels, tangent space mappings, base matrix functions, approximate joint diagonalization, and matrix property predicates). They live in the standalone pyriemann.geometry subpackage.

Covariance processing

covariances(X[, estimator])	Estimation of covariance matrices.
covariance_mest(X, m_estimator, *[, init, ...])	Robust M-estimators.
covariance_sch(X)	Schaefer-Strimmer shrunk covariance estimator.
covariance_scm(X, *[, assume_centered, weights])	Sample covariance estimator.
covariances_EP(X, P[, estimator])	Special form covariance matrix, concatenating a prototype P.
covariances_X(*args, **kwargs)
block_covariances(X, blocks[, estimator])	Compute block diagonal covariance.
cross_spectrum(X[, window, overlap, fmin, ...])	Compute the complex cross-spectral matrices of a real signal.
cospectrum(*args, **kwargs)
coherence(X[, window, overlap, fmin, fmax, ...])	Compute squared coherence.
normalize(X, norm)	Normalize a set of square matrices, using corr, trace or determinant.
get_nondiag_weight(X)	Compute non-diagonality weights of a set of square matrices.

Distances

distance(A, B[, metric, squared])	Distance between matrices according to a metric.
distance_chol(A, B[, squared])	Cholesky distance between SPD/HPD matrices.
distance_euclid(A, B[, squared])	Euclidean distance between matrices.
distance_harmonic(A, B[, squared])	Harmonic distance between invertible matrices.
distance_kullback(A, B[, squared])	Kullback-Leibler divergence between SPD/HPD matrices.
distance_kullback_sym(A, B[, squared])	Symmetrized Kullback-Leibler divergence between SPD/HPD matrices.
distance_logchol(A, B[, squared])	Log-Cholesky distance between SPD/HPD matrices.
distance_logdet(A, B[, squared])	Log-det distance between SPD/HPD matrices.
distance_logeuclid(A, B[, squared])	Log-Euclidean distance between SPD/HPD matrices.
distance_poweuclid(A, B, p[, squared])	Power Euclidean distance between SPD/HPD matrices.
distance_riemann(A, B[, squared])	Affine-invariant Riemannian distance between SPD/HPD matrices.
distance_thompson(A, B[, squared])	Thompson distance between SPD/HPD matrices.
distance_wasserstein(A, B[, squared])	Wasserstein distance between SPSD/HPSD matrices.
pairwise_distance(X[, Y, metric, squared])	Pairwise distance matrix.
distance_mahalanobis(X, cov[, mean, squared])	Mahalanobis distance between vectors and a Gaussian distribution.

Means

gmean(X, *args[, metric, sample_weight])	Mean of matrices according to a metric.
mean_ale(X, *[, tol, maxiter, ...])	AJD-based log-Euclidean (ALE) mean of SPD/HPD matrices.
mean_alm(X, *[, tol, maxiter, sample_weight])	Ando-Li-Mathias (ALM) mean of SPD/HPD matrices.
mean_bmp(X, *[, tol, maxiter, sample_weight])	Bini-Meini-Poloni (BMP) mean of SPD/HPD matrices.
mean_cheap(X, *[, tol, maxiter, sample_weight])	Cheap mean of SPD/HPD matrices.
mean_chol(X[, sample_weight])	Mean of SPD/HPD matrices according to the Cholesky metric.
mean_covariance(*args, **kwargs)
mean_euclid(X[, sample_weight])	Mean of matrices according to the Euclidean metric.
mean_harmonic(X[, sample_weight])	Harmonic mean of invertible matrices.
mean_kullback_sym(X[, sample_weight])	Mean of SPD/HPD matrices according to Kullback-Leibler divergence.
mean_logchol(X[, sample_weight])	Mean of SPD/HPD matrices according to the log-Cholesky metric.
mean_logdet(X, *[, tol, maxiter, init, ...])	Mean of SPD/HPD matrices according to the log-det metric.
mean_logeuclid(X[, sample_weight])	Mean of SPD/HPD matrices according to the log-Euclidean metric.
mean_power(X, p, *[, sample_weight, zeta, ...])	Power mean of SPD/HPD matrices.
mean_poweuclid(X, p, *[, sample_weight])	Mean of SPD/HPD matrices according to the power Euclidean metric.
mean_riemann(X, *[, tol, maxiter, init, ...])	Mean of SPD/HPD matrices according to the Riemannian metric.
mean_thompson(X, *[, tol, maxiter, init, ...])	Mean of SPD/HPD matrices according to the Thompson metric.
mean_wasserstein(X[, tol, maxiter, init, ...])	Mean of SPD/HPD matrices according to the Wasserstein metric.
maskedmean_riemann(X, masks, *[, tol, ...])	Masked Riemannian mean of SPD/HPD matrices.
nanmean_riemann(X[, tol, maxiter, init, ...])	Riemannian NaN-mean of SPD/HPD matrices.

Medians

median_euclid(X, *[, tol, maxiter, init, ...])	Euclidean geometric median of matrices.
median_riemann(X, *[, tol, maxiter, init, ...])	Affine-invariant Riemannian geometric median of SPD/HPD matrices.

Geodesics

geodesic(A, B, alpha[, metric])	Geodesic between matrices according to a metric.
geodesic_chol(A, B[, alpha])	Cholesky geodesic between SPD/HPD matrices.
geodesic_euclid(A, B[, alpha])	Euclidean geodesic between matrices.
geodesic_logchol(A, B[, alpha])	Log-Cholesky geodesic between SPD/HPD matrices.
geodesic_logeuclid(A, B[, alpha])	Log-Euclidean geodesic between SPD/HPD matrices.
geodesic_riemann(A, B[, alpha])	Affine-invariant Riemannian geodesic between SPD/HPD matrices.
geodesic_thompson(A, B[, alpha])	Thompson geodesic between SPD/HPD matrices.
geodesic_wasserstein(A, B[, alpha])	Wasserstein geodesic between SPD/HPD matrices.

Kernels

kernel(X[, Y, Cref, metric, reg])	Kernel matrix between matrices according to a specified metric.
kernel_euclid(X[, Y, Cref, reg])	Euclidean kernel between two sets of matrices.
kernel_logeuclid(X[, Y, Cref, reg])	Log-Euclidean kernel between two sets of SPD matrices.
kernel_riemann(X[, Y, Cref, reg])	Affine-invariant Riemannian kernel between two sets of SPD matrices.

Tangent Space

exp_map(X, Cref, *[, metric])	Project matrices back to manifold by exponential map.
exp_map_euclid(X, Cref)	Project matrices back to manifold by Euclidean exponential map.
exp_map_logchol(X, Cref)	Project matrices back to manifold by log-Cholesky exponential map.
exp_map_logeuclid(X, Cref)	Project matrices back to manifold by log-Euclidean exponential map.
exp_map_riemann(X, Cref[, Cm12])	Project matrices back to manifold by Riemannian exponential map.
exp_map_wasserstein(X, Cref)	Project matrices back to manifold by Wasserstein exponential map.
log_map(X, Cref, *[, metric])	Project matrices in tangent space by logarithmic map.
log_map_euclid(X, Cref)	Project matrices in tangent space by Euclidean logarithmic map.
log_map_logchol(X, Cref)	Project matrices in tangent space by log-Cholesky logarithmic map.
log_map_logeuclid(X, Cref)	Project matrices in tangent space by log-Euclidean logarithmic map.
log_map_riemann(X, Cref[, C12])	Project matrices in tangent space by Riemannian logarithmic map.
log_map_wasserstein(X, Cref)	Project matrices in tangent space by Wasserstein logarithmic map.
upper(X)	Return the weighted upper triangular part of matrices.
unupper(T)	Inverse upper function.
tangent_space(X, Cref, *[, metric])	Transform matrices into tangent vectors.
untangent_space(T, Cref, *[, metric])	Transform tangent vectors back to matrices.
innerproduct(X, Y, Cref[, metric])	Inner product according to a specified metric.
innerproduct_euclid(X, Y, *args)	Euclidean inner product.
innerproduct_logeuclid(X, Y, Cref)	Log-Euclidean inner product.
innerproduct_riemann(X, Y, Cref)	Affine-invariant Riemannian inner product.
norm(X, Cref[, metric])	Norm according to a specified metric.
transport(X, A, B[, metric])	Parallel transport according to a specified metric.
transport_euclid(X[, A, B])	Parallel transport for Euclidean metric.
transport_logchol(X, A, B)	Parallel transport for log-Cholesky metric.
transport_logeuclid(X, A, B)	Parallel transport for log-Euclidean metric.
transport_riemann(X, A, B)	Parallel transport for affine-invariant Riemannian metric.

Base

ctranspose(X)	Conjugate transpose operator.
expm(C)	Exponential of SPD/HPD matrices.
invsqrtm(C)	Inverse square root of SPD/HPD matrices.
logm(C)	Logarithm of SPD/HPD matrices.
powm(C, alpha)	Power of SPD/HPD matrices.
sqrtm(C)	Square root of SPD/HPD matrices.
nearest_sym_pos_def(X[, reg])	Find the nearest SPD matrices.
ddexpm(X, Cref)	Directional derivative of the matrix exponential.
ddlogm(X, Cref)	Directional derivative of the matrix logarithm.

Aproximate Joint Diagonalization

ajd(X[, method, init, eps, n_iter_max])	Aproximate joint diagonalization (AJD) according to a method.
ajd_pham(X, *[, init, eps, n_iter_max, ...])	Approximate joint diagonalization based on Pham's algorithm.
rjd(X, *[, init, eps, n_iter_max])	Approximate joint diagonalization based on JADE.
uwedge(X, *[, init, eps, n_iter_max])	Approximate joint diagonalization based on UWEDGE.

Matrix Tests

is_square(X)	Check if matrices are square.
is_sym(X)	Check if all matrices are symmetric.
is_skew_sym(X)	Check if all matrices are skew-symmetric.
is_real(X)	Check if all matrices are strictly real.
is_real_type(X)	Check if matrices are real type.
is_hermitian(X)	Check if all matrices are Hermitian.
is_pos_def(X[, tol, fast_mode])	Check if all matrices are positive definite (PD).
is_pos_semi_def(X)	Check if all matrices are positive semi-definite (PSD).
is_sym_pos_def(X[, tol])	Check if all matrices are symmetric positive-definite (SPD).
is_sym_pos_semi_def(X)	Check if all matrices are symmetric positive semi-definite (SPSD).
is_herm_pos_def(X[, tol])	Check if all matrices are Hermitian positive-definite (HPD).
is_herm_pos_semi_def(X)	Check if all matrices are Hermitian positive semi-definite (HPSD).

Utility Functions

Visualization and miscellaneous helpers.

Visualization

plot_bihist(X, y[, n_bins, title])	Plot histogram of bi-class predictions.
plot_biscatter(X, y)	Plot scatter of bi-class predictions.
plot_cospectra(X, freqs, *[, ylabels, title])	Plot cospectral matrices.
plot_cov_ellipse(ax, X[, n_std])	Plot 2x2 covariance matrix as an ellipse.
plot_embedding(X[, y, embd_type, metric, ...])	Plot embedding of SPD matrices.
plot_waveforms(X, display, *[, times, ...])	Plot repetitions of a multichannel waveform.