geometric_kernels.feature_maps.probability_densities

This module provide the routines for sampling from the Gaussian and Student-t probability densities in a backend-agnostic way. It also provides the routines for sampling the non-standard probability densities that arise in relation to the Hyperbolic and SymmetricPositiveDefiniteMatrices spaces.

Module Contents

geometric_kernels.feature_maps.probability_densities.base_density_sample(key, size, params, dim, rho, shifted_laplacian=True)

The Matérn kernel’s spectral density is \(p_{\nu,\kappa}(\lambda)\), where \(\nu\) is the smoothness parameter, \(\kappa\) is the length scale and \(p_{\nu,\kappa}\) is the Student’s t or Gaussian density, depending on the smoothness.

We call it “base density” and this function returns a sample from it.

Parameters:

• key (lab.RandomState) – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).

• size (beartype.typing.Tuple[int, Ellipsis]) – The returned array samples will have the shape (*size, dim).

• params (beartype.typing.Dict[str, lab.Numeric]) – Params of the kernel.

• dim (int) – Dimensionality of the space the kernel is defined on.

• rho (lab.Numeric) – \(\rho\) vector of the space.

• shifted_laplacian (bool) –

  If True, assumes that the kernels are defined in terms of the shifted Laplacian. This often makes Matérn kernels more flexible by widening the effective range of the length scale parameter.

  Defaults to True.

Returns:

Tuple(key, samples) where samples is a (*size, dim)-shaped array of samples, and key is the updated random key for jax, or the similar random state (generator) for any other backend.

Return type:

beartype.typing.Tuple[lab.RandomState, lab.Numeric]

geometric_kernels.feature_maps.probability_densities.hyperbolic_density_sample(key, size, params, dim, shifted_laplacian=True)

This function samples from the full (i.e., including the \(c(\lambda)^{-2}\) factor, where \(c\) is the Harish-Chandra’s \(c\)-function) spectral density of the heat/Matérn kernel on the hyperbolic space, using rejection sampling.

Parameters:

• key (lab.RandomState) – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).

• size (beartype.typing.Tuple[int, Ellipsis]) – Shape of the returned sample.

• params (beartype.typing.Dict[str, lab.Numeric]) – Params of the kernel.

• dim (int) – Dimensionality of the space the kernel is defined on.

• shifted_laplacian (bool) –

  If True, assumes that the kernels are defined in terms of the shifted Laplacian. This often makes Matérn kernels more flexible by widening the effective range of the length scale parameter.

  Defaults to True.

Returns:

Tuple(key, samples) where samples is a size-shaped array of samples, and key is the updated random key for jax, or the similar random state (generator) for any other backend.

Return type:

beartype.typing.Tuple[lab.RandomState, lab.Numeric]

geometric_kernels.feature_maps.probability_densities.spd_density_sample(key, size, params, degree, rho, shifted_laplacian=True)

This function samples from the full (i.e., including the \(c(\lambda)^{-2}\) factor, where \(c\) is the Harish-Chandra’s \(c\)-function) spectral density of the heat/Matérn kernel on the manifold of symmetric positive definite matrices, using rejection sampling.

Parameters:

• key (lab.RandomState) – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).

• size (beartype.typing.Tuple[int, Ellipsis]) – The returned array samples will have the shape (*size, D).

• params (beartype.typing.Dict[str, lab.Numeric]) – Params of the kernel.

• dim – Dimensionality of the space the kernel is defined on.

• degree (int) – The degree D of the SPD(D) space.

• rho (lab.Numeric) – \(\rho\) vector of the space, D-dimensional.

• shifted_laplacian (bool) –

  If True, assumes that the kernels are defined in terms of the shifted Laplacian. This often makes Matérn kernels more flexible by widening the effective range of the length scale parameter.

  Defaults to True.

Returns:

Tuple(key, samples) where samples is a (*size, D)-shaped array of samples, and key is the updated random key for jax, or the similar random state (generator) for any other backend.

Return type:

beartype.typing.Tuple[lab.RandomState, lab.Numeric]

geometric_kernels.feature_maps.probability_densities.student_t_sample(key, loc, shape, df, size, dtype=None)

Sample from the multivariate Student’s t-distribution with mean vector loc, shape matrix shape and df degrees of freedom, using key random state, and returning sample of shape size.

A multivariate Student’s t random vector \(T\) with \(\nu\) degrees of freedom, a mean vector \(\mu\) and a shape matrix \(\Sigma\) can be represented as

\[T = \frac{Z}{\sqrt{V/\nu}} + \mu,\]

where \(Z \sim N(0, \Sigma)\) and \(V \sim \chi^2(\nu)\). The \(\chi^2(\nu)\) distribution, in its turn, is the same as \(\Gamma(\nu / 2, 2)\) distribution, and therefore \(V/\nu \sim \Gamma(\nu / 2, 2 / \nu)\). We use these properties to sample a multivariate Student’s t random vector by sampling a Gaussian random vector and a Gamma random variable.

Warning

The shape parameter has little to do with tensor shapes, it is similar to the covariance matrix in the Gaussian distribution.

Parameters:

• key (lab.RandomState) – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).

• loc (lab.Numeric) – Mean vector of the multivariate Student’s t-distribution. An array of shape (n,).

• shape (lab.Numeric) – Shape matrix of the multivariate Student’s t-distribution. An array of shape (n, n).

• size (beartype.typing.Tuple[int, Ellipsis]) – The returned array samples will have the shape (*size, n).

• df (lab.Numeric) – The number of degrees of freedom of the Student-t distribution, represented as a (1,)-array of the used backend.

• dtype (beartype.typing.Optional[lab.DType]) – dtype of the returned tensor.

Returns:

Tuple(key, samples) where samples is a (*size, n)-shaped array of samples of type dtype, and key is the updated random key for jax, or the similar random state (generator) for any other backend.

Return type:

beartype.typing.Tuple[lab.RandomState, lab.Numeric]