or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-variational.mddata-io-utilities.mdgenerated-quantities.mdindex.mdinstallation-setup.mdmcmc-results.mdmodel-compilation.mdmodel-interface.mdoptimization-results.mdvariational-results.md
tile.json

tessl/pypi-cmdstanpy

Python interface to CmdStan that provides comprehensive access to the Stan compiler and all Bayesian inference algorithms.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/cmdstanpy@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-cmdstanpy@1.2.0

index.mddocs/

CmdStanPy

CmdStanPy is a lightweight pure-Python interface to CmdStan that provides comprehensive access to the Stan compiler and all Bayesian inference algorithms. It serves as a clean, minimal-dependency bridge between Python data science workflows and the powerful Stan probabilistic programming language, enabling users to compile Stan models and execute MCMC sampling, variational inference, and optimization algorithms.

Package Information

  • Package Name: cmdstanpy
  • Language: Python
  • Installation: pip install cmdstanpy
  • License: BSD-3-Clause
  • Documentation: https://mc-stan.org/cmdstanpy

Core Imports

import cmdstanpy

Common pattern for model-based inference:

from cmdstanpy import CmdStanModel

For working with existing fits from CSV files:

from cmdstanpy import from_csv

Basic Usage

import cmdstanpy as csp
from cmdstanpy import CmdStanModel
import numpy as np

# Set up CmdStan (one-time setup)
csp.install_cmdstan()  # Download and install CmdStan
csp.set_cmdstan_path("/path/to/cmdstan")  # Or set path if already installed

# Create a simple Stan model
stan_code = """
data {
  int<lower=0> N;
  vector[N] x;
  vector[N] y;
}
parameters {
  real alpha;
  real beta;
  real<lower=0> sigma;
}
model {
  y ~ normal(alpha + beta * x, sigma);
}
"""

# Write Stan code to file and compile
with open("linear_regression.stan", "w") as f:
    f.write(stan_code)

model = CmdStanModel(stan_file="linear_regression.stan")

# Generate some sample data
N = 100
x = np.random.normal(0, 1, N)
y = 2 + 3 * x + np.random.normal(0, 0.5, N)

data = {"N": N, "x": x, "y": y}

# Run MCMC sampling
fit = model.sample(data=data, chains=4, iter_sampling=1000, iter_warmup=1000)

# Access results
print(fit.summary())
print("Alpha mean:", fit.stan_variable("alpha").mean())
print("Beta mean:", fit.stan_variable("beta").mean())

# Save results
fit.save_csvfiles(dir="./results")

Architecture

CmdStanPy follows a clean separation between model compilation, inference execution, and results handling:

  • CmdStanModel: Encapsulates Stan program compilation and provides methods for different inference algorithms
  • Fit Objects: Specialized containers (CmdStanMCMC, CmdStanMLE, etc.) that provide access to inference results through multiple data formats
  • Utilities: Installation, configuration, and data formatting functions that handle the interface to CmdStan
  • CSV Interoperability: All results can be saved/loaded as Stan-format CSV files for reproducibility and external analysis

This design enables both interactive analysis and production workflows while maintaining compatibility with the broader Stan ecosystem.

Capabilities

Installation and Setup

Functions for installing, configuring, and managing the CmdStan installation that CmdStanPy depends on.

def install_cmdstan(version=None, dir=None, overwrite=False, compiler=False, progress=False, verbose=False, cores=1, interactive=False): ...
def set_cmdstan_path(path): ...
def cmdstan_path(): ...
def cmdstan_version(): ...
def set_make_env(make_env): ...
def rebuild_cmdstan(verbose=False, progress=True, cores=1): ...

Installation and Setup

Model Compilation

Functions for compiling and formatting Stan programs, with support for custom compiler options and automatic dependency management.

def compile_stan_file(src, force=False, stanc_options=None, cpp_options=None, user_header=None): ...
def format_stan_file(stan_file, overwrite_file=False, canonicalize=False, max_line_length=78, backup=True, stanc_options=None): ...

Model Compilation

Model Interface

The core CmdStanModel class that handles Stan program compilation and provides methods for all inference algorithms.

