### Install HSSM and Dependencies

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/pymc_to_hssm.ipynb

Uncomment and run these lines in Google Colab to install the necessary libraries for the tutorial. Remember to restart the runtime after installation.

```python
# If running this on Colab, please uncomment the next line
# !pip install hssm
# !pip install onnxruntime
# !pip install "zeus-mcmc>=2.5.4"
```

--------------------------------

### Install JAX with GPU Support on Windows

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/installation.md

Install JAX with CUDA 12 support using pip on Windows before installing HSSM.

```bash
pip install jax[cuda12]
```

--------------------------------

### Install all dev dependencies

Source: https://github.com/lnccbrown/hssm/blob/main/CLAUDE.md

Installs all development dependencies including those for testing, linting, and documentation.

```bash
# Install all dev dependencies
uv sync --group dev --group notebook --group docs
```

--------------------------------

### Install All Dependencies and Extras with uv

Source: https://github.com/lnccbrown/hssm/blob/main/docs/local_development.md

Install all dependency groups and extras, including optional GPU support for JAX.

```sh
uv sync --all-groups --all-extras
```

--------------------------------

### Install HSSM on Windows (CPU Only)

Source: https://github.com/lnccbrown/hssm/blob/main/README.md

Install PyMC first using conda, then install HSSM via pip. This method is recommended for Windows due to dependency management.

```bash
conda install -c conda-forge pymc
pip install hssm
```

--------------------------------

### Set up Starting Point and Tracker for ADVI

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/variational_inference.ipynb

Prepares the initial point for optimization and sets up a tracker to monitor mean and standard deviation during the VI fit. This helps in assessing convergence.

```python
# Set up starting point
start = cav_model.pymc_model.initial_point()
vars_dict = {var.name: var for var in cav_model.pymc_model.continuous_value_vars}
x0 = DictToArrayBijection.map(
    {var_name: value for var_name, value in start.items() if var_name in vars_dict}
)

# Define quantities to track
tracker = pm.callbacks.Tracker(
    mean=lambda: DictToArrayBijection.rmap(
        RaveledVars(advi.approx.mean.eval(), x0.point_map_info), start
    ),  # callable that returns mean
    std=lambda: DictToArrayBijection.rmap(
        RaveledVars(advi.approx.std.eval(), x0.point_map_info), start
    ),  # callable that returns std
)
```

--------------------------------

### Build documentation with MkDocs

Source: https://github.com/lnccbrown/hssm/blob/main/CLAUDE.md

Builds the project documentation using MkDocs. Requires the 'notebook' and 'docs' dependency groups to be installed.

```bash
# Build docs
uv run --group notebook --group docs mkdocs build
```

--------------------------------

### Install Graphviz Python Binding

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/installation.md

After installing graphviz system-wide, install its Python binding using pip for model visualization.

```bash
pip install graphviz
```

--------------------------------

### Install Specific GPU Dependencies with uv

Source: https://github.com/lnccbrown/hssm/blob/main/docs/local_development.md

Install development and test dependencies along with CUDA 12 extras for GPU support.

```sh
uv sync --group dev --group test --extra cuda12
```

--------------------------------

### Install HSSM with BayesFlow support

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/bayesflow_lre_integration.ipynb

Uncomment and run this cell on Google Colab to install the necessary libraries. Remember to restart your runtime after installation.

```python
# Uncomment below if running on Colab
# !pip install hssm[bayesflow]
```

--------------------------------

### Install HSSM on Linux/MacOS with GPU Support

Source: https://github.com/lnccbrown/hssm/blob/main/README.md

Install JAX with GPU support first, then install HSSM using conda. Ensure your environment has the necessary CUDA toolkit.

```bash
conda install jaxlib=*=*cuda* jax cuda-nvcc -c conda-forge -c nvidia
conda install -c conda-forge hssm
```

--------------------------------

### Verify uv Installation

Source: https://github.com/lnccbrown/hssm/blob/main/docs/local_development.md

Check if the uv package manager is installed correctly by displaying its version.

```sh
uv --version
```

--------------------------------

### Install JAX with GPU Support on Linux/macOS

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/installation.md

Before installing HSSM with GPU support on Linux/macOS, install JAX with CUDA support using conda.

```bash
conda install jaxlib=*=*cuda* jax cuda-nvcc -c conda-forge -c nvidia
```

--------------------------------

### Install JAX on Windows (CPU)

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/installation.md

On Windows, JAXlib is not available via conda-forge. Install JAX using pip before installing HSSM.

