API reference

class spherical_stats.ACG(cov_matrix=None)

Bases: object

Angular Central Gaussian distribution

Parameters

cov_matrix (optional, ndarray (3, 3)) – Covariance matrix of the ACG distribution

The angular central gaussian distribution is an elliptically symmetrical distribution for axial data. Its PDF is defined as

\[p_{ACG}(\pm\mathbf{x}|\mathbf{\Lambda}) = \frac{1}{4\pi\sqrt{|\Lambda|}}(\mathbf{x}\Lambda^{-1}\mathbf{x})^{-\frac{3}{2}}\]

with covariance matrix \(\Lambda\) and its determinant \(|\Lambda|\) . \(\Lambda\) must be positive definite.

Notes

Reference: Tyler, Statistical analysis for the angular central Gaussian distribution on the sphere Biometrika (1987), 74, 3, pp. 579-89

fit(vectors, tol=0.0001)

Fits the Angular Central Gaussian Distribution to data

Parameters

  • vectors (ndarray (n, 3)) – Vector data the distribution is fitted to

  • tol (float, optional, default 1e-4) – Convergence tolerance of the fix point algorithm. Tolerance is measured as the difference between the Frobenius norms of the estimated covariance matrix between two iterations.

pdf(x)

Calculate probability density function of a set of vectors x given a parameterized Angular Central Gaussian distribution

Parameters

x (ndarray (size, 3)) – Vectors to evaluate the PDF at

Returns

pdfvals – PDF values as ndarray of shape (size,)

Return type

ndarray (size,)

rvs(size=1)

Generate samples from the Angular central gaussian distribution

Parameters

size (int, optional, default 1) – Number of samples

Returns

samples – samples as ndarray of shape (size, 3)

Return type

ndarray (size, 3)

class spherical_stats.ESAG(params=None)

Bases: object

Elliptically symmetrical angular Central Gaussian distribution

Parameters

params (optional, ndarray (5, )) – Parameters of the distribution

params are the following: \((\mu_0, \mu_1, \mu_2, \gamma_1, \gamma_2)\).

The principal orientation vectors is given by the normalized vector \(\boldsymbol{\mu}=[\mu_0, \mu_1, \mu_2]^T/||[\mu_0, \mu_1, \mu_2]^T||\) and the shape of the distribution is controlled by the parameters \(\gamma_1\) and \(\gamma_2\).

Notes

The formula of the ESAG PDF is quite complicated, developers are referred to the reference below.

Note that unlike the original Matlab implementation the distribution is fitted using the L-BFGS-B algorithm based on a finite difference approximation of the gradient. So far, this has proven to work succesfully.

Reference: Paine et al. An elliptically symmetric angular Gaussian distribution, Statistics and Computing volume 28, 689–697 (2018)

fit(vectors, verbose=False)

Fits the elliptically symmetrical angular Central Gaussian distribution to data

Parameters

  • vectors (ndarray (n, 3)) – Vector data the distribution is fitted to

  • verbose (bool, optional, default False) – Print additional information about the fit

pdf(vectors)

Calculate probability density function of a set of vectors x given a parameterized elliptically symmetric angular Central Gaussian distribution

Parameters

x (ndarray (size, 3)) – Vectors to evaluate the PDF at

Returns

pdfvals – PDF values as ndarray of shape (size,)

Return type

ndarray (size,)

rvs(size=1)

Generate samples from the elliptically symmetric angular central gaussian distribution

Parameters

size (int, optional, default 1) – Number of samples

Returns

samples – samples as ndarray of shape (size, 3)

Return type

ndarray (size, 3)

class spherical_stats.VMF(mu=None, kappa=None)

Bases: object

Von Mises-Fisher distribution

Parameters

  • mu (optional, ndarray (3, )) – Mean orientation

  • kappa (optional, float) – positive concentration parameter

The VMF distribution is an isotropic distribution for directional data. Its PDF is typically defined as

