CmdStanPHP

Data & Workflow

Statistics, Modeling, & Visualization

Fits

On this page
Examples

Every fitting method returns a fit: CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanLaplace, CmdStanPathfinder, CmdStanGQ, or CmdStanDiagnose, all extending CmdStanFit. Methods are camelCase versions of CmdStanR’s.

A fit reads its CSV metadata and checks every row when it is created, then reads only the columns that draws(), summary(), and the diagnostics use. Each read of new columns passes over the files again, so request variables together. Until materialize(), the fit needs its CSV files.

Draws and summaries

draws()

$fit->draws(    array|string|null $variables = null,    ?string $format = null,    bool $incWarmup = false,): array
Format Shape
draws_array [iteration][chain][variable => value]. Default for MCMC and generated quantities fits. Chains must have equal lengths.
draws_matrix [draw][variable => value], chain after chain. Default for other fits.
draws_df draws_matrix rows plus one-based .chain, .iteration, and .draw
draws_list [chain][variable => list of values], in the requested variable order
draws_rvars [base name => ['dims', 'nchains', 'ndraws', 'draws']]

A base name such as beta selects every element, and null selects every variable except sampler columns ending in __. Unknown names throw. A null format uses the cmdstanr_draws_format option, else the default above. Warmup draws need save_warmup: true and incWarmup: true. Draws, summaries, and saving fits gives examples.

samplerDiagnostics()

$fit->samplerDiagnostics(    ?string $format = null,    bool $incWarmup = false,): array

The columns ending in __ other than lp__, in the same formats as draws().

summary()

$fit->summary(    array|string|null $variables = null,    array $probs = [0.05, 0.95],    array $measures = [],): array

Without measures, returns mean, median, sd, mad, the quantiles named after probs (q5 and q95 by default), rhat, ess_bulk, ess_tail, and mcse_mean. CmdStan’s stansummary computes rhat, ess_bulk, and mcse_mean, and ess_tail is computed in PHP. With measures, the summary follows posterior’s summarise_draws() and is computed in PHP: named measures, the groups default_summary_measures, default_convergence_measures, and default_mcse_measures, or callables with string keys. Convergence columns are NAN for fits other than MCMC and for chains with fewer than four draws. Summaries lists the measures.

drawsColumns(), summaryColumns()

$fit->drawsColumns(    array|string|null $variables = null,    bool $incWarmup = false,): array$fit->summaryColumns(    array|string|null $variables = null,    array $probs = [0.05, 0.95],    array $measures = [],): array

drawsColumns() returns one list per variable element, such as beta[2], then one-based .chain, .iteration, and .draw columns, like posterior’s as_draws_df(). summaryColumns() returns variable and one column per measure. Neither needs another package.

drawsTable(), summaryTable()

$fit->drawsTable(    array|string|null $variables = null,    bool $incWarmup = false,): object$fit->summaryTable(    array|string|null $variables = null,    array $probs = [0.05, 0.95],    array $measures = [],): object

The column arrays above as a Phibble\DataFrame. Needs phpstats/phibble, which requires PHP 8.3 or later, and throws a RuntimeException when it is not installed.

print()

$fit->print(    array|string|null $variables = null,    ?int $maxRows = null,): void

Prints at most maxRows variables, by default the cmdstanr_max_rows option, else 10.

lp()

$fit->lp(): array|float

Returns [iteration][chain] values of lp__. Optimization and diagnose fits return one float: see CmdStanMLE::lp() and CmdStanDiagnose::lp().

cmdstanSummary()

$fit->cmdstanSummary(): string

Returns stansummary’s text for the output files. Compressed files are decompressed to temporary copies first.

Diagnostics and run information

diagnosticSummary()

$fit->diagnosticSummary(): array

Returns num_divergent, num_max_treedepth, and ebfmi, each with one value per chain.

checkDiagnostics(), diagnosticWarnings()

$fit->checkDiagnostics(    array $checks = ['divergences', 'treedepth', 'ebfmi'],): array$fit->diagnosticWarnings(): array

checkDiagnostics() runs the named checks (divergences, treedepth, and ebfmi) and returns their messages. diagnosticWarnings() returns the messages from the checks run when the fit was created. Messages are returned, not raised as PHP warnings.

cmdstanDiagnose()

$fit->cmdstanDiagnose(): string

Returns the text of CmdStan’s bin/diagnose for the output files.

metadata(), chainMetadata()

$fit->metadata(): array$fit->chainMetadata(): array

metadata() returns the first chain’s metadata with id, seed, init, step_size, step_size_adaptation, and fitted_params collected across chains (seed is a scalar when shared), time as per-chain rows, and missing keys filled from the configuration JSON. chainMetadata() returns each chain’s metadata, including CmdStan’s raw argument keys.

variables()

$fit->variables(): array

Returns the column names, in CSV order.