```bash
pip install jax
```

--------------------------------

### Install Development and Test Dependencies with uv

Source: https://github.com/lnccbrown/hssm/blob/main/docs/local_development.md

Synchronize development and testing dependencies for HSSM using uv, as defined in pyproject.toml.

```sh
uv sync --group dev --group test
```

--------------------------------

### Install Blackjax Sampler

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/installation.md

Install the 'blackjax' library via pip if you intend to use its sampling algorithms with HSSM.

```bash
pip install blackjax
```

--------------------------------

### Setup and Import Libraries

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/bayesflow_lre_integration.ipynb

Sets the Keras backend to JAX and imports essential libraries for HSSM, BayesFlow, JAX, PyMC, ArviZ, and simulation utilities. It also checks for the availability of BayesFlow and Keras.

```python
import os

os.environ["KERAS_BACKEND"] = "jax"

import arviz as az
import jax
import jax.numpy as jnp
import matplotlib.pyplot as plt
import numpy as np
import pymc as pm
import pytensor.tensor as pt

import hssm
from hssm.config import ModelConfig
from ssms.basic_simulators.simulator import simulator as ssm_simulator
from ssms.config import model_config as ssms_model_config

try:
    import bayesflow as bf
    import keras
except ImportError:
    raise ImportError(
        "This tutorial requires bayesflow and keras. "
        "Install them with:  pip install hssm[bayesflow]"
    )

print(f"Keras backend : {keras.backend.backend()}")
print(f"JAX devices   : {jax.devices()}")
```

--------------------------------

### Install HSSM Package

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/hmm_ddm_regime_switching.ipynb

Installs the HSSM package. Uncomment and run this cell if you are using Google Colab. Remember to restart your runtime after installation.

```python
# Uncomment below if running on Colab
# !pip install hssm
```

--------------------------------

### Install bayeux-ml and dependencies

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/tutorial_bayeux.ipynb

Install the bayeux-ml package and its dependencies using pip. This command is for a virtual environment where HSSM is already installed.

```sh
pip install hssm bayeux-ml flowMC==0.3.4 jax[cuda12]==0.4.38 jaxlib==0.4.38
```

--------------------------------

### Install HSSM Package

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/main_tutorial.ipynb

Use this command to install the HSSM package from GitHub, especially if running on Google Colab. Remember to uncomment the line before running.

```python
# If running this on Colab, please uncomment the next line
# !pip install git+https://github.com/lnccbrown/HSSM@workshop_tutorial
```

--------------------------------

### Run MCMC sampling with Zeus

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/compile_logp.ipynb

Execute the MCMC sampling process using the initialized Zeus sampler and the provided starting points.

```python
sampler.run_mcmc(start, 1000)
```

--------------------------------

### Install HSSM on Colab

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/lapse_prob_and_dist.ipynb

Uncomment and run this line to install the HSSM library if you are using Google Colab.

```python
# If running this on Colab, please uncomment the next line
# !pip install hssm
```

--------------------------------

### Install HSSM with Pip

Source: https://github.com/lnccbrown/hssm/blob/main/docs/index.md

Use this command to install the latest stable version of HSSM from PyPI. Ensure you are in a virtual environment.

```bash
pip install hssm
```

--------------------------------

### Install HSSM Package

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/hierarchical_modeling.ipynb

Installs the HSSM package using pip. This is a prerequisite for using HSSM functionalities.

```python
# !pip install hssm
```

--------------------------------

### Setup and Data Simulation for PyMC Regression

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/main_tutorial.ipynb

Defines parameters, simulates data using the DDM model, and adds covariates to the dataset. It also prepares a boolean vector for regression parameters and defines a callable likelihood function.

