pyriemann.datasets.sample_gaussian

pyriemann.datasets.sample_gaussian(n_matrices, mean, sigma, random_state=None, n_jobs=1, sampling_method='auto')

Sample a Riemannian Gaussian distribution.

Sample SPD or HPD matrices from a Riemannian Gaussian distribution centered at mean and with dispersion parametrized by sigma.

If mean has a complex dtype, Hermitian positive-definite (HPD) matrices are generated instead of symmetric positive-definite (SPD).

If sigma is a float, it samples from the distribution defined in [1] that generalizes the notion of a Gaussian distribution to the space of SPD/HPD matrices. This sampling is based on a spectral factorization of SPD/HPD matrices in terms of their eigenvectors (U-parameters) and the log of the eigenvalues (r-parameters).

If sigma is a covariance matrix, it samples from the wrapped Gaussian distribution defined in [2].

Parameters:

n_matricesint

Number of matrices to generate.

meanndarray, shape (n_dim, n_dim)

Center of the Riemannian Gaussian distribution. If complex, HPD matrices are generated; if real, SPD matrices are generated.

Changed in version 0.12.

sigmafloat | ndarray, shape (n_dim * (n_dim + 1) / 2, n_dim * (n_dim + 1) / 2)

If float, dispersion of the Riemannian Gaussian distribution [1]. If ndarray, covariance matrix of the wrapped Gaussian distribution [2].

Changed in version 0.11.

random_stateint | RandomState instance | None, default=None

Pass an int for reproducible output across multiple function calls.

n_jobsint, default=1

When sigma is a float, the number of jobs to use for the computation. This works by computing each sample in parallel. If -1 all CPUs are used.

sampling_method{“auto”, “slice”, “rejection”}, default=”auto”

When sigma is a float, method used to sample eigenvalues: “auto”, “slice” or “rejection”. If “auto”, sampling_method will be equal to “slice” for n_dim != 2 and equal to “rejection” for n_dim = 2.

Added in version 0.4.

Returns:

samplesndarray, shape (n_matrices, n_dim, n_dim)

Samples of the Riemannian Gaussian distribution.

Notes

Added in version 0.3.

Changed in version 0.11: Add support for sigma defined as a covariance matrix.

Changed in version 0.12: Rename sample_gaussian_spd into sample_gaussian. Add support for HPD matrices for float sigma.

References

[1] (1,2)

Riemannian Gaussian distributions on the space of symmetric positive definite matrices S. Said, L. Bombrun, Y. Berthoumieu, and J. Manton. IEEE Trans Inf Theory, vol. 63, pp. 2153-2170, 2017.

[2] (1,2)

Wrapped gaussian on the manifold of symmetric positive definite matrices T. de Surrel, F. Lotte, S. Chevallier, and F. Yger. International Conference on Machine Learning (ICML), July 2025, Vancouver, Canada.