API reference

Global options

options() accepts cmdstanr_output_dir, cmdstanr_write_stan_file_dir, cmdstanr_force_recompile, cmdstanr_draws_format, cmdstanr_warn_inits, cmdstanr_verbose, cmdstanr_no_ver_check, cmdstanr_max_rows, cmdstanr_print_line_numbers, cmdstanr_compress, cmdstanr_progress_bar, cmdstanr_save_metric, cmdstanr_save_config, cmdstanr_spinner, mc.cores, and cmdstanphp_example_dir. A null value unsets an option. Unknown names and values of the wrong type throw. mc.cores sets the default parallel_chains and installer core count. cmdstanr_compress ('none', 'gzip', or 'bzip2') is the fitting methods’ default compress, cmdstanr_progress_bar is sample()’s default show_progress_bar, cmdstanr_save_metric is sample()’s default save_metric, and cmdstanr_save_config is the default save_cmdstan_config. cmdstanr_spinner is accepted and has no effect.

Data arrays use named PHP arrays at the top level and zero-indexed lists for Stan arrays, vectors, and matrices. Boolean values become 0/1. Matrices are rows of rows, with no R column-major conversion. Empty top-level data becomes {}. Missing values, strings, objects, nonfinite numbers, sparse indices, invalid variable names, and ragged arrays are rejected. The fitting methods write data with the model’s declarations, so every declared data variable is required, int variables are written as integers (a non-integer is truncated with a warning), a single value for a one-dimensional array becomes a one-element array, and a tuple is passed as a list of its elements. Complex numbers are [re, im] pairs. Errors name the variable.

Shared options

data, seed, refresh, init, output_dir, output_basename, sig_figs, opencl_ids, show_messages, show_exceptions, save_cmdstan_config, timeout. Every method except diagnose() and logProb() also takes compress.

init additionally accepts a fit object (see initial values). The CmdStanR names that CmdStanR 1.0 removed are unknown options here too: sample()’s cores, num_cores, num_chains, num_warmup, num_samples, max_depth, stepsize, save_extra_diagnostics, and validate_csv, and the jacobian_adjustment argument.

The thread option depends on the method: threads_per_chain for sample() and generateQuantities(), and threads for optimize(), variational(), pathfinder(), and laplace(). pathfinder() still accepts num_threads with an E_USER_DEPRECATED notice. Asking for more than one thread from an executable built without threading is an error. compress ('none', 'gzip', or 'bzip2'; default: the cmdstanr_compress option) compresses the output and latent-dynamics CSVs after the run. sig_figs is 1–18. opencl_ids contains platform/device IDs and requires an OpenCL build. output_basename contains only letters, numbers, dots, underscores, and hyphens. save_latent_dynamics, a sample() and variational() option, creates auxiliary diagnostic CSVs. save_cmdstan_config requests CmdStan configuration JSON beside the CSVs.

Method-specific options

• sample: threads_per_chain, save_latent_dynamics, show_progress_bar, chains (default 4), parallel_chains (default 1), chain_ids, iter_warmup, iter_sampling, save_warmup, thin, max_treedepth, adapt_engaged, adapt_delta, step_size, metric, metric_file, inv_metric, init_buffer, term_buffer, window, fixed_param, save_metric, diagnostics.
• optimize: threads, algorithm, jacobian, init_alpha, iter, tol_obj, tol_rel_obj, tol_grad, tol_rel_grad, tol_param, history_size, save_iterations.
• variational: threads, save_latent_dynamics, algorithm, iter, grad_samples, elbo_samples, eta, adapt_engaged, adapt_iter, tol_rel_obj, eval_elbo, draws (CmdStan’s output_samples).
• pathfinder: threads, init_alpha, tol_obj, tol_rel_obj, tol_grad, tol_rel_grad, tol_param, history_size, single_path_draws, draws, num_paths, max_lbfgs_iters, num_elbo_draws, save_single_paths, psis_resample, calculate_lp.
• laplace: threads, mode, opt_args, jacobian (default true), draws, calculate_lp.
• generate_quantities: required fittedParams is a fit, filename, or filename list; threads_per_chain; parallel_chains controls concurrency.
• diagnose: epsilon, error for finite-difference gradient checks.
• log_prob: exactly one of unconstrained_params, constrained_params, and optional jacobian.

sampleMpi(mpiCmd: 'mpiexec', mpiArgs: [], ...options) accepts sampling options, defaults to one chain, and executes chains sequentially. An associative MPI argument such as ['n' => 4] becomes -n 4; a list is passed as a literal argument vector. Compile with ['STAN_MPI' => true, 'CXX' => 'mpicxx', 'TBB_CXX_TYPE' => 'gcc'] and install an MPI runtime. MPI launch construction is unit-tested; a real MPI cluster run is not validated here.