```python
import pytensor.tensor as pt
import pymc as pm
import arviz as az
import numpy as np

# Assuming hssm and make_params_is_reg_vec, make_likelihood_callable, make_distribution are defined elsewhere
# For demonstration, let's mock them if they are not available in this context
class MockHSSM:
    def simulate_data(self, model, theta, size):
        # Mock simulation
        return {"rt": np.random.rand(size), "response": np.random.randint(0, 2, size=size)}
    
def defaults():
    class DefaultConfig:
        class Angle:
            list_params = ["v", "a", "z", "t", "theta"]
        default_model_config = {"angle": Angle()}
    return DefaultConfig()

hssm = MockHSSM()
hssm.defaults = MockHSSM()

def make_params_is_reg_vec(reg_parameters, parameter_names):
    # Mock function
    return [p in reg_parameters for p in parameter_names]

def make_likelihood_callable(loglik, loglik_kind, backend, params_is_reg):
    # Mock function
    return lambda **kwargs: None

def make_distribution(name, loglik, list_params):
    # Mock function
    return lambda name, **kwargs: None

v_intercept = 0.3
x = np.random.uniform(-1, 1, size=1000)
v_x = 0.8
y = np.random.uniform(-1, 1, size=1000)
v_y = 0.3
v_intercept_pymc_reg = 0.3
x_pymc_reg = np.random.uniform(-1, 1, size=1000)
v_x_pymc_reg = 0.8
y_pymc_reg = np.random.uniform(-1, 1, size=1000)
v_y_pymc_reg = 0.3
v_pymc_reg = v_intercept + (v_x * x) + (v_y * y)

param_dict_pymc_reg = dict(
    v_Intercept=v_intercept_pymc_reg,
    v_x=v_x_pymc_reg,
    v_y=v_y_pymc_reg,
    v=v_pymc_reg,
    a=1.5,
    z=0.5,
    t=0.1,
    theta=0.0,
)

# base dataset
pymc_reg_data = hssm.simulate_data(model="ddm", theta=param_dict_pymc_reg, size=1)

# Adding covariates into the datsaframe
pymc_reg_data["x"] = x
pymc_reg_data["y"] = y

# Make the boolean vector for params_is_reg argument
bool_param_reg = make_params_is_reg_vec(
    reg_parameters=["v"],
    parameter_names=hssm.defaults.default_model_config["angle"]["list_params"],
)

angle_loglik = make_likelihood_callable(
    loglik="angle.onnx",
    loglik_kind="approx_differentiable",
    backend="jax",
    params_is_reg=bool_param_reg,
)

ANGLE = make_distribution(
    "angle",
    loglik=angle_loglik,
    list_params=hssm.defaults.default_model_config["angle"]["list_params"],
)
```

--------------------------------

### Load Data for Plotting Example

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/plotting.ipynb

Loads test data for the Cavanagh experiment from CSV and ArviZ inference data from NetCDF. This data is used for subsequent plotting demonstrations.

```python
from pathlib import Path

import arviz as az
import matplotlib.pyplot as plt
import pandas as pd
import numpy as np
import seaborn as sns

import hssm
import hssm.plotting

%matplotlib inline
%config InlineBackend.figure_format='retina'

fixtures_dir = Path("../../tests/fixtures")
cav_data_test = pd.read_csv(fixtures_dir / "cavanagh_theta_test.csv")
cav_data_traces = az.from_netcdf(fixtures_dir / "cavanagh_idata.nc")
```

--------------------------------

### Install Development Version of HSSM

Source: https://github.com/lnccbrown/hssm/blob/main/docs/index.md

Install the latest development version of HSSM directly from its GitHub repository. This is useful for testing upcoming features or contributing to the project.

```bash
pip install git+https://github.com/lnccbrown/HSSM.git
```

--------------------------------

### Simulate DDM Data using ssm-simulators with Parameter Matrix

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/main_tutorial.ipynb

Directly uses the ssm-simulators package to generate data equivalent to the hssm.simulate_data example. Parameters are passed as a NumPy matrix, requiring careful attention to column ordering.

```python
import numpy as np
import pandas as pd
from ssms.basic_simulators.simulator import simulator

# a changes trial wise
theta_mat = np.zeros((1000, 4))
theta_mat[:, 0] = v_true  # v
theta_mat[:, 1] = a_trialwise  # a
theta_mat[:, 2] = z_true  # z
theta_mat[:, 3] = t_true  # t

# simulate data
sim_out_trialwise = simulator(
    theta=theta_mat,  # parameter_matrix
    model="ddm",  # specify model (many are included in ssms)
    n_samples=1,  # number of samples for each set of parameters
    # (plays the role of `size` parameter in `hssm.simulate_data`)
)

```

--------------------------------

### Initializing HSSM Model with Logit Link

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/initial_values.ipynb

Initialize an HSSM model with a 'ddm' model type and 'log_logit' link settings. This example demonstrates setting up a regression with logit link functions.

```python
model = hssm.HSSM(
    data=cav_data,
    model="ddm",
    link_settings="log_logit",
    loglik_kind="approx_differentiable",
    include=[{"name": "a", "formula": "a ~ 1 + theta"}],
)
```

--------------------------------

