<div style="position: relative; width: 100%;">
<img src="docs/images/mainlogo.png" style="width: 250px;">
<a href="https://ccbs.carney.brown.edu/brainstorm" style="position: absolute; right: 0; top: 50%; transform: translateY(-50%);">
<img src="docs/images/Brain-Bolt-%2B-Circuits.gif" style="width: 100px;">
</a>
</div>
## HSSM - Hierarchical Sequential Sampling Modeling
[](https://github.com/astral-sh/ruff)
### Overview
HSSM is a Python toolbox that provides a seamless combination of
state-of-the-art likelihood approximation methods with the wider ecosystem of
probabilistic programming languages. It facilitates flexible hierarchical model
building and inference via modern MCMC samplers. HSSM is user-friendly and
provides the ability to rigorously estimate the impact of neural and other
trial-by-trial covariates through parameter-wise mixed-effects models for a
large variety of cognitive process models. HSSM is a
<a href="https://ccbs.carney.brown.edu/brainstorm">BRAINSTORM</a> project in
collaboration with the Center for Computation and Visualization and the Center
for Computational Brain Science within the Carney Institute at Brown University.
- Allows approximate hierarchical Bayesian inference via various likelihood
approximators.
- Estimate impact of neural and other trial-by-trial covariates via native
hierarchical mixed-regression support.
- Extensible for users to add novel models with corresponding likelihoods.
- Built on PyMC with support from the Python Bayesian ecosystem at large.
- Incorporates Bambi's intuitive `lmer`-like regression parameter specification
for within- and between-subject effects.
- Native ArviZ support for plotting and other convenience functions to aid the
Bayesian workflow.
- Utilizes the ONNX format for translation of differentiable likelihood
approximators across backends.
### [Official documentation](https://lnccbrown.github.io/HSSM/).
## Cite HSSM
Fengler, A., Xu, Y., Bera, K., Omar, A., Frank, M.J. (in preparation). HSSM: A
generalized toolbox for hierarchical bayesian estimation of computational models
in cognitive neuroscience.
## Example
Here is a simple example of how to use HSSM:
```python
import hssm
# Load a package-supplied dataset
cav_data = hssm.load_data("cavanagh_theta")
# Define a basic hierarchical model with trial-level covariates
model = hssm.HSSM(
model="ddm",
data=cav_data,
include=[
{
"name": "v",
"prior": {
"Intercept": {"name": "Normal", "mu": 0.0, "sigma": 0.1},
"theta": {"name": "Normal", "mu": 0.0, "sigma": 0.1},
},
"formula": "v ~ theta + (1|participant_id)",
"link": "identity",
},
],
)
# Sample from the posterior for this model
model.sample()
```
To quickly get started with HSSM, please follow
[this tutorial](https://lnccbrown.github.io/HSSM/getting_started/getting_started/).
For a deeper dive into HSSM, please follow
[our main tutorial](https://lnccbrown.github.io/HSSM/tutorials/main_tutorial/).
## Installation
HSSM can be directly installed into your conda environment on Linux and MacOS.
Installing HSSM on windows takes only one more simple step. We have a more
detailed
[installation guide](https://lnccbrown.github.io/HSSM/getting_started/installation/)
for users with more specific setups.
### Install HSSM on Linux and MacOS (CPU only)
Use the following command to install HSSM into your virtual environment:
```bash
conda install -c conda-forge hssm
```
### Install HSSM on Linux and MacOS (with GPU Support)
If you need to sample with GPU, please install JAX with GPU support before
installing HSSM:
```bash
conda install jaxlib=*=*cuda* jax cuda-nvcc -c conda-forge -c nvidia
conda install -c conda-forge hssm
```
### Install HSSM on Windows (CPU only)
Because dependencies such as `jaxlib` and `numpyro` are not up-to-date on Conda,
the easiest way to install HSSM on Windows is to install PyMC first and install
HSSM via `pip`:
```bash
conda install -c conda-forge pymc
pip install hssm
```
### Install HSSM on Windows (with GPU support)
You simply need to install JAX with GPU support after installing PyMC:
```bash
conda install -c conda-forge pymc
pip install hssm[cuda12]
```
### Support for Apple Silicon, AMD, and other GPUs
JAX also has support other GPUs. Please follow the
[Official JAX installation guide](https://jax.readthedocs.io/en/latest/installation.html)
to install the correct version of JAX before installing HSSM.
## Advanced Installation
### Install HSSM directly with Pip
HSSM is also available through PyPI. You can directly install it with pip into
any virtual environment via:
```bash
pip install hssm
```
**Note:** While this installation is much simpler, you might encounter this
warning message
`WARNING (pytensor.tensor.blas): Using NumPy C-API based implementation for BLAS functions.`
Please refer to our
[advanced installation guide](https://lnccbrown.github.io/HSSM/getting_started/installation/)
for more details.
### Install the dev version of HSSM
You can install the dev version of `hssm` directly from this repo:
```bash
pip install git+https://github.com/lnccbrown/HSSM.git
```
### Install HSSM on Google Colab
Google Colab comes with PyMC and JAX pre-configured. That holds true even if you
are using the GPU and TPU backend, so you simply need to install HSSM via pip on
Colab regardless of the backend you are using:
```bash
!pip install hssm
```
## Troubleshooting
**Note:** Possible solutions to any issues with installations with hssm can be
located [here](https://github.com/lnccbrown/HSSM/discussions). Also feel free to
start a new discussion thread if you don't find answers there. We recommend
installing HSSM into a new conda environment with Python 3.10 or 3.11 to prevent
any problems with dependencies during the installation process. Please note that
hssm is only tested for python 3.10, 3.11. As of HSSM v0.2.0, support for Python
3.9 is dropped. Use unsupported python versions with caution.
## License
HSSM is licensed under
[Copyright 2023, Brown University, Providence, RI](LICENSE)
## Support
For questions, please feel free to
[open a discussion](https://github.com/lnccbrown/HSSM/discussions).
For bug reports and feature requests, please feel free to
[open an issue](https://github.com/lnccbrown/HSSM/issues) using the
corresponding template.
## Contribution
If you want to contribute to this project, please follow our
[contribution guidelines](docs/CONTRIBUTING.md).
## Acknowledgements
We would like to extend our gratitude to the following individuals for their
valuable contributions to the development of the HSSM package:
- [Bambi](https://github.com/bambinos/bambi) - A special thanks to the Bambi
project for providing inspiration, guidance, and support throughout the
development process. [Tomás Capretto](https://github.com/tomicapretto), a key
contributor to Bambi, provided invaluable assistance in the development of the
HSSM package.
Those contributions have greatly enhanced the functionality and quality of the
HSSM.
Raw data
{
"_id": null,
"home_page": "https://github.com/lnccbrown/HSSM",
"name": "HSSM",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.12,>=3.10",
"maintainer_email": null,
"keywords": "HSSM, sequential sampling models, bayesian, bayes, mcmc",
"author": "Alexander Fengler",
"author_email": "alexander_fengler@brown.edu",
"download_url": "https://files.pythonhosted.org/packages/c0/9c/f4657d94d3707343a3f46e2ad3c6fe22793e2b22af2b11bd8e59ea6dd2b7/hssm-0.2.5.tar.gz",
"platform": null,
"description": "<div style=\"position: relative; width: 100%;\">\n <img src=\"docs/images/mainlogo.png\" style=\"width: 250px;\">\n <a href=\"https://ccbs.carney.brown.edu/brainstorm\" style=\"position: absolute; right: 0; top: 50%; transform: translateY(-50%);\">\n <img src=\"docs/images/Brain-Bolt-%2B-Circuits.gif\" style=\"width: 100px;\">\n </a>\n</div>\n\n## HSSM - Hierarchical Sequential Sampling Modeling\n\n\n\n\n\n\n\n[](https://github.com/astral-sh/ruff)\n\n### Overview\n\nHSSM is a Python toolbox that provides a seamless combination of\nstate-of-the-art likelihood approximation methods with the wider ecosystem of\nprobabilistic programming languages. It facilitates flexible hierarchical model\nbuilding and inference via modern MCMC samplers. HSSM is user-friendly and\nprovides the ability to rigorously estimate the impact of neural and other\ntrial-by-trial covariates through parameter-wise mixed-effects models for a\nlarge variety of cognitive process models. HSSM is a\n<a href=\"https://ccbs.carney.brown.edu/brainstorm\">BRAINSTORM</a> project in\ncollaboration with the Center for Computation and Visualization and the Center\nfor Computational Brain Science within the Carney Institute at Brown University.\n\n- Allows approximate hierarchical Bayesian inference via various likelihood\n approximators.\n- Estimate impact of neural and other trial-by-trial covariates via native\n hierarchical mixed-regression support.\n- Extensible for users to add novel models with corresponding likelihoods.\n- Built on PyMC with support from the Python Bayesian ecosystem at large.\n- Incorporates Bambi's intuitive `lmer`-like regression parameter specification\n for within- and between-subject effects.\n- Native ArviZ support for plotting and other convenience functions to aid the\n Bayesian workflow.\n- Utilizes the ONNX format for translation of differentiable likelihood\n approximators across backends.\n\n### [Official documentation](https://lnccbrown.github.io/HSSM/).\n\n## Cite HSSM\n\nFengler, A., Xu, Y., Bera, K., Omar, A., Frank, M.J. (in preparation). HSSM: A\ngeneralized toolbox for hierarchical bayesian estimation of computational models\nin cognitive neuroscience.\n\n## Example\n\nHere is a simple example of how to use HSSM:\n\n```python\nimport hssm\n\n# Load a package-supplied dataset\ncav_data = hssm.load_data(\"cavanagh_theta\")\n\n# Define a basic hierarchical model with trial-level covariates\nmodel = hssm.HSSM(\n model=\"ddm\",\n data=cav_data,\n include=[\n {\n \"name\": \"v\",\n \"prior\": {\n \"Intercept\": {\"name\": \"Normal\", \"mu\": 0.0, \"sigma\": 0.1},\n \"theta\": {\"name\": \"Normal\", \"mu\": 0.0, \"sigma\": 0.1},\n },\n \"formula\": \"v ~ theta + (1|participant_id)\",\n \"link\": \"identity\",\n },\n ],\n)\n\n# Sample from the posterior for this model\nmodel.sample()\n```\n\nTo quickly get started with HSSM, please follow\n[this tutorial](https://lnccbrown.github.io/HSSM/getting_started/getting_started/).\nFor a deeper dive into HSSM, please follow\n[our main tutorial](https://lnccbrown.github.io/HSSM/tutorials/main_tutorial/).\n\n## Installation\n\nHSSM can be directly installed into your conda environment on Linux and MacOS.\nInstalling HSSM on windows takes only one more simple step. We have a more\ndetailed\n[installation guide](https://lnccbrown.github.io/HSSM/getting_started/installation/)\nfor users with more specific setups.\n\n### Install HSSM on Linux and MacOS (CPU only)\n\nUse the following command to install HSSM into your virtual environment:\n\n```bash\nconda install -c conda-forge hssm\n```\n\n### Install HSSM on Linux and MacOS (with GPU Support)\n\nIf you need to sample with GPU, please install JAX with GPU support before\ninstalling HSSM:\n\n```bash\nconda install jaxlib=*=*cuda* jax cuda-nvcc -c conda-forge -c nvidia\nconda install -c conda-forge hssm\n```\n\n### Install HSSM on Windows (CPU only)\n\nBecause dependencies such as `jaxlib` and `numpyro` are not up-to-date on Conda,\nthe easiest way to install HSSM on Windows is to install PyMC first and install\nHSSM via `pip`:\n\n```bash\nconda install -c conda-forge pymc\npip install hssm\n```\n\n### Install HSSM on Windows (with GPU support)\n\nYou simply need to install JAX with GPU support after installing PyMC:\n\n```bash\nconda install -c conda-forge pymc\npip install hssm[cuda12]\n```\n\n### Support for Apple Silicon, AMD, and other GPUs\n\nJAX also has support other GPUs. Please follow the\n[Official JAX installation guide](https://jax.readthedocs.io/en/latest/installation.html)\nto install the correct version of JAX before installing HSSM.\n\n## Advanced Installation\n\n### Install HSSM directly with Pip\n\nHSSM is also available through PyPI. You can directly install it with pip into\nany virtual environment via:\n\n```bash\npip install hssm\n```\n\n**Note:** While this installation is much simpler, you might encounter this\nwarning message\n`WARNING (pytensor.tensor.blas): Using NumPy C-API based implementation for BLAS functions.`\nPlease refer to our\n[advanced installation guide](https://lnccbrown.github.io/HSSM/getting_started/installation/)\nfor more details.\n\n### Install the dev version of HSSM\n\nYou can install the dev version of `hssm` directly from this repo:\n\n```bash\npip install git+https://github.com/lnccbrown/HSSM.git\n```\n\n### Install HSSM on Google Colab\n\nGoogle Colab comes with PyMC and JAX pre-configured. That holds true even if you\nare using the GPU and TPU backend, so you simply need to install HSSM via pip on\nColab regardless of the backend you are using:\n\n```bash\n!pip install hssm\n```\n\n## Troubleshooting\n\n**Note:** Possible solutions to any issues with installations with hssm can be\nlocated [here](https://github.com/lnccbrown/HSSM/discussions). Also feel free to\nstart a new discussion thread if you don't find answers there. We recommend\ninstalling HSSM into a new conda environment with Python 3.10 or 3.11 to prevent\nany problems with dependencies during the installation process. Please note that\nhssm is only tested for python 3.10, 3.11. As of HSSM v0.2.0, support for Python\n3.9 is dropped. Use unsupported python versions with caution.\n\n## License\n\nHSSM is licensed under\n[Copyright 2023, Brown University, Providence, RI](LICENSE)\n\n## Support\n\nFor questions, please feel free to\n[open a discussion](https://github.com/lnccbrown/HSSM/discussions).\n\nFor bug reports and feature requests, please feel free to\n[open an issue](https://github.com/lnccbrown/HSSM/issues) using the\ncorresponding template.\n\n## Contribution\n\nIf you want to contribute to this project, please follow our\n[contribution guidelines](docs/CONTRIBUTING.md).\n\n## Acknowledgements\n\nWe would like to extend our gratitude to the following individuals for their\nvaluable contributions to the development of the HSSM package:\n\n- [Bambi](https://github.com/bambinos/bambi) - A special thanks to the Bambi\n project for providing inspiration, guidance, and support throughout the\n development process. [Tom\u00e1s Capretto](https://github.com/tomicapretto), a key\n contributor to Bambi, provided invaluable assistance in the development of the\n HSSM package.\n\nThose contributions have greatly enhanced the functionality and quality of the\nHSSM.\n",
"bugtrack_url": null,
"license": "Copyright 2023, Brown University, Providence, RI.",
"summary": "Bayesian inference for hierarchical sequential sampling models.",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/lnccbrown/HSSM",
"Repository": "https://github.com/lnccbrown/HSSM"
},
"split_keywords": [
"hssm",
" sequential sampling models",
" bayesian",
" bayes",
" mcmc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2d8fbcca0837397a4c1a26a461817dffd344568c26303038f15a2f3a8c8e0c2d",
"md5": "96c5d7462b14b8e750c3c830036a92fa",
"sha256": "bea0ecab55d3a4eaefdf88067b6ce496793c946dc1c0a00cb6574e7cdcb76021"
},
"downloads": -1,
"filename": "hssm-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96c5d7462b14b8e750c3c830036a92fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.12,>=3.10",
"size": 204720,
"upload_time": "2025-01-01T21:37:04",
"upload_time_iso_8601": "2025-01-01T21:37:04.533825Z",
"url": "https://files.pythonhosted.org/packages/2d/8f/bcca0837397a4c1a26a461817dffd344568c26303038f15a2f3a8c8e0c2d/hssm-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c09cf4657d94d3707343a3f46e2ad3c6fe22793e2b22af2b11bd8e59ea6dd2b7",
"md5": "9716d7e3162e605ae284e87bbc0a369e",
"sha256": "8689e3f361b1abcb6fcc6e66cc0d9d405d1ed50cbd3c1ec85bdd4ba1c3b62699"
},
"downloads": -1,
"filename": "hssm-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "9716d7e3162e605ae284e87bbc0a369e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.12,>=3.10",
"size": 192074,
"upload_time": "2025-01-01T21:37:07",
"upload_time_iso_8601": "2025-01-01T21:37:07.205496Z",
"url": "https://files.pythonhosted.org/packages/c0/9c/f4657d94d3707343a3f46e2ad3c6fe22793e2b22af2b11bd8e59ea6dd2b7/hssm-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-01 21:37:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lnccbrown",
"github_project": "HSSM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hssm"
}
JSON
