Merge pull request #226 from lnccbrown/206-docs-update

Updated documentation to include a more detailed installation guide

docs/changelog.md

@@ -2,6 +2,19 @@
 
 ## 0.1.x
 
+### 0.1.2
+
+- Improved numerical stability of `analytical` likelihoods.
+- Added the ability to handle lapse distributions.
+- Added the ability to perform prior predictive sampling.
+- Improved model information output - now default priors provided by `bambi` is also printed.
+- Added a `hierarchical` switch which turns all parameters into hierarchical
+  when `participant_id` is provided in data.
+- Parameters are now named more consistently (group-specific terms are now aliased correctly).
+
+- Fixed a bug where information about which parameter is regression is incorrectly passed.
+- Added links to Colab to try out hssm in Google Colab.
+
 ### 0.1.1
 
 - Handle `float` types in `PyTensor` and `JAX` more consistently and explicitly.

docs/index.md

@@ -17,7 +17,7 @@ HSSM is a Python toolbox that provides a seamless combination of state-of-the-ar
 
 **License**: HSSM is licensed under [Copyright 2023, Brown University, Providence, RI](../LICENSE)
 
-**Version**: 0.1.1
+**Version**: 0.1.2
 
 - 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.
@@ -40,35 +40,16 @@ You can also install the bleeding edge version of `hssm` directly from this repo
 ```
 pip install git+https://github.com/lnccbrown/HSSM.git
 ```
-!!! note 
 
-Possible solutions to any issues with installations with hssm can be located [here](https://github.com/lnccbrown/HSSM/discussions). We recommend leveraging an environment manager with Python 3.9~3.11 to prevent any problems with dependencies during the installation process. Please note that hssm is tested for python 3.9, 3.10, 3.11. Use other python versions with caution. For more detailed guidance, please refer to this [discussion](https://github.com/lnccbrown/HSSM/discussions/152). 
-
-### Optional dependencies
-
-**Dependency for graph() Function**
+For more detailed guidance, please check out our [installation guide](installation.md).
 
 !!! note
 
-    In addition to the installation of the main hssm class, there is an optional dependency for the graph() function. This dependency requires graphviz, which can be installed conveniently using conda with the following command:
-
-    ```bash
-    conda install -c conda-forge python-graphviz
-    ```
-
-    Alternatively, you have the option to install the graphviz binaries manually and then install the Python bindings using pip with the following command:
-
-    ```bash
-    pip install graphviz
-    ```
-
-**Dependency for sampler="nuts_numpyro"**
-
-`numpyro` needs to be installed to use the `nuts_numpyro` sampler:
-
-```bash
-pip install numpyro
-```
+    Possible solutions to any issues with installations with hssm can be located
+    [here](https://github.com/lnccbrown/HSSM/discussions). We recommend leveraging an
+    environment manager with Python 3.9~3.11 to prevent any problems with dependencies
+    during the installation process. Please note that hssm is tested for python 3.9, 3.10,
+    3.11. Use other python versions with caution.
 
 ### Setting global float type
 

docs/installation.md

@@ -0,0 +1,84 @@
+# Installation
+
+## Install the HSSM package
+
+### Install via `pip` from PyPI
+
+HSSM is available through [PyPI](https://pypi.org/project/hssm/). The easiest way to
+install HSSM is through pip.
+
+```bash
+pip install hssm
+```
+
+Because HSSM depends on very specific versions of PyMC, JAX and Bambi, we recommend that
+you install HSSM into a dedicated virtual environment to avoid dependency conflicts.
+
+### Install from GitHub
+
+You can also install the bleeding edge version of `hssm` directly from
+[our repo](https://github.com/lnccbrown/HSSM):
+
+```
+pip install git+https://github.com/lnccbrown/HSSM.git
+```
+
+## Install optional dependencies
+
+Some functionalities in HSSM are available through optional dependencies.
+
+### Sampling with JAX through `numpyro` or `blackjax`
+
+JAX-based sampling is done through `numpyro` and `blackjax`. You need to have `numpyro`
+installed if you want to use the `nuts_numpyro` sampler.
+
+```bash
+pip install numpyro
+```
+
+Likewise, you need to have `blackjax` installed if you want to use the `nuts_blackjax`
+sampler.
+
+```bash
+pip install blackjax
+```
+
+### Visualizing the model
+
+Model graphs are created with `model.graph()` through `graphviz`. In order to use it,
+you need to have `graphviz` installed system-wide and then install its Python binding:
+
+#### Install graphviz system-wide
+
+Please follow the instructions on the
+[graphviz official site](https://graphviz.org/download/) to install graphviz for your
+specific platform.
+
+#### Install graphviz python binding
+
+Once graphviz is installed, you can install its Python binding via pip:
+
+```bash
+pip install graphviz
+```
+
+## Common issues
+
+1. `pip` installation fails with missing dependencies:
+
+   Here's an example:
+
+   ```
+   ERROR: Could not find a version that satisfies the requirement jaxlib<0.5.0,>=0.4.0 (from hssm) (from versions: none)
+   ERROR: No matching distribution found for jaxlib<0.5.0,>=0.4.0 (from hssm)
+   ```
+
+   HSSM has very specific requirements for the versions of `jax`, `pymc`, and `bambi`.
+   This problem can usually be resolved by installing HSSM into a dedicated virtual
+   environment.
+
+## Questions?
+
+If you have any questions, please
+[open an issue](https://github.com/lnccbrown/HSSM/issues) in our
+[GitHub repo](https://github.com/lnccbrown/HSSM).