### Pip Installation Failure Example

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/installation.md

This error occurs when pip cannot find a suitable version for a required dependency, such as jaxlib, due to strict version requirements of HSSM. Installing HSSM in a dedicated virtual environment is recommended to resolve this.

```text
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)
```

--------------------------------

### Get initial parameter point

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/compile_logp.ipynb

Retrieve the initial parameter values for the model. These values are used as a starting point for MCMC sampling.

```python
print(model.initial_point(transformed=False))
```

--------------------------------

### Serve documentation locally with MkDocs

Source: https://github.com/lnccbrown/hssm/blob/main/CLAUDE.md

Serves the project documentation locally for preview. Requires the 'notebook' and 'docs' dependency groups.

```bash
# Serve docs locally
uv run --group notebook --group docs mkdocs serve
```

--------------------------------

### Inspect Initialized Model Parameters

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/rlssm_rlwm_model.ipynb

Retrieves and displays the initial values for the parameters of the HSSM model after initialization. This is useful for verifying the setup and understanding the starting point for inference.

```python
hssm_model.initvals
```

--------------------------------

### Download Tutorial Data Files

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/pymc_to_hssm.ipynb

Use these wget commands to download the required ONNX data files for the tutorial. Ensure the target directory exists or is created.

```bash
# Data Files
!wget -P  data/mathpsych_workshop_2025_data https://raw.githubusercontent.com/lnccbrown/HSSM/main/docs/tutorials/pymc_to_hssm/mathpsych_workshop_2025_data/race_3_no_bias_lan_batch.onnx
!wget -P  data/mathpsych_workshop_2025_data https://raw.githubusercontent.com/lnccbrown/HSSM/main/docs/tutorials/pymc_to_hssm/mathpsych_workshop_2025_data/ddm_lan_batch.onnx
```

--------------------------------

### PyTensor BLAS Warning Example

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/installation.md

This warning indicates that PyTensor, the compute backend for PyMC, cannot locate a BLAS library for optimized computations. It suggests installing HSSM within a conda environment or manually linking a BLAS library.

```text
WARNING (pytensor.tensor.blas): Using NumPy C-API based implementation for BLAS functions.
```

--------------------------------

### Install Graphviz with Conda

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/installation.md

If HSSM was installed in a conda environment, install the 'graphviz' package using conda for model visualization.

```bash
conda install -c conda-forge graphviz
```

--------------------------------

### Initialize and Run Zeus Sampler

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/pymc_to_hssm.ipynb

Initializes and runs the Zeus MCMC sampler with the custom log probability wrapper. It sets up the sampler with the number of walkers, dimensions, and the log probability function, then runs the MCMC chain.

```python
import zeus

start = np.random.uniform(low=-0.2,
                          high=0.2,
                          size=(10, 5)) + np.tile([0.5, 1.5, 0.5, 1.5, 0.3], (10, 1)
)
sampler = zeus.EnsembleSampler(10, 5, mylogp)
sampler.run_mcmc(start, 1000)
```

--------------------------------

### Import Libraries and Set Up

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/poisson_race.ipynb

Imports necessary libraries (ArviZ, NumPy, Pandas, PyMC, HSSM) and sets the floatX type and ArviZ style. Initializes a random number generator.

```python
import arviz as az
import numpy as np
import pandas as pd
import pymc as pm

import hssm

hssm.set_floatX("float32")
az.style.use("arviz-whitegrid")

rng = np.random.default_rng(123)

```

--------------------------------

### Configure DDM Parameters

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/bayesflow_lre_integration.ipynb

Sets up configuration for the DDM model, including parameter names and bounds, and prints them. This is a prerequisite for defining the simulator.

```python
ddm_cfg = ssms_model_config["ddm"]
param_names = ddm_cfg["params"]
param_lower = np.array(ddm_cfg["param_bounds"][0])
param_upper = np.array(ddm_cfg["param_bounds"][1])

print("DDM parameters:")
for name, lo, hi in zip(param_names, param_lower, param_upper):
    print(f"  {name:5s}: bounds=[{lo:5.2f}, {hi:5.2f}]")
```

--------------------------------

### Model Sampling with JAX

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/jax_callable_contribution_onnx_example.ipynb

This snippet shows how to sample from a model using JAX as the backend. It configures the number of draws, tuning steps, sampler type, and chain/core configurations. Ensure JAX is correctly configured for multi-device execution if needed.

```python
model.sample(draws=500,
             tune=200,
             sampler="numpyro",
             chains = 2,
             cores = 2,
             discard_tuned_samples=False)
```

