CmdStanPy

1.3.0 · active · verified Thu Apr 09

CmdStanPy is the official Python interface to CmdStan, a command-line program for fitting statistical models written in Stan. It facilitates compiling Stan models, running MCMC, optimization, and variational inference, and processing the results. Currently at version 1.3.0, it follows a regular release cadence with minor updates every few months, and a major 2.0 release planned to remove existing deprecations.

Warnings

breaking CmdStanPy 2.0 (the next major non-bugfix release) is announced to remove all existing deprecations. Users should update their code to address current deprecation warnings before migrating to 2.0 to avoid breaking changes.
Fix: Consult CmdStanPy documentation for current deprecations (e.g., replace `output_basename` with `output_dir`) and update code accordingly.
gotcha CmdStanPy is a Python wrapper for the CmdStan C++ program. You must have CmdStan installed on your system. It can be manually installed and its path set via `cmdstanpy.set_cmdstan_path()`, or automatically downloaded and installed to your home directory (`~/.cmdstan`) using `cmdstanpy.install_cmdstan()`.
Fix: Before using CmdStanPy, either run `cmdstanpy.install_cmdstan()` once, or install CmdStan manually and set the `CMDSTAN_PATH` environment variable or call `cmdstanpy.set_cmdstan_path()`.
deprecated The `output_basename` argument in `sample()`, `optimize()`, `variational()`, `generate_quantities()`, and `pathfinder()` methods is deprecated and will be removed in CmdStanPy 2.0. Users should use the `output_dir` argument instead.
Fix: Replace `output_basename='my_output'` with `output_dir='path/to/output'` (which defaults to a temporary directory if not specified).
gotcha Versions of CmdStanPy prior to 1.2.4 could fail to load output files from CmdStan 2.35+ due to changes in CmdStan's output format.
Fix: Upgrade CmdStanPy to version 1.2.4 or newer to ensure compatibility with CmdStan 2.35 and later versions.

Install

pip install cmdstanpy Install CmdStanPy Python package

Imports

CmdStanModel
```
from cmdstanpy import CmdStanModel
```
install_cmdstan
```
from cmdstanpy import install_cmdstan
```
Used to automatically download and set up the CmdStan C++ library.
set_cmdstan_path
```
from cmdstanpy import set_cmdstan_path
```
Used to explicitly point CmdStanPy to an existing CmdStan installation.

Quickstart

This quickstart demonstrates how to define, compile, and fit a simple Bernoulli model using CmdStanPy. It includes essential steps to ensure the underlying CmdStan C++ program is available, either by setting its path or by automatically installing it. The example compiles a Stan file, provides data, runs MCMC sampling, and prints a summary of the results.

import os
import shutil
from cmdstanpy import CmdStanModel, install_cmdstan, set_cmdstan_path

# --- Step 1: Ensure CmdStan is installed and path is set ---
# This is crucial. If CMDSTAN_PATH environment variable is not set,
# CmdStanPy will attempt to download and install CmdStan to '~/.cmdstan'.
# You can also manually set the path via set_cmdstan_path().
try:
    set_cmdstan_path(os.environ.get('CMDSTAN_PATH', ''))
except ValueError:
    print("CmdStan path not explicitly set or found. Attempting automatic installation...")
    install_cmdstan()
    print(f"CmdStan installed to: {os.path.join(os.path.expanduser('~'), '.cmdstan')}")

# --- Step 2: Define a Stan model ---
stan_code = """
data {
  int<lower=0> N;
  array[N] int<lower=0,upper=1> y;
}
parameters {
  real<lower=0,upper=1> theta;
}
model {
  y ~ bernoulli(theta);
}
"""
stan_filepath = "bernoulli.stan"
with open(stan_filepath, "w") as f:
    f.write(stan_code)

try:
    # --- Step 3: Compile the Stan model ---
    # This creates an executable that CmdStanPy will call.
    model = CmdStanModel(stan_file=stan_filepath)
    print(f"Stan model compiled to: {model.exe_file}")

    # --- Step 4: Prepare data for the model ---
    data = {'N': 10, 'y': [0, 1, 0, 0, 0, 0, 0, 0, 0, 1]}

    # --- Step 5: Fit the model using MCMC sampling ---
    print("Starting MCMC sampling...")
    fit = model.sample(data=data, chains=2, iter_sampling=500, iter_warmup=500, seed=42)
    print("MCMC sampling complete.")

    # --- Step 6: Summarize and inspect results ---
    print("\nPosterior summary statistics:")
    print(fit.summary())

    # Access posterior draws as a pandas DataFrame
    # print("\nFirst 5 rows of posterior draws:")
    # print(fit.draws_pd().head())

except Exception as e:
    print(f"An error occurred during CmdStanPy execution: {e}")
finally:
    # --- Step 7: Clean up generated files ---
    if os.path.exists(stan_filepath):
        os.remove(stan_filepath)
    # CmdStan installation is usually kept, so no cleanup for it here.
    print("Cleanup complete.")

view raw JSON →