Model methods

These methods need PHP FFI. The first call compiles a shared library for the fit’s model and data; initModelMethods(data: null, seed: 1, verbose: false, quiet: false, model: null) does this explicitly. data binds other data, such as the data of a fit reloaded after its data file is gone, and dataFile() then points to it. Imported CSV fits must pass model:. A model from exeFile alone has no Stan program to build them from.

• logProb(unconstrainedVariables, jacobian: true): log density with constants dropped.
• gradLogProb(...): ['log_prob' => float, 'gradient' => list].
• hessian(...): ['log_prob' => float, 'grad_log_prob' => list, 'hessian' => rows].
• unconstrainVariables(variables): a flat unconstrained list from parameter values keyed by name, structured as constrainVariables() returns them.
• unconstrainDraws(files: null, draws: null, format: null, incWarmup: false): the fit’s draws, another set of CSV files, or draws_df rows, in unconstrained space.
• constrainVariables(unconstrainedVariables, transformedParameters: true, generatedQuantities: true): variables keyed by name as nested arrays, with tuples as lists of their elements and complex values as [re, im].
• exposeFunctions(timeout: null) / functions(): the model’s user-defined functions.

CmdStan\ModelMethods and CmdStan\StanFunctions can also be used directly with a Stan file.

Method-specific fit methods

CmdStanMCMC adds loo(variables: 'log_lik', rEff: false, momentMatch: false, maxIters: 30, kThreshold: null, split: true, cov: true) and waic(variables: 'log_lik'). Both return estimates (each with Estimate and SE), pointwise rows, and flat keys such as elpd_loo and se_elpd_loo. rEff: false, CmdStanR 1.0’s default, skips the relative efficiencies; rEff: true computes them. LOO also returns diagnostics with Pareto k values. momentMatch: true needs model methods and the phit posterior-draw kernels, and adds a moment_match key; see moment matching.

CmdStanMLE adds mle()/optimizedParams() (the estimates by variable, without lp__) and lp(); its summary() returns variable/estimate rows, matching CmdStanR’s optimization summary. CmdStanVB adds variationalMean() and lpApprox(), the approximation’s log density at each draw as one list in draw order. Pathfinder and Laplace also expose lpApprox(); Laplace exposes mode(), and generated quantities fits expose fittedParamsFiles(). CmdStanPathfinder adds singlePathFiles(), singlePathJsonFiles(), singlePathFits(), and singlePathDiagnostics() for runs with save_single_paths: true, and lists lp_approx__ and path__ among its variables. CmdStanDiagnose adds gradients() (gradient-check console output).

Statistics helpers

CmdStan\Figure renders computed figures with ascii(), vegaLite(), json(), html(), svg(), and png(); casting a figure to a string gives its ASCII form. CmdStan\Plot computes the figures, plus bandwidth(), density(), autocorrelation(), and ranks() for the values they draw. CmdStan\Psis (paretoSmooth(), paretoKhat(), psis(), gpdfit()), CmdStan\Loo (loo(), waic(), relativeEff()), CmdStan\MomentMatch (loo() on unconstrained draws with log-density and log-likelihood callbacks, fromFit()), CmdStan\DrawKernels (detection of and wrappers for the phit draw kernels), CmdStan\Summary (summarise() and each posterior measure), CmdStan\Rvars, and CmdStan\Inits (fromFit(), fromDraws(), nest(), validate()) operate on plain draws arrays. Their docblocks describe the input and output shapes.

Data in

Every data argument (sample(), sampleMpi(), optimize(), variational(), pathfinder(), laplace(), generateQuantities(), diagnose(), and logProb()) and write_stan_json() accept a plain array, a JSON file, a CmdStan\StanData, or a table. A table is any object with toModelData() or toColumns(), such as a phibble Phibble\DataFrame. toModelData() is used when both exist. StanData::fromTable($table, addN: true) performs the same conversion and keeps the factor labels.

Factor levels come from a toModelData() descriptor (['levels' => list<string>, 'codes' => list<?int>, 'ordered' => bool], with 0-based codes, as phibble’s DataFrame::toModelData() returns them from phibble 0.1.0; add 'base' => 1 for 1-based codes) or, for a toColumns() table, from levels($name) when types() reports a factor. The ordered flag is ignored. Labels cannot be written to Stan JSON, so they are returned in StanData::$levels, keyed by data variable, where label i has index i + 1. The conversion adds N, the row count, unless the table has a column named N, and adds J_<name> unless a column already has that name. CmdStan ignores data variables that the program does not declare. Column names must be valid Stan identifiers.

