spherical_kde package¶
Subpackages¶
Submodules¶
spherical_kde.distributions module¶
Module containing the kernel function for the spherical KDE.
For more detail, see: https://en.wikipedia.org/wiki/Von_Mises-Fisher_distribution
- spherical_kde.distributions.VonMisesFisher_distribution(phi, theta, phi0, theta0, sigma0)[source]¶
Von-Mises Fisher distribution function.
- Parameters
- phi, thetafloat or array_like
Spherical-polar coordinates to evaluate function at.
- phi0, theta0float or array-like
Spherical-polar coordinates of the center of the distribution.
- sigma0float
Width of the distribution.
- Returns
- float or array_like
log-probability of the vonmises fisher distribution.
Notes
- spherical_kde.distributions.VonMisesFisher_sample(phi0, theta0, sigma0, size=None)[source]¶
Draw a sample from the Von-Mises Fisher distribution.
- Parameters
- phi0, theta0float or array-like
Spherical-polar coordinates of the center of the distribution.
- sigma0float
Width of the distribution.
- sizeint, tuple, array-like
number of samples to draw.
- Returns
- phi, thetafloat or array_like
Spherical-polar coordinates of sample from distribution.
- spherical_kde.distributions.VonMises_mean(phi, theta)[source]¶
Von-Mises sample mean.
- Parameters
- phi, thetaarray-like
Spherical-polar coordinate samples to compute mean from.
- Returns
- float
- ..math::
sum_i^N x_i / || sum_i^N x_i ||
Notes
- spherical_kde.distributions.VonMises_std(phi, theta)[source]¶
Von-Mises sample standard deviation.
- Parameters
- phi, thetaarray-like
Spherical-polar coordinate samples to compute mean from.
- Returns
- solution for
..math:: 1/tanh(x) - 1/x = R,
where
..math:: R = || sum_i^N x_i || / N
Notes
- Wikipedia:
https://en.wikipedia.org/wiki/Von_Mises-Fisher_distribution#Estimation_of_parameters but re-parameterised for sigma rather than kappa.
spherical_kde.utils module¶
Utilities
General stable functions
Transforming coordinates
Computing rotations
Performing spherical integrals
- spherical_kde.utils.cartesian_from_polar(phi, theta)[source]¶
Embedded 3D unit vector from spherical polar coordinates.
- Parameters
- phi, thetafloat or numpy.array
azimuthal and polar angle in radians.
- Returns
- nhatnumpy.array
unit vector(s) in direction (phi, theta).
- spherical_kde.utils.decra_from_polar(phi, theta)[source]¶
Convert from ra and dec to spherical polar coordinates.
- Parameters
- phi, thetafloat or numpy.array
azimuthal and polar angle in radians
- Returns
- ra, decfloat or numpy.array
Right ascension and declination in degrees.
- spherical_kde.utils.logsinh(x)[source]¶
Compute log(sinh(x)), stably for large x.
- Parameters
- xfloat or numpy.array
argument to evaluate at, must be positive
- Returns
- float or numpy.array
log(sinh(x))
- spherical_kde.utils.polar_from_cartesian(x)[source]¶
Embedded 3D unit vector from spherical polar coordinates.
- Parameters
- xarray_like
cartesian coordinates
- Returns
- phi, thetafloat or numpy.array
azimuthal and polar angle in radians.
- spherical_kde.utils.polar_from_decra(ra, dec)[source]¶
Convert from spherical polar coordinates to ra and dec.
- Parameters
- ra, decfloat or numpy.array
Right ascension and declination in degrees.
- Returns
- phi, thetafloat or numpy.array
Spherical polar coordinates in radians
- spherical_kde.utils.rotation_matrix(a, b)[source]¶
The rotation matrix that takes a onto b.
- Parameters
- a, bnumpy.array
Three dimensional vectors defining the rotation matrix
- Returns
- Mnumpy.array
Three by three rotation matrix
Notes
- spherical_kde.utils.spherical_integrate(f, log=False)[source]¶
Integrate an area density function over the sphere.
- Parameters
- fcallable
function to integrate (phi, theta) -> float
- logbool
Should the function be exponentiated?
- Returns
- float
Spherical area integral
\[\int_0^{2\pi}d\phi\int_0^\pi d\theta f(\phi, \theta) \sin(\theta)\]
- spherical_kde.utils.spherical_kullback_liebler(logp, logq)[source]¶
Compute the spherical Kullback-Liebler divergence.
- Parameters
- logp, logqcallable
log-probability distributions (phi, theta) -> float
- Returns
- float
Kullback-Liebler divergence
\[\int P(x)\log \frac{P(x)}{Q(x)} dx\]
Notes
- Wikipedia post:
Module contents¶
The spherical kernel density estimator class.
- class spherical_kde.SphericalKDE(phi_samples, theta_samples, weights=None, bandwidth=None, density=100)[source]¶
Bases:
object
Spherical kernel density estimator
- Parameters
- phi_samples, theta_samplesarray_like
spherical-polar samples to construct the kde
- weightsarray_like
Sample weighting default [1] * len(phi_samples))
- bandwidthfloat
bandwidth of the KDE. Increasing bandwidth increases smoothness
- densityint
number of grid points in theta and phi to draw contours.
- Attributes
- phi, thetanumpy.array
spherical polar samples
- weightsnumpy.array
Sample weighting (normalised to sum to 1).
- bandwidthfloat
Bandwidth of the kde. defaults to rule-of-thumb estimator https://en.wikipedia.org/wiki/Kernel_density_estimation Set to None to use this value
- densityint
number of grid points in theta and phi to draw contours.
- palefactorfloat
getdist-style colouration factor of sigma-contours.
Methods
__call__
(phi, theta)Log-probability density estimate
plot
(ax[, colour])Plot the KDE on an axis.
plot_samples
(ax[, nsamples])Plot equally weighted samples on an axis.
- property bandwidth¶
- plot(ax, colour='g', **kwargs)[source]¶
Plot the KDE on an axis.
- Parameters
- axmatplotlib.axes.Axes
matplotlib axis to plot on. This must be constructed with a cartopy.crs.projection:
>>> import cartopy >>> import matplotlib.pyplot as plt >>> fig = plt.subplots() >>> ax = fig.add_subplot(111, projection=cartopy.crs.Mollweide())
- color
Colour to plot the contours. arg can be an RGB or RGBA sequence or a string in any of several forms:
a letter from the set ‘rgbcmykw’
a hex color string, like ‘#00FFFF’
a standard name, like ‘aqua’
a string representation of a float, like ‘0.4’,
This is passed into matplotlib.colors.colorConverter.to_rgb
- plot_samples(ax, nsamples=None, **kwargs)[source]¶
Plot equally weighted samples on an axis.
- Parameters
- axmatplotlib.axes.Axes
matplotlib axis to plot on. This must be constructed with a cartopy.crs.projection:
>>> import cartopy >>> import matplotlib.pyplot as plt >>> fig = plt.subplots() >>> ax = fig.add_subplot(111, projection=cartopy.crs.Mollweide())
- nsamplesint
Approximate number of samples to plot. Can only thin down to this number, not bulk up