--------------------------------

### Install HSSM on Windows with GPU Support

Source: https://github.com/lnccbrown/hssm/blob/main/README.md

Install PyMC using conda, then install HSSM with CUDA 12 support via pip. This enables GPU acceleration on Windows.

```bash
conda install -c conda-forge pymc
pip install hssm[cuda12]
```

--------------------------------

### Initialize DDM Model with Shortcut Syntax

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/getting_started.ipynb

Initializes a DDM model using HSSM's shortcut syntax, specifying priors for parameters v, a, z, and t. Supports various prior distributions and explicit bounds.

```python
shortcut_ddm_model = hssm.HSSM(
    data=dataset,
    model="ddm",
    v={"name": "Normal", "mu": 0.0, "sigma": 2.0},
    a=dict(name="Uniform", lower=0.01, upper=5),
    z=hssm.Prior("Uniform", lower=0.01, upper=1.0),
    t=0.5,
)

shortcut_ddm_model
```

--------------------------------

### Simulate Data with Trial-Varying Parameters

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/main_tutorial.ipynb

Demonstrates how to simulate data where parameters vary by trial. By supplying a vector to the 'theta' dictionary and setting 'size=1', you can generate a dataset with a specified number of trials.

```python
# Example of simulating data with trial-varying parameters (conceptual)
# v_varying = np.random.normal(0.5, 0.1, 1000)
# dataset_varying = hssm.simulate_data(
#     model="ddm", theta=dict(v=v_varying, a=a_true, z=z_true, t=t_true), size=1
# )
# dataset_varying
```

--------------------------------

### Initialize Zeus sampler

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/compile_logp.ipynb

Initialize the Zeus ensemble sampler with the number of walkers, dimensions, and the wrapped log-likelihood function.

```python
import zeus

start = np.random.uniform(low=-0.2, high=0.2, size=(8, 4)) + np.tile(
    [0.5, 1.5, 0.5, 0.3], (8, 1)
)
sampler = zeus.EnsembleSampler(8, 4, mylogp)
```

--------------------------------

### Build and Train RatioApproximator

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/bayesflow_lre_integration.ipynb

Builds, trains, and saves a BayesFlow RatioApproximator if LOAD_PRETRAINED is False. It compiles the approximator, fits it using the simulator, plots the loss history, and saves the trained model.

```python
if not LOAD_PRETRAINED:
    adapter = bf.approximators.RatioApproximator.build_adapter(
        inference_variables=["v", "a", "z", "t"],
        inference_conditions=["obs"],
    )

    ratio_approximator = bf.approximators.RatioApproximator(
        adapter=adapter,
        inference_network=bf.networks.MLP(widths=[256, 256, 256]),
        standardize=None,
    )

    ratio_approximator.compile(optimizer="adam")
    history = ratio_approximator.fit(
        simulator=simulator,
        epochs=150,
        num_batches=200,
        batch_size=64,
    )

    bf.diagnostics.plots.loss(history)

    os.makedirs(SAVE_DIR, exist_ok=True)
    ratio_approximator.save(os.path.join(SAVE_DIR, PRE_TRAINED_NAME))
    print(f"Saved to {SAVE_DIR}/{PRE_TRAINED_NAME}")
else:
    print("Skipping training (LOAD_PRETRAINED = True).")
```

--------------------------------

### Download Data Files

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/scientific_workflow_hssm.ipynb

Download necessary data files for the workshop. These include parquet files for modeling and parameter files.

```bash
# Data Files
!wget -P  data/carney_workshop_2025_data/ https://raw.githubusercontent.com/lnccbrown/HSSM/main/scientific_workflow_hssm/data/carney_workshop_2025_full.parquet
!wget -P  data/carney_workshop_2025_data/ https://raw.githubusercontent.com/lnccbrown/HSSM/main/scientific_workflow_hssm/data/carney_workshop_2025_modeling.parquet
!wget -P  data/carney_workshop_2025_data/ https://raw.githubusercontent.com/lnccbrown/HSSM/main/scientific_workflow_hssm/data/carney_workshop_2025_parameters.pkl
```

--------------------------------

### Install HSSM on Linux and MacOS

Source: https://github.com/lnccbrown/hssm/blob/main/README.md

Use this command to install HSSM into your conda environment on Linux and MacOS for CPU-only usage.

```bash
conda install -c conda-forge hssm
```

--------------------------------