numChains(), numDrawsSampling(), numDrawsWarmup(), numProcs()

$fit->numChains(): int$fit->numDrawsSampling(): int$fit->numDrawsWarmup(): int$fit->numProcs(): int

numDrawsWarmup() is 0 unless warmup was saved. numProcs() counts CmdStan processes, one per output file.

stepSize(), invMetric(), metric()

$fit->stepSize(): array$fit->invMetric(bool $matrix = true): array$fit->metric(): array

stepSize() returns one step size per chain. invMetric() returns each chain’s inverse metric, from save_metric JSON when every chain has it, else from the CSV comments. With matrix: true, CmdStanR’s default, diagonal metrics are expanded to matrices. metric() returns the decoded save_metric JSON (stepsize, metric_type, and inv_metric) per chain.

cmdstanConfig()

$fit->cmdstanConfig(): array

Returns the decoded save_cmdstan_config JSON, one array per process.

time()

$fit->time(): array

Returns rows with chain, warmup, sampling, and total in seconds. total is the process’s elapsed time, null for imported fits.

init()

$fit->init(): array

Read from the init files named in the metadata.

output(), returnCodes(), command()

$fit->output(): array$fit->returnCodes(): array$fit->command(): array

Imported fits have none of these. command() returns shell-quoted command lines and leaves out STAN_NUM_THREADS and an MPI launcher.

code()

$fit->code(): string

Throws a RuntimeException for fits imported from CSV files.

profiles()

$fit->profiles(): array

Returns one list of rows per profile CSV file, with numeric values as floats.

Files and saving

outputFiles(), latentDynamicsFiles(), profileFiles()

$fit->outputFiles(bool $includeFailed = false): array$fit->latentDynamicsFiles(bool $includeFailed = false): array$fit->profileFiles(bool $includeFailed = false): array

The latent-dynamics and profile accessors throw when there are no such files. includeFailed is accepted for CmdStanR compatibility and adds nothing, because a failing process throws.

dataFile(), configFiles(), metricFiles()

$fit->dataFile(): ?string$fit->configFiles(bool $includeFailed = false): array$fit->metricFiles(bool $includeFailed = false): array

An imported fit uses the data file recorded in the CSV header when it still exists.

saveOutputFiles(), saveLatentDynamicsFiles(), saveProfileFiles(), saveDataFile(), saveConfigFiles(), saveMetricFiles()

$fit->saveOutputFiles(    string $dir = '.',    ?string $basename = null,    bool $timestamp = true,    bool $random = true,    ?string $compress = null,): array$fit->saveLatentDynamicsFiles(    string $dir = '.',    ?string $basename = null,    bool $timestamp = true,    bool $random = true,    ?string $compress = null,): array$fit->saveProfileFiles(    string $dir = '.',    ?string $basename = null,    bool $timestamp = true,    bool $random = true,): array$fit->saveDataFile(    string $dir = '.',    ?string $basename = null,    bool $timestamp = true,    bool $random = true,): ?string$fit->saveConfigFiles(    string $dir = '.',    ?string $basename = null,    bool $timestamp = true,    bool $random = true,): array$fit->saveMetricFiles(    string $dir = '.',    ?string $basename = null,    bool $timestamp = true,    bool $random = true,): array

Returns the saved paths and points the fit at them. Files are named <basename>[-<YYYYmmddHHMM>][-<id>][-<hex>], where basename defaults to the model name, timestamp adds the date, and random adds the suffix. Files the run created are moved. Imported CSV files and the data file are copied. An existing destination throws. compress recompresses output and latent-dynamics files.

materialize()

$fit->materialize(): static

Returns the fit. Afterwards it no longer needs its files.

saveObject()

$fit->saveObject(string $file): string

Materializes the fit, computes MCMC summary statistics, and writes serialize($fit). Returns the file path. Read it with unserialize(file_get_contents($file)), and unserialize only files you trust. Running generated quantities from a restored fit still needs its CSV files.

Model methods

These need PHP’s FFI extension. The first call compiles a shared library for the fit’s model and data. A model from exeFile alone has no program to build them from. Log density and model methods gives examples. ModelMethods and StanFunctions can also be used directly with a Stan file: see Helper classes.

initModelMethods()

$fit->initModelMethods(    object|array|string|null $data = null,    int $seed = 1,    bool $verbose = false,    bool $quiet = false,    ?CmdStanModel $model = null,): void

Compiles (or reuses) a shared library for the model and binds it to data, by default the fit’s data. The first model-method call does this implicitly. Pass data when a reloaded fit’s data file is gone, and dataFile() then points to it. Imported CSV fits must pass model.

logProb()

$fit->logProb(    array $unconstrainedVariables,    bool $jacobian = true,): float

Constants are dropped. jacobian: false leaves out the Jacobian adjustment.