Fit methods are camelCase, as are StanData‘s and Tables’ from...() constructors and the package’s other static helpers, such as CmdStanFit::fromCsv() and Inits::fromFit(). StanData is a value object with readonly data, levels, columns (the names of the columns of X), and meta. toArray() returns data, and with(['prior_scale' => 2.5]) adds or replaces variables.

Regression data

StanData::fromColumns($columns, y: 'y', x: ['x1', 'x2'], groups: 'school', intercept: false) builds the usual hierarchical regression data block from named columns or a table:

Groups are numbered over sorted unique values (numbers numerically, otherwise in strcmp order) or over a factor’s levels, and the labels are in levels['<g>_id']. Predictors must be numeric. intercept: true prepends a column of ones named (Intercept). It is off by default because Stan programs usually give the intercept its own parameter.

$data = CmdStan\StanData::fromColumns($df, 'score', ['hours'], 'school');
$fit = $model->sample(data: $data, seed: 1);

data {
  int<lower=0> N;
  int<lower=0> K;
  matrix[N, K] X;
  vector[N] y;
  int<lower=1> J;
  array[N] int<lower=1, upper=J> school_id;
}

StanData::fromFormula('y ~ x1 + f + (1 + x1 | g)', $data, dropIntercept: false, missing: 'drop') builds regression data from an R-style formula through Phit\model_matrix() in the phit extension (phit 0.1.0 and later). The function handles factor predictors (treatment contrasts), interactions, transforms, and offsets, and keeps the (Intercept) column in X unless dropIntercept: true. $data can be columns, factor descriptors, or a table, whose toModelData() is passed unchanged. Without the function, fromFormula() throws a RuntimeException that names the requirement. StanData::fromModelMatrix($result) maps an existing Phit\model_matrix() result and is the only code that depends on its shape.

Group names that are not Stan identifiers have other characters replaced by _, so the nested group g2:g1 gives g2_g1_id. Groups are numbered in factor level order when the data has descriptors or table factors, and otherwise over sorted labels (numbers numerically, otherwise byte order, as Phit\model_matrix() sorts levels). Terms on the same group are concatenated into one Z_<g>, intercept-only terms included, so (1 | g) + (0 + x | g) gives the same Z_g as (1 + x | g). Two groups whose names map to the same <g>, such as a.b and a_b, are rejected. Factors reach Phit\model_matrix() as descriptors in the data’s level order, so the first level is the reference level and a factor response is coded in that order, while plain string columns use sorted levels. missing: 'drop' removes rows with missing values in any variable the formula uses, with one E_WARNING from Phit\model_matrix(), and missing: 'raise' rejects them. The remaining result keys, including retained_rows, dropped_rows, n_input, n_dropped, terms, and assign, are kept in meta, and meta['random'][<g>] lists each group’s columns and terms.

data {
  int<lower=0> N;
  int<lower=1> K;
  matrix[N, K] X;          // includes the intercept column
  vector[N] y;
  int<lower=1> J;
  array[N] int<lower=1, upper=J> g_id;
  int<lower=1> Q_g;
  matrix[N, Q_g] Z_g;      // (1 + x1 | g)
}

Draws and summaries out

• drawsColumns(variables: null, incWarmup: false) returns draws as columns, like posterior’s as_draws_df(): one list per variable element (such as beta[2]), then one-based .chain, .iteration, and .draw columns.
• summaryColumns(variables: null, probs: [0.05, 0.95], measures: []) returns summary() as columns: variable and one column per measure.
• drawsTable() and summaryTable() take the same arguments and return a Phibble\DataFrame built with DataFrame::fromColumns(). They need phpstats/phibble, which requires PHP 8.3 or later, and throw a RuntimeException explaining this when it is not installed.
• CmdStan\Tables::fromRows($rows) converts any list of associative rows, such as loo()['pointwise'], to columns.

The column arrays need no other package and suit any data frame library that accepts name-to-values columns.

Part of the phpstats family

CmdStanPHP is part of the phpstats family of PHP statistics packages:

• phit: the phit native extension (Phit\ functions), which provides the moment-matching draw kernels and, when available, Phit\model_matrix().
• phibble: data frames (Phibble\DataFrame).
• phplyr: dplyr-style verbs for phibble tables.
• phiz: a Vega-Lite grammar of graphics.

CmdStanPHP requires none of them. phibble, phplyr, and phiz require PHP 8.3 or later, and the phit extension supports PHP 8.3, 8.4, and 8.5.