### Initialize Basic Drift Diffusion Model (DDM)

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/scientific_workflow_hssm.ipynb

Initializes a basic DDM using HSSM with approximate differentiable log-likelihood. Requires workshop_data to be loaded.

```python
BasicDDMModel = hssm.HSSM(data = workshop_data,
                          model = "ddm",
                          loglik_kind = "approx_differentiable",
                          global_formula = "y ~ 1",
                          noncentered = False,
                          )
```

--------------------------------

### Display Help for simulate_data

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/likelihoods.ipynb

Displays the help documentation for the `hssm.simulate_data` function, providing details on its parameters and usage.

```python
help(hssm.simulate_data)
```

--------------------------------

### Install HSSM on Google Colab

Source: https://github.com/lnccbrown/hssm/blob/main/docs/index.md

Install HSSM within a Google Colab notebook using pip. This command works regardless of the backend (GPU/TPU) being used.

```bash
!pip install hssm
```

--------------------------------

### Import HSSM Distribution Utilities

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/bayesflow_lre_integration.ipynb

Import necessary functions for creating JAX log-probability functions and PyTensor Ops.

```python
from hssm.distribution_utils.dist import make_distribution
from hssm.distribution_utils.jax import (
    make_jax_logp_funcs_from_callable,
    make_jax_logp_ops,
)
```

--------------------------------

### Install bayeux-ml on Google Colab

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/tutorial_bayeux.ipynb

Install the bayeux-ml package and its dependencies using pip, specifically for use in a Google Colab environment. Uncomment and run this line if needed.

```python
# Un-comment and run this only on Google Colab
# !pip install hssm bayeux-ml flowMC==0.3.4 jax[cuda12]==0.4.38 jaxlib==0.4.38
```

--------------------------------

### Run tests with pytest

Source: https://github.com/lnccbrown/hssm/blob/main/CLAUDE.md

Executes the test suite using pytest. Ensure all development dependencies are installed.

```bash
# Run tests
uv run pytest tests/
```

--------------------------------

### Hierarchical DDM Output

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/scientific_workflow_hssm.ipynb

Example output from the Hierarchical DDM model, showing parameters and performance metrics.

```text
Project: /lnccbrown/hssm
Content:
## DDM Hierarchical

DDM Hierarchical  76.438410   0.000000     True   log  
DDM               74.728599  32.604471    False   log  
```

```python

```

--------------------------------

### Instantiate RLSSM Model

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/rlssm_quickstart.ipynb

Create an instance of the RLSSM model by passing the prepared data and configuration. This step validates data requirements and builds the internal PyTensor Op for the Q-learning and log-likelihood computations. Verify the model's structure and parameters after instantiation.

```python
model = RLSSM(data=data, model_config=rlssm_config)

assert isinstance(model, RLSSM)
print("Model type       :", type(model).__name__)
print("Participants     :", model.n_participants)
print("Trials/subj      :", model.n_trials)
print("Free parameters  :", list(model.params.keys()))
assert "rl_alpha" in model.params, "rl_alpha must be a free parameter"
assert "v" not in model.params, "v is computed, not a free parameter"
model
```

--------------------------------

### Get DDM Model Config Keys

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/main_tutorial.ipynb

Retrieves the top-level keys available in the default model configuration for the DDM.

```python
hssm.config.default_model_config["ddm"].keys()
```

--------------------------------

### Run Test Suite with uv

Source: https://github.com/lnccbrown/hssm/blob/main/docs/local_development.md

Execute the project's test suite using the 'uv run' command to ensure all tests pass.

```sh
uv run pytest
```

--------------------------------

### Initialize DDM Model with Fixed Parameters

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/main_tutorial.ipynb

Sets up a DDM model instance, fixing all parameters except 'v' to predefined scalar values from param_dict_init.

```python
ddm_model_only_v = hssm.HSSM(
    data=dataset,
    model="ddm",
    a=param_dict_init["a"],
    t=param_dict_init["t"],
    z=param_dict_init["z"],
)
```

--------------------------------

### Sample with Custom Initial Values

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/initial_values.ipynb

Run the HSSM sampler using custom initial values. Note the limited tuning steps, which may leave initial values apparent in the chains.

```python
idata = model.sample(draws=100,
                     tune=100,
                     sampler="pymc",
                     cores=1,
                     chains=1,
                     initvals = my_initvals)
```

--------------------------------

### Visualize DDM Model Structure

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/getting_started.ipynb

Generates a graphical representation of the DDM model structure using Graphviz. This requires Graphviz to be installed on the system.