gradLogProb()

$fit->gradLogProb(    array $unconstrainedVariables,    bool $jacobian = true,): array

Returns ['log_prob' => float, 'gradient' => list].

hessian()

$fit->hessian(    array $unconstrainedVariables,    bool $jacobian = true,): array

Returns ['log_prob' => float, 'grad_log_prob' => list, 'hessian' => rows]. The Hessian uses finite differences of autodiff gradients, as in CmdStanR.

unconstrainVariables()

$fit->unconstrainVariables(array $variables): array

variables is keyed by parameter name and shaped as constrainVariables() returns them. Returns a flat list.

unconstrainDraws()

$fit->unconstrainDraws(    ?array $files = null,    ?array $draws = null,    ?string $format = null,    bool $incWarmup = false,): array

Unconstrains the fit’s draws, the draws in other CmdStan CSV files, or draws_df or draws_matrix rows given as draws, in a draws format.

constrainVariables()

$fit->constrainVariables(    array $unconstrainedVariables,    bool $transformedParameters = true,    bool $generatedQuantities = true,): array

Returns variables keyed by name as nested arrays, with tuples as lists and complex values as [re, im]. Transformed parameters and generated quantities are included unless turned off.

exposeFunctions(), functions()

$fit->exposeFunctions(?float $timeout = null): StanFunctions$fit->functions(): StanFunctions

As CmdStanModel::exposeFunctions() for the model that produced the fit.

Methods of specific fit types

loo()

$fit->loo(    string $variables = 'log_lik',    array|float|bool|null $rEff = false,    bool $momentMatch = false,    int $maxIters = 30,    ?float $kThreshold = null,    bool $split = true,    bool $cov = true,): array

CmdStanMCMC only. Uses the log_lik variable by default. rEff: true computes relative efficiencies as CmdStanR does. momentMatch: true needs the phit extension and model methods, and maxIters, kThreshold, split, and cov are loo_moment_match()’s options. LOO and WAIC describes the result.

waic()

$fit->waic(string $variables = 'log_lik'): array

CmdStanMCMC only. Uses the log_lik variable by default. Adds a message to warnings when any pointwise p_waic exceeds 0.4.

mle(), optimizedParams()

$fit->mle(): array$fit->optimizedParams(): array

CmdStanMLE only. Returns the estimates keyed by variable name. summary() on this fit returns variable and estimate rows and rejects measures.

lp()

$fit->lp(): float

CmdStanMLE only. The log density at the optimum, NAN when missing.

variationalMean()

$fit->variationalMean(): array

CmdStanVB only. Returns values keyed by variable name.

lpApprox()

$fit->lpApprox(): array

CmdStanVB, CmdStanLaplace, and CmdStanPathfinder. The approximation’s log density at each draw, as one list in draw order.

mode()

$fit->mode(): array

CmdStanLaplace only. Returns values keyed by variable name.

singlePathFiles(), singlePathJsonFiles(), singlePathFits(), singlePathDiagnostics()

$fit->singlePathFiles(): array$fit->singlePathJsonFiles(): array$fit->singlePathFits(): array$fit->singlePathDiagnostics(): array

CmdStanPathfinder only. Available with save_single_paths: true. The files are CmdStan’s <output>_path_<n>.csv and .json, in path order. singlePathFits() returns one CmdStanPathfinder per path, and singlePathDiagnostics() the decoded JSON. The fit’s variables include lp_approx__ and path__.

fittedParamsFiles()

$fit->fittedParamsFiles(): array

CmdStanGQ only. The files generated quantities ran on.

gradients()

$fit->gradients(): string

CmdStanDiagnose only. The console output of CmdStan’s diagnose method.

lp()

$fit->lp(): float

CmdStanDiagnose only. The log density at the checked point.

Reading CSV files

Static methods of CmdStanFit.

CmdStanFit::fromCsv()

CmdStanFit::fromCsv(    array $files,    ?array $variables = null,    bool $checkDiagnostics = true,    ?string $format = null,): self

The static form of as_cmdstan_fit(). Returns the fit class for the files’ method.

CmdStanFit::readCmdStanCsv()

CmdStanFit::readCmdStanCsv(    array $files,    array|string|null $variables = null,    array|string|null $samplerDiagnostics = null,    ?string $format = null,): array

The static form of read_cmdstan_csv_list().

CmdStanFit::classForMethod()

CmdStanFit::classForMethod(string $method): string

The fit class name for a CmdStan method name, such as CmdStanMCMC for sample.

CmdStanFit::quantile()

CmdStanFit::quantile(array $values, float $p): float

The p quantile of values with R’s type 7 rule. NAN for an empty list.

Statistics helpers

Figure, Plot, Psis, Loo, MomentMatch, DrawKernels, Summary, Rvars, Inits, ModelMethods, and StanFunctions are on Helper classes.