[DOC] Update to HSSM documentation for better organization and code f…

…ormatting (#614) * Update README.md * Add back black as dev dependency to format code in documentation * Update to documentation
lnccbrown · Dec 31, 2024 · 577cdc4 · 577cdc4
1 parent 8fd9584
commit 577cdc4
Show file tree

Hide file tree

Showing 21 changed files with 3,580 additions and 2,174 deletions.
diff --git a/README.md b/README.md
@@ -14,26 +14,40 @@
 ![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/lnccbrown/HSSM/run_slow_tests.yml)
 ![GitHub Repo stars](https://img.shields.io/github/stars/lnccbrown/HSSM)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-[![codecov](https://codecov.io/gh/lnccbrown/HSSM/branch/main/graph/badge.svg)](https://codecov.io/gh/lnccbrown/HSSM)
-
 
 ### 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.
+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.
+- 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, P., Bera, K., Omar, A., Frank, M.J. (in preparation). HSSM: A generalized toolbox for hierarchical bayesian estimation of computational models in cognitive neuroscience.
+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
 
@@ -43,7 +57,7 @@ Here is a simple example of how to use HSSM:
 import hssm
 
 # Load a package-supplied dataset
-cav_data = hssm.load_data('cavanagh_theta')
+cav_data = hssm.load_data("cavanagh_theta")
 
 # Define a basic hierarchical model with trial-level covariates
 model = hssm.HSSM(
@@ -66,12 +80,18 @@ model = hssm.HSSM(
 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/).
+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.
+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)
 
@@ -83,7 +103,8 @@ 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:
+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
@@ -92,7 +113,9 @@ 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`:
+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
@@ -110,20 +133,27 @@ 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.
-
+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:
+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.
+**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
 
@@ -135,40 +165,53 @@ 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:
+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.
+**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)
+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 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.
+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).
+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:
+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.
+- [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.
+Those contributions have greatly enhanced the functionality and quality of the
+HSSM.
diff --git a/docs/api/distribution_utils.md b/docs/api/distribution_utils.md
@@ -1 +1,19 @@
+The `hssm.distribution_utils` contains useful functions for building `pm.Distribution`
+classes. Other than the `download_hf` function that downloads ONNX models shared on our
+[huggingface model repository](https://huggingface.co/franklab/HSSM/tree/main), you will
+generally not have to use these functions. For advanced users who want to build their
+own PyMC models, they can use these functions to create `pm.Distribution` and
+`RandomVariable` classes that they desire.
+
 ::: hssm.distribution_utils
+    handler: python
+    options:
+        members:
+        - download_hf
+        - make_distribution
+        - make_ssm_rv
+        - make_family
+        - make_likelihood_callable
+        - make_missing_data_callable
+        - make_blackbox_op
+        - assemble_callables
diff --git a/docs/api/hssm.md b/docs/api/hssm.md
@@ -1 +1,27 @@
-::: hssm
+Use `hssm.HSSM` class to construct an HSSM model.
+
+::: hssm.HSSM
+    handler: python
+    options:
+        show_root_heading: true
+        show_signature_annotations: true
+        show_object_full_path: false
+        show_signature: true  # Make sure this is true
+        docstring_options:
+            ignore_init_summary: false
+        members:
+            - traces
+            - pymc_model
+            - sample
+            - sample_posterior_predictive
+            - sample_prior_predictive
+            - vi
+            - find_MAP
+            - log_likelihood
+            - summary
+            - plot_trace
+            - graph
+            - plot_posterior_predictive
+            - plot_quantile_probability
+            - restore_traces
+            - initial_point
diff --git a/docs/api/likelihoods.md b/docs/api/likelihoods.md
@@ -1 +1,7 @@
+The `hssm.likelihoods` submodule exports a few likelihood functions. These functions
+are already used in the model building process for some supported models, such as `ddm`,
+`ddm_sdv`, and `full_ddm`, so you typically would not have to deal with them. However,
+they can be helpful if you want to use them to build a model yourself in PyMC. Please
+checkout the [this tutorial](../tutorials/pymc.ipynb) for more details.
+
 :::hssm.likelihoods
diff --git a/docs/api/link.md b/docs/api/link.md
@@ -0,0 +1 @@
+::: hssm.Link
diff --git a/docs/api/load_data.md b/docs/api/load_data.md
@@ -0,0 +1 @@
+::: hssm.load_data
diff --git a/docs/api/model_config.md b/docs/api/model_config.md
@@ -0,0 +1 @@
+::: hssm.ModelConfig
diff --git a/docs/api/param.md b/docs/api/param.md
@@ -0,0 +1 @@
+::: hssm.Param
diff --git a/docs/api/plotting.md b/docs/api/plotting.md
@@ -1 +1,8 @@
+The `hssm.plotting` module provide functionalities to create HSSM-specific plots such
+as the posterior predictive plots. Please checkout
+[the plotting tutorial](../tutorials/plotting.ipynb) for more examples on how to use
+these functions. Note that each plotting function has an equivalent in the
+[`hssm.HSSM`](hssm.md) class, so you can call these functions from a built model without
+having to import these functions.
+
 :::hssm.plotting
diff --git a/docs/api/prior.md b/docs/api/prior.md
@@ -0,0 +1 @@
+::: hssm.Prior
diff --git a/docs/api/set_floatx.md b/docs/api/set_floatx.md
@@ -0,0 +1 @@
+::: hssm.set_floatX
diff --git a/docs/api/show_defaults.md b/docs/api/show_defaults.md
@@ -0,0 +1 @@
+::: hssm.show_defaults
diff --git a/docs/api/simulate_data.md b/docs/api/simulate_data.md
@@ -0,0 +1 @@
+::: hssm.simulate_data