```python
# Uncomment if you have graphviz installed
simple_ddm_model.graph()
```

--------------------------------

### Simulate DDM Data

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/jax_callable_contribution_onnx_example.ipynb

Simulates a dataset from the Drift Diffusion Model (DDM) for use in subsequent examples. Sets a random seed for reproducibility.

```python
# simulate some data from the model
SEED = 123
obs_ddm = hssm.simulate_data(
    theta=dict(v=0.40,
               a=1.25,
               t=0.2,
               z=0.5),
    model="ddm",
    size=500,
    random_state = SEED,
)
```

--------------------------------

### Sample from the model using tfp_nuts

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/tutorial_bayeux.ipynb

Sample from the HSSM model using the `tfp_nuts` sampler provided by Bayeux. This demonstrates using an alternative sampler from the Bayeux library.

```python
idata = bx_model.mcmc.tfp_nuts(seed=jax.random.key(0))
```

--------------------------------

### Visualize Model Graph

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/getting_started.ipynb

Generates a graphical representation of the HSSM model structure, useful for understanding the relationships between parameters and components. Requires graphviz to be installed.

```python
# Uncomment to see model graph if you have graphviz installed
model_reg_v.graph()
```

--------------------------------

### Get Posterior Variable Names

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/plotting.ipynb

Use this to inspect the names of posterior variables available in the model traces. This can help in understanding the model's output.

```python
set(list(cav_model.traces.posterior.data_vars.keys()))
```

--------------------------------

### Sample from DDM Model

Source: https://github.com/lnccbrown/hssm/blob/main/docs/getting_started/getting_started.ipynb

Initiates sampling for the DDM model. Uses default initial values and displays initialization messages.

```python
example_ddm_model.sample()
```

--------------------------------

### Build a hierarchical model with HSSM

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/tutorial_bayeux.ipynb

Define a basic hierarchical model using the HSSM package. This example defines a 'ddm' model with trial-level covariates for 'v'.

```python
# 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",
        },
    ],
)
```

--------------------------------

### Perform Variational Inference (VI)

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/variational_inference.ipynb

Executes Variational Inference using the 'fullrank_advi' method for a specified number of iterations. It utilizes MCMC starting point defaults.

```python
vi_idata = cav_model.vi(niter=100000,
                        method="fullrank_advi")
```

--------------------------------

### Import necessary libraries

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/tutorial_bayeux.ipynb

Import the required libraries: ArviZ for plotting, Bayeux for sampling, JAX for numerical operations, and HSSM for model building.

```python
import arviz as az
import bayeux as bx
import jax
import hssm
```

--------------------------------

### Import Necessary Libraries for HSSM

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/rlssm_rlwm_model.ipynb

Imports core Python libraries for numerical operations, Bayesian inference, plotting, and HSSM-specific modules. Ensure these libraries are installed before running.

```python
import numpy as np
import arviz as az
import pickle
import matplotlib.pyplot as plt
import matplotlib.ticker as ticker
from functools import partial
from scipy.stats import spearmanr

# Import HSSM and simulator package
import hssm
from hssm.utils import decorate_atomic_simulator
from hssm.likelihoods.rldm import make_rldm_logp_op
from hssm.distribution_utils.dist import make_hssm_rv
from ssms.basic_simulators.simulator import simulator
```

--------------------------------

### Initialize ADVI Runner

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/variational_inference.ipynb

Initializes the ADVI runner for variational inference. This is the first step in setting up a VI analysis.

```python
with cav_model.pymc_model:
    advi = pm.ADVI()
```

--------------------------------

### Load Pre-trained RatioApproximator

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/bayesflow_lre_integration.ipynb

Loads a pre-trained BayesFlow RatioApproximator from disk if LOAD_PRETRAINED is True. Otherwise, it indicates that the in-memory approximator from training is being used.

```python
if LOAD_PRETRAINED:
    load_path = os.path.join(SAVE_DIR, PRE_TRAINED_NAME)
    ratio_approximator = keras.saving.load_model(load_path)
    print(f"Loaded from: {load_path}")
else:
    print("Using in-memory approximator from training above.")
```

--------------------------------

### Get Default Configuration for Weibull Model

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/hssm_tutorial_workshop_1.ipynb

Retrieves and displays the default configuration for the 'weibull' model, including its response variables, parameters, choices, and likelihood details with bounds.

