PyStan

Warnings

• breaking PyStan 3 is a complete rewrite and introduces numerous backwards-incompatible changes from PyStan 2.x. Key API changes include `pystan.StanModel()` becoming `stan.build()`, `fit.sampling()` becoming `fit.sample()`, and `iter` parameter changing to `num_samples`.
  Fix: Consult the 'Upgrading to Newer Releases' section in the official documentation. Update import statements (`import stan`), function calls (`build`, `sample`), and parameter names (`num_samples`).
• breaking Microsoft Windows is no longer officially supported for PyStan 3.x installations. Users on Windows are advised to use Windows Subsystem for Linux 2 (WSL2) to run PyStan, or consider alternative Stan interfaces like CmdStanPy.
  Fix: Install and configure WSL2, then install PyStan within the Linux environment. Alternatively, use CmdStanPy or another Stan interface that supports Windows directly.
• breaking In PyStan 3.x, data and `random_seed` must be passed during the `stan.build()` step (compile time), not during the `fit.sample()` step (sampling time), unlike PyStan 2.x.
  Fix: Ensure that your data dictionary and `random_seed` argument are passed to `stan.build()` when initializing your model, e.g., `posterior = stan.build(model_code, data=my_data, random_seed=123)`.
• breaking PyStan 3.x significantly reduces its scope. Variational inference, maximization algorithms (e.g., LBFGS), and samplers other than the default HMC sampler are no longer supported. The `stansummary` display and `check_hmc_diagnostics` functions have also been removed.
  Fix: For these features, consider using alternative Stan interfaces (like CmdStanPy or RStan) or other probabilistic programming libraries (e.g., PyMC, JAX, PyTorch for VI/maximization). For diagnostics, use the ArviZ library.
• gotcha PyStan requires a C++ compiler to be available both during installation and at runtime for compiling Stan models. Lack of a properly configured compiler is a common cause of installation and runtime errors.
  Fix: Ensure you have a compatible C++ compiler installed (e.g., gcc >=9.0 or clang >=10.0 on Linux/macOS). On Debian-based systems, `apt-get install build-essential` often suffices. For Windows, WSL2 is the recommended approach.
• gotcha When running PyStan 3.x in Jupyter notebooks or other environments that manage their own `asyncio` event loops, `RuntimeError: asyncio.run() cannot be called from a running event loop` may occur.
  Fix: Install and use `nest-asyncio` by adding `import nest_asyncio; nest_asyncio.apply()` at the beginning of your notebook or script to allow nested event loops.

Install

• pip install pystan PyPI (requires C++ compiler)
• conda install pystan -c conda-forge Conda-forge (may include compiler)

Imports

• stan

  import stan

  PyStan 3 uses 'import stan' instead of 'import pystan' (used in v2.x) to align with other Stan interfaces.

Quickstart

This quickstart demonstrates how to define a Stan model, provide data, build the model, sample from the posterior distribution using HMC, and extract results for analysis. It uses the classic 'Eight Schools' hierarchical model. The `stan.build()` step compiles the model, which can take some time. `posterior.sample()` then runs the MCMC chains.

import stan
import numpy as np

schools_code = """
data {
  int<lower=0> J; // number of schools
  array[J] real y; // estimated treatment effects
  array[J] real<lower=0> sigma; // standard error of effect estimates
}
parameters {
  real mu; // population treatment effect
  real<lower=0> tau; // standard deviation in treatment effects
  vector[J] eta; // unscaled deviation from mu by school
}
transformed parameters {
  vector[J] theta = mu + tau * eta; // school treatment effects
}
model {
  target += normal_lpdf(eta | 0, 1); // prior log-density
  target += normal_lpdf(y | theta, sigma); // log-likelihood
}
"""

schools_data = {
    "J": 8,
    "y": [28, 8, -3, 7, -1, 1, 18, 12],
    "sigma": [15, 10, 16, 11, 9, 11, 10, 18],
}

# Build the model (compiles Stan code to C++ and then to executable)
posterior = stan.build(schools_code, data=schools_data, random_seed=1)

# Sample from the posterior distribution
fit = posterior.sample(num_chains=4, num_samples=1000)

# Extract samples for a parameter
mu_samples = fit["mu"]
print(f"Mean of mu samples: {np.mean(mu_samples)}")

# To get a pandas DataFrame (requires pandas installed):
# import pandas as pd
# df = fit.to_frame()
# print(df.head())