\[p_{vMF}(\mathbf{x}| \boldsymbol{\mu}, \kappa) = \frac{\kappa}{4\pi\cdot\text{sinh}(\kappa)}\exp(\kappa \boldsymbol{\mu}^T\mathbf{x})\]

Here, the numerically stable variant from (Wenzel, 2012) is used:

\[p_{vMF}(\mathbf{x}| \boldsymbol{\mu}, \kappa) = \frac{\kappa}{2\pi(1-\exp(-2\kappa))}\exp(\kappa( \boldsymbol{\mu}^T \mathbf{x}-1))\]

References:

Mardia, Jupp. Directional Statistics, 1999.

Wenzel. Numerically stable sampling of the von Mises Fisher distribution on S2. 2012

angle_within_probability_mass(alpha, deg=False)

Calculates the angle which contains probability mass alpha of the VMF density around the mean angle

Reference: Fayat, 2021. Conversion of the von Mises-Fisher concentration parameter to an equivalent angle.

https://github.com/rfayat/SphereProba/blob/main/ressources/vmf_integration.pdf

Parameters

  • alpha (float) – Probability mass. Must be \(0<\alpha<1\)

  • deg (optional, default False) – If True, converts the result into degrees

Returns

angle – Resulting angle

Return type

float

fit(data)

Fits the VMF distribution to data

Parameters

data (ndarray (n, 3)) – Vector data the distribution is fitted to

pdf(x)

Calculate probability density function of a set of vectors x given a parameterized VMF distribution

Parameters

x (ndarray (size, 3)) – Vectors to evaluate the PDF at

Returns

pdfvals – PDF values as ndarray of shape (size,)

Return type

ndarray (size,)

rvs(size=1)

Generate samples from the VMF distribution

Parameters

size (int, optional, default 1) – Number of samples

Returns

samples – samples as ndarray of shape (size, 3)

Return type

ndarray (size, 3)

class spherical_stats.Watson(mu=None, kappa=None)

Bases: object

Watson distribution

Note

The Watson distribution is only implemented for positive concentration parameter \(\kappa\).

Parameters

  • mu (optional, ndarray (3, )) – Mean axis

  • kappa (optional, float) – positive concentration parameter

The Watson distribution is an isotropic distribution for axial data. Its PDF is defined as

\[\begin{split}p_{Watson}(\pm\mathbf{x}| \boldsymbol{\mu}, \kappa) & = M\left(\frac{1}{2},\frac{3}{2},\kappa\right)\exp(\kappa (\boldsymbol{\mu}^T\mathbf{x})^2) \\ & = \frac{\sqrt{\pi}\mathrm{erfi}(\sqrt{\kappa})}{2\sqrt{\kappa}}\exp(\kappa (\boldsymbol{\mu}^T\mathbf{x})^2)\end{split}\]

where \(M\) denotes Kummer’s confluent hypergeometric function and \(\mathrm{erfi}\) the imaginary error function .

References:

Mardia, Jupp. Directional Statistics, 1999.

Chen. Generate Random Samples from von Mises-Fisher and Watson Distributions. 2012

fit(data)

Fits the Watson distribution to data

Parameters

data (ndarray (n, 3)) – Vector data the distribution is fitted to

pdf(x)

Calculate probability density function of a set of vectors x given a parameterized Watson distribution

Parameters

x (ndarray (size, 3)) – Vectors to evaluate the PDF at

Returns

pdfvals – PDF values as ndarray of shape (size, )

Return type

ndarray (size,)

rvs(size=1)

Generate samples from the Watson distribution

Parameters

size (int, optional, default 1) – Number of samples

Returns

samples – samples as ndarray of shape (size, 3)

Return type

ndarray (size, 3)

spherical_stats.evaluate_on_sphere(func, n_grid=30, equalize_areas=True)

Evaluate a function over a sphere