```python
### Details about a particular model
hssm.defaults.default_model_config["weibull"]
##### the bounds within "likelihoods" provide reasonable parameter values (take this with a grain of salt)
```

--------------------------------

### Get Shape of Recovered Alpha Intercept

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/rlssm_rlwm_model.ipynb

Retrieves and prints the shape of the recovered 'alpha_Intercept' parameter from the MCMC inference data. This helps in understanding the dimensions of the posterior samples.

```python
idata_mcmc.posterior['alpha_Intercept'].values[0].shape
```

--------------------------------

### Load Data and Instantiate HSSM Model

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/save_load_tutorial.ipynb

Loads sample data and initializes a basic HSSM model with specified settings and a formula for the 'v' component.

```python
import hssm

cav_data = hssm.load_data("cavanagh_theta")

basic_hssm_model = hssm.HSSM(
    data=cav_data,
    process_initvals=True,
    link_settings="log_logit",
    model="angle",
    include=[
        {
            "name": "v",
            "formula": "v ~ 1 + C(stim)",
        }
    ],
)
```

--------------------------------

### Get Summary Statistics from Sampled Model

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/hssm_tutorial_workshop_2.ipynb

Generates a summary table of the sampled model parameters. Focus on mean, credible intervals (hdi_3%, hdi_97%), and convergence diagnostics (r_hat).

```python
az.summary(v_sex.traces, var_names=['v_sex','t','z','a'])
```

--------------------------------

### Import Modules and Configure Environment

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/hssm_tutorial_workshop_1.ipynb

Imports necessary libraries like arviz, jax, matplotlib, pytensor, and hssm. Configures PyTensor and JAX for specific settings and sets the matplotlib backend.

```python
# Import modules
import arviz as az
import jax
import matplotlib as plt
import pytensor

import hssm

pytensor.config.floatX = "float32"
jax.config.update("jax_enable_x64", False)

plt.use("Agg")
%matplotlib inline
%config InlineBackend.figure_format='retina'

# hssm.set_floatX("float32")
```

--------------------------------

### Initialize HSSM Model with Data and Model Type

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/scientific_workflow_hssm.ipynb

Initializes an HSSM model of type 'angle' using provided workshop data. This is a setup step for further analysis or model fitting.

```python
AngleHierModelV3 = hssm.HSSM(data = workshop_data,
                             model = "angle",

```

--------------------------------

### Plot Posterior Predictive Fit for Another Individual Subject

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/hssm_tutorial_workshop_2.ipynb

Visualizes the predicted posterior distribution against the observed data for a different specific participant. This example demonstrates a potentially poor fit.

```python
hssm.plotting.plot_predictive(
    v_sex, # the model which you have fit
    data = df[df.participant_id=='JK03'], # specifying a specific subject
    x_range=(-5,5) # the range on the x-axis, which is the response time
)
;
```

--------------------------------

### Load Pickle File with Simulation Data

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/rlssm_rlwm_model.ipynb

Loads simulation data from a pickle file. Ensure the 'pickle' library is imported. This snippet is used for initial data ingestion.

```python
import pickle

with open("../../tests/fixtures/rlwm_data.pickle", "rb") as f:
    datafile = pickle.load(f)
```

--------------------------------

### Sample from the Basic Model

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/choice_only_models.ipynb

Samples from the initialized HSSM model using the 'numpyro' sampler. Adjust 'chains', 'tune', and 'draws' for desired sampling precision. Note potential warnings regarding device availability and sampling diagnostics.

```python
idata_basic = model_basic.sample(
    sampler="numpyro",
    chains=2,
    tune=500,
    draws=500,
)
```

--------------------------------

### Define and Sample a PyMC Model with an ONNX-based Likelihood

Source: https://github.com/lnccbrown/hssm/blob/main/docs/tutorials/pymc.ipynb

This snippet demonstrates setting up a PyMC model using a custom distribution derived from an ONNX likelihood. It includes defining priors, linking the custom distribution, and performing sampling with NUTS.

```python
with pm.Model() as ddm_jax_model:
    v = pm.Uniform("v", lower=-3, upper=3)
    a = pm.Gamma("a", mu=0.5, sigma=1.0)
    z = pm.Uniform("z", lower=0.1, upper=0.9)
    t = pm.Uniform("t", lower=0.01, upper=1.0, initval=0.1)

    ddm = DDM_JAX("ddm", v=v, a=a, z=z, t=t, observed=dataset.values)

    ddm_jax_trace = pm.sample(mp_ctx="spawn", tune=500, draws=200)
```