This python package implements two novel tuning-free MCMC algorithms, an ideal geodesic slice sampler based on accept/reject strategy and a shrinkage-based geodesic slice sampler to sample from spherical distributions on arbitrary dimensions. The package also includes the implementation of random-walk Metropolis-Hastings (RWMH) and Hamiltonian Monte Carlo (HMC) whose step-size parameter is automatically tuned. As shown in our paper, our algorithms have outperformed RWMH and HMC for spherical distributions.
This demo quickly illustrates that. We consider a target that is a mixture of von Mises-Fisher distribution on a 2-sphere with concentration parameter
GeoSSS is available for installation from PyPI. Therefore, simply type:
pip install geosss
To install dependencies required to run scripts under scripts/
,
pip install geosss[extras]
If you want to install with the latest changes including all the dependencies,
pip install geosss[extras]@git+https://github.com/microscopic-image-analysis/geosss.git@main
A minimal example to get started as well as reproduce the above demo:
import geosss as gs
import numpy as np
# parameters for mixture of von Mises-Fisher (vMF)
# distributions
d = 3 # required dimension
K = 3 # number of mixture components
kappa = 80.0 # concentration parameter
# mus (mean directions) of the vMF mixture components
mus = np.array([[0.86981638, -0.37077248, 0.32549536],
[-0.19772391, -0.89279985, -0.40473902],
[0.19047726, 0.22240888, -0.95616562]])
# target pdf
vmfs = [gs.VonMisesFisher(kappa*mu) for mu in mus]
pdf = gs.MixtureModel(vmfs)
# sampler parameters
n_samples = int(1e3) # no. of samples
burnin = int(0.1 * n_samples) # burnin samples
seed = 3521 # sampler seed
# initial state of the samplers
init_state = np.array([-0.86333052, 0.18685286, -0.46877117])
# sampling with the four samplers
samples = {}
# geoSSS (reject): ideal geodesic slice sampler
rsss = gs.RejectionSphericalSliceSampler(pdf, init_state, seed)
samples['sss-reject'] = rsss.sample(n_samples, burnin)
# geoSSS (shrink): shrinkage-based geodesic slice sampler
ssss = gs.ShrinkageSphericalSliceSampler(pdf, init_state, seed)
samples['sss-shrink'] = ssss.sample(n_samples, burnin)
# RWMH: random-walk Metropolis Hastings
rwmh = gs.MetropolisHastings(pdf, init_state, seed)
samples['rwmh'] = rwmh.sample(n_samples, burnin)
# HMC: Hamiltonian Monte Carlo
hmc = gs.SphericalHMC(pdf, init_state, seed)
samples['hmc'] = hmc.sample(n_samples, burnin)
# visualize samples in 3d
gs.compare_samplers_3d(pdf, samples)
The plots in the paper under numerical illustrations section were generated using bingham.py
, mixture_vMF.py
, ess_vMF.py
and curve.py
.
To install this package and its development dependencies in editable mode, please do the following
git clone https://github.com/microscopic-image-analysis/geosss.git
cd geosss
pip install -e .[dev]
If you use this package or ideas from the paper, please consider citing us.
@misc{habeck2023,
title={Geodesic slice sampling on the sphere},
author={Michael Habeck and Mareike Hasenpflug and Shantanu Kodgirwar and Daniel Rudolf},
year={2023},
eprint={2301.08056},
archivePrefix={arXiv},
primaryClass={stat.ME}
}