Parameters

  • func (callable) – Must be of the form ndarray (n, 3)-> (n, )

  • n_grid (int, optional, default 30) – Number of grid points for the sphere for both longitude and lattitude

  • equalize_areas (bool, optional, default True) – If True, enforces that surface patches are of same area

Returns

f

Return type

ndarray (n, )

spherical_stats.geographical_to_vectors(latitude, longitude, deg=False)

Transform a set of geographical coordinates to vectors

Parameters

  • latitude (ndarray (n, )) – Polar angle

  • longitude (ndarray (n, )) – Azimuthal angle

  • deg (bool, optional, default False) – If True, assumes that input is in degrees. If False, assumes that input is in radian.

Returns

vectors – Vector data

Return type

ndarray (n, 3)

spherical_stats.load_northpole()

Load example data for finding the historical position of the north pole

Reference: Paine et al. An elliptically symmetric angular Gaussian distribution, Statistics and Computing volume 28, 689–697 (2018)

Returns

data

Return type

ndarray (33, 3)

spherical_stats.orientation_matrix(vectors)

Calculates the orientation matrix of a set of vectors

Parameters

vectors (ndarray (n ,3)) – sample of n vectors

Returns

orientation_matrix

Return type

ndarray (3, 3)

spherical_stats.polar_to_vectors(theta, phi, deg=False)

Transform a set of polar coordinates to vectors

Parameters

  • theta (ndarray (n, )) – Polar angle

  • phi (ndarray (n, )) – Azimuthal angle

  • deg (bool, optional, default False) – If True, assumes that input is in degrees. If False, assumes that input is in radian.

Returns

vectors – Vector data

Return type

ndarray (n, 3)

spherical_stats.sphere(n_grid=30, equalize_areas=True)

Create vectors to conveniently plot a sphere

Parameters

  • n_grid (int, optional, default 30) – Number of grid points for the sphere for both longitude and lattitude

  • equalize_areas (bool, optional, default True) – If True, enforces that surface patches are of same area

Returns

  • x (ndarray)

  • y (ndarray)

  • z (ndarray)

spherical_stats.spherical_hist(vectors, n_grid=100)

Basic spherical histogram

Parameters

  • vectors (ndarray (n, 3)) – Vectors to calculate histogram of

  • n_grid (int, optional, default 100) – number of grid points for the sphere for both longitude and lattitude

Returns

  • hist (ndarray)

  • x (ndarray)

  • y (ndarray)

  • z (ndarray)

spherical_stats.spherical_mean(vectors)

Calculates the spherical mean of a set of vectors

Parameters

vectors (ndarray (n, 3)) – Input vectors to calculate spherical mean of

Returns

mean

Return type

ndarray (3, )

spherical_stats.spherical_variance(vectors)

Calculates the spherical variance of a set of vectors

Parameters

vectors (ndarray (n, 3)) – Input vectors to calculate spherical variance of

Returns

var

Return type

float

spherical_stats.sphericalrand(size=1)

Generate uniform random samples on a sphere

Parameters

size (int, optional, default 1) – Number of samples

Returns

samples

Return type

ndarray (size, 3)

spherical_stats.vectors_to_geographical(vectors, deg=False)

Transform a set of vectors to geographical coordinates

Parameters

  • vectors (ndarray (n, 3)) – Vector data

  • deg (bool, optional, default False) – If True, returns output geographical angles in degrees. If False, returns angles in radian.

Returns

  • latitude (ndarray (n, )) – Geographical latitude

  • longitude (ndarray (n, )) – Geographical longitude

spherical_stats.vectors_to_polar(vectors, deg=False)

Transform a set of vectors to polar coordinates

Parameters

  • vectors (ndarray (n, 3)) – Vector data

  • deg (bool, optional, default False) – If True, returns output polar angles in degrees. If False, returns angles in radian.

Returns

  • theta (ndarray (size, )) – Polar angle

  • phi (ndarray (size, )) – Azimuthal angle