{"id":37673556,"url":"https://github.com/microscopic-image-analysis/geosss","last_synced_at":"2026-01-16T12:09:12.117Z","repository":{"id":183500945,"uuid":"666479128","full_name":"microscopic-image-analysis/geosss","owner":"microscopic-image-analysis","description":"Implementation of the geodesic slice sampling on the sphere","archived":false,"fork":false,"pushed_at":"2025-12-03T13:34:21.000Z","size":18952,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-06T14:48:46.544Z","etag":null,"topics":["bayesian-inference","bioinformatics","directional-statistics","mcmc","shape-analysis"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microscopic-image-analysis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-14T16:11:53.000Z","updated_at":"2025-12-03T13:34:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"fd0d7d2f-57bc-4009-a896-2fee1244332f","html_url":"https://github.com/microscopic-image-analysis/geosss","commit_stats":null,"previous_names":["microscopic-image-analysis/geosss"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/microscopic-image-analysis/geosss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microscopic-image-analysis%2Fgeosss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microscopic-image-analysis%2Fgeosss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microscopic-image-analysis%2Fgeosss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microscopic-image-analysis%2Fgeosss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microscopic-image-analysis","download_url":"https://codeload.github.com/microscopic-image-analysis/geosss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microscopic-image-analysis%2Fgeosss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bayesian-inference","bioinformatics","directional-statistics","mcmc","shape-analysis"],"created_at":"2026-01-16T12:09:12.017Z","updated_at":"2026-01-16T12:09:12.082Z","avatar_url":"https://github.com/microscopic-image-analysis.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\r\n\u003cimg src=\"https://raw.githubusercontent.com/microscopic-image-analysis/geosss/927ff8c8187b88a1a72725c4e450ae0f0523431b/assets/logo.svg\" width=\"300\"\u003e\r\n\u003c/p\u003e\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n  [![PyPI](https://img.shields.io/pypi/v/geosss)](https://pypi.org/project/geosss/)\r\n  ![Python 3.9+](https://img.shields.io/badge/python-3.9+-green.svg)\r\n  [![License](https://img.shields.io/badge/License-BSD_3--Clause-purple.svg)](https://opensource.org/licenses/BSD-3-Clause)\r\n\r\n\u003c/div\u003e\r\n\r\n# GeoSSS: Geodesic Slice Sampling on the Sphere\r\n\r\nThis python package implements the novel and efficient tuning-free MCMC based inference methods to sample distributions defined on the sphere as published in JMLR. This includes the two variants GeoSSS (reject) and GeoSSS (shrink), where the latter is much faster and therefore recommended for practical utility.\r\n\r\nIn addition, the package also provides the implementation of the spherical variants of random-walk Metropolis-Hastings (RWMH) [Lie et al. 2023] and state-of-the-art Hamiltonian Monte Carlo [Lan et al. 2014]. As demonstrated in our [paper](https://doi.org/10.48550/arXiv.2301.08056), the proposed GeoSSS samplers outperform these baseline samplers for several challenging target distributions. \r\n\r\nTo reproduce the results in the paper, see this [section](#development-and-reproducibility). However, to get started quickly, install the package and follow along with the demo provided below. \r\n\r\n\r\n## Installation\r\n\r\nGeoSSS is available for installation from [PyPI](https://pypi.org/project/geosss/). Therefore, simply type:\r\n\r\n```bash\r\npip install geosss\r\n```\r\n\r\n## Minimal Example\r\n\r\nAs a demo, we consider a target that is a mixture of von Mises-Fisher distributions on $\\mathbb{S}^2$ with concentration parameter $\\kappa=$ 80. By considering a fixed computational budget of 1000 samples, our samplers manage to explore all modes, whereas RWMH and HMC get stuck in a single mode. \r\n\r\n\u003cp align=\"center\"\u003e\r\n\u003cimg src=\"https://github.com/microscopic-image-analysis/geosss/blob/1ed528f2b708cfc8b88bd78bd8f210e6a0d6372a/assets/animation_vMF.gif\" width=\"1000\"\u003e\r\n\u003c/p\u003e\r\n\r\nThis demo can be created with the below script.\r\n```python\r\nimport geosss as gs\r\nimport numpy as np\r\n\r\n# Create mixture of von Mises-Fisher distributions\r\nmus = np.array([[0.87, -0.37, 0.33],\r\n                [-0.20, -0.89, -0.40],\r\n                [0.19, 0.22, -0.96]])\r\nvmfs = [gs.VonMisesFisher(80.0 * mu) for mu in mus]\r\npdf = gs.MixtureModel(vmfs)\r\n\r\n# Sampling parameters\r\nn_samples, burnin = 1000, 100\r\ninit_state = np.array([-0.86, 0.19, -0.47])\r\nseed = 3521\r\n\r\n# Sample with different methods\r\nsamplers = {\r\n    'sss-reject': gs.RejectionSphericalSliceSampler, # very accurate, but slow\r\n    'sss-shrink': gs.ShrinkageSphericalSliceSampler, # reasonably accurate, but fast\r\n    'rwmh': gs.MetropolisHastings,                   # automatically tuned during burnin          \r\n    'hmc': gs.SphericalHMC,                          # automatically tuned during burnin\r\n}\r\n\r\nsamples = {name: cls(pdf, init_state, seed).sample(n_samples, burnin) \r\n           for name, cls in samplers.items()}\r\n```\r\nSee the notebook [`demo.ipynb`](demo.ipynb) for visualization of the samples.\r\n\r\n## Development and Reproducibility\r\n\r\nTo reproduce results from the numerical illustrations section of the paper, check the [scripts](scripts/) directory. Precomputed results can also be downloaded from the [Science Data Bank](https://doi.org/10.57760/sciencedb.30181) and used with these scripts.\r\n\r\nHowever, first installing the package and it's *locked* dependencies is necessary and can be done as follows:\r\n\r\n1. Clone the repository and navigate to the root of the folder,\r\n\r\n```bash\r\ngit clone https://github.com/microscopic-image-analysis/geosss.git\r\ncd geosss\r\ngit checkout v0.3.5 # version (for JMLR paper reprod.)\r\n```\r\n\r\n2. You can now create a virtual environment (with `conda` for example),\r\n\r\n```bash\r\nconda create --name geosss-venv python=3.12 # or python \u003e= 3.10, \u003c 3.13\r\nconda activate geosss-venv\r\n```\r\n\r\n3. The dependencies can now be installed in this environment as,\r\n```bash\r\npip install -r requirements.txt\r\npip install -e . --no-deps\r\n```\r\n## References\r\n\r\n[Lie et al. 2023](https://doi.org/10.48550/arXiv.2112.12185): Lie, H. C., Rudolf, D., Sprungk, B., and Sullivan, T. J. (2023). “Dimension-independent Markov\r\nchain Monte Carlo on the sphere”. *Scandinavian Journal of Statistics* 5:4, pp. 1818–1858.\r\n\r\n[Lan et al. 2014](https://doi.org/10.48550/arXiv.1309.4289): Lan, S., Zhou, B., and Shahbaba, B. (2014). “Spherical Hamiltonian Monte Carlo for constrained\r\ntarget distributions”. In: *Proceedings of the 31st International Conference on Machine Learning.* Vol. 32.\r\nPMLR, pp. 629–637.\r\n\r\n\r\n\r\n## Citation\r\n\r\nIf you use this package or ideas from the paper, please consider citing us.\r\n```bash\r\n@misc{habeck2023,\r\n      title={Geodesic slice sampling on the sphere}, \r\n      author={Michael Habeck and Mareike Hasenpflug and Shantanu Kodgirwar and Daniel Rudolf},\r\n      year={2023},\r\n      eprint={2301.08056},\r\n      archivePrefix={arXiv},\r\n      primaryClass={stat.ME}\r\n}\r\n```\r\n\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicroscopic-image-analysis%2Fgeosss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicroscopic-image-analysis%2Fgeosss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicroscopic-image-analysis%2Fgeosss/lists"}