class CmdStanModel:
    def __init__(self, model_name=None, stan_file=None, exe_file=None, force_compile=False, stanc_options=None, cpp_options=None, user_header=None, compile=None): ...
    def sample(self, data=None, chains=4, parallel_chains=None, threads_per_chain=None, seed=None, inits=None, iter_warmup=1000, iter_sampling=1000, save_warmup=False, thin=1, max_treedepth=10, metric=None, step_size=None, adapt_engaged=True, adapt_delta=0.8, adapt_init_phase=15, adapt_metric_window=25, adapt_step_size=50, fixed_param=False, output_dir=None, sig_figs=None, validate_csv=True, show_console=False, refresh=None, time_fmt=None, timeout=None): ...
    def optimize(self, data=None, seed=None, inits=None, algorithm=None, iter=2000, jacobian=False, output_dir=None, sig_figs=None, show_console=False, refresh=None, time_fmt=None, timeout=None): ...
    def variational(self, data=None, seed=None, inits=None, algorithm=None, iter=10000, grad_samples=1, elbo_samples=100, eta=1.0, adapt_engaged=True, adapt_iter=50, tol_rel_obj=0.01, eval_elbo=100, draws=1000, output_dir=None, sig_figs=None, show_console=False, refresh=None, time_fmt=None, timeout=None): ...
    def pathfinder(self, data=None, seed=None, inits=None, num_paths=4, draws=1000, psis_resample=True, calculate_lp=True, max_lbfgs_iters=1000, num_draws=None, save_single_paths=False, output_dir=None, sig_figs=None, show_console=False, refresh=None, time_fmt=None, timeout=None): ...
    def laplace_sample(self, data=None, mode=None, draws=1000, jacobian=True, refresh=100, output_dir=None, sig_figs=None, show_console=False, time_fmt=None, timeout=None): ...
    def generate_quantities(self, data=None, previous_fit=None, seed=None, parallel_chains=None, output_dir=None, sig_figs=None, show_console=False, refresh=None, time_fmt=None, timeout=None): ...
    def log_prob(self, params, data=None, jacobian=True, sig_figs=None): ...

Model Interface

MCMC Sampling Results

Container for Markov Chain Monte Carlo sampling results with comprehensive diagnostics and multiple data access formats.

class CmdStanMCMC:
    def draws(self, inc_warmup=False, concat_chains=False): ...
    def draws_pd(self, vars=None, inc_warmup=False): ...
    def draws_xr(self, vars=None, inc_warmup=False): ...
    def stan_variable(self, var, inc_warmup=False): ...
    def stan_variables(self): ...
    def method_variables(self): ...
    def summary(self, percentiles=None, sig_figs=None): ...
    def diagnose(self): ...
    def save_csvfiles(self, dir=None): ...

MCMC Sampling Results

Optimization Results

Container for maximum likelihood and maximum a posteriori estimation results.

class CmdStanMLE:
    def optimized_params_np(self): ...
    def optimized_params_pd(self): ...
    def optimized_params_dict(self): ...
    def optimized_iterations_np(self): ...
    def optimized_iterations_pd(self): ...
    def stan_variable(self, var): ...
    def stan_variables(self): ...
    def save_csvfiles(self, dir=None): ...

Optimization Results

Variational Inference Results

Container for Automatic Differentiation Variational Inference (ADVI) results and approximate posterior samples.

class CmdStanVB:
    def variational_params_np(self): ...
    def variational_params_pd(self): ...
    def variational_params_dict(self): ...
    def variational_sample(self): ...
    def variational_sample_pd(self): ...
    def stan_variable(self, var): ...
    def stan_variables(self): ...
    def save_csvfiles(self, dir=None): ...

Variational Inference Results

Pathfinder and Laplace Results

Containers for advanced variational approximation methods including Pathfinder algorithm and Laplace approximation.

class CmdStanPathfinder:
    def draws(self): ...
    def stan_variable(self, var): ...
    def stan_variables(self): ...
    def method_variables(self): ...
    def create_inits(self, seed=None, chains=4): ...
    def save_csvfiles(self, dir=None): ...

class CmdStanLaplace:
    def draws(self): ...
    def draws_pd(self, vars=None): ...
    def draws_xr(self, vars=None): ...
    def stan_variable(self, var): ...
    def stan_variables(self): ...
    def method_variables(self): ...
    def save_csvfiles(self, dir=None): ...

Advanced Variational Methods

Generated Quantities

Container for generated quantities computed from existing fit results, enabling post-processing and derived quantity calculation.

class CmdStanGQ:
    def draws(self, concat_chains=True): ...
    def draws_pd(self, vars=None): ...
    def draws_xr(self, vars=None): ...
    def stan_variable(self, var): ...
    def stan_variables(self): ...
    def save_csvfiles(self, dir=None): ...

Generated Quantities

Data and I/O Utilities

Functions for data formatting, CSV file handling, and interoperability with the Stan ecosystem.

def write_stan_json(data, filename=None): ...
def from_csv(path=None, method=None): ...
def show_versions(output=True): ...

Data and I/O Utilities