Compute a summary table of estimates and diagnostics — fit-method-summary • cmdstanr
Description: The $summary() method runs summarise_draws() from the posterior package and returns the output. For MCMC, only post-warmup draws are included in the summary. There is also a $print() method that prints the same summary stats but removes the extra formatting used for printing tibbles and returns the fitted model object itself. The $print() method may also be faster than $summary() because it is designed to only compute the summary statistics for the variables that will actually fit in the printed output whereas $summary() will compute them for all of the specified variables in order to be able to return them to the user. See Examples.

# Compute a summary table of estimates and diagnostics

Source: `R/fit.R`
`fit-method-summary.Rd`

The `$summary()` method runs `summarise_draws()` from the posterior package and returns the output. For MCMC, only post-warmup draws are included in the summary.

There is also a `$print()` method that prints the same summary stats but removes the extra formatting used for printing tibbles and returns the fitted model object itself. The `$print()` method may also be faster than `$summary()` because it is designed to only compute the summary statistics for the variables that will actually fit in the printed output whereas `$summary()` will compute them for all of the specified variables in order to be able to return them to the user. See Examples.

    summary(variables = NULL, ...)

## Arguments

variables

  (character vector) The variables to include.

...

  Optional arguments to pass to `posterior::summarise_draws()`.

## Value

The `$summary()` method returns the tibble data frame created by `posterior::summarise_draws()`.

The `$print()` method returns the fitted model object itself (invisibly), which is the standard behavior for print methods in R.

## See also

`CmdStanMCMC`, `CmdStanMLE`, `CmdStanVB`, `CmdStanGQ`

## Examples

    # \dontrun{
    fit <- cmdstanr_example("logistic")
    fit$summary()
    #> # A tibble: 105 × 10
    #>    variable      mean  median     sd    mad       q5      q95  rhat ess_bulk
    #>    <chr>        <num>   <num>  <num>  <num>    <num>    <num> <num>    <num>
    #>  1 lp__       -66.0   -65.7   1.45   1.26   -68.9    -64.3     1.00    1950.
    #>  2 alpha        0.380   0.376 0.218  0.214    0.0316   0.747   1.00    4585.
    #>  3 beta[1]     -0.669  -0.662 0.254  0.252   -1.09    -0.248   1.00    4669.
    #>  4 beta[2]     -0.277  -0.273 0.231  0.232   -0.665    0.0927  1.00    4400.
    #>  5 beta[3]      0.676   0.677 0.268  0.267    0.242    1.12    1.00    4179.
    #>  6 log_lik[1]  -0.515  -0.508 0.0986 0.0967  -0.686   -0.365   1.00    4439.
    #>  7 log_lik[2]  -0.405  -0.387 0.146  0.140   -0.676   -0.197   1.00    4528.
    #>  8 log_lik[3]  -0.501  -0.464 0.221  0.207   -0.917   -0.210   1.00    4266.
    #>  9 log_lik[4]  -0.450  -0.429 0.155  0.148   -0.729   -0.229   1.00    4175.
    #> 10 log_lik[5]  -1.18   -1.16  0.281  0.278   -1.67    -0.750   1.00    4417.
    #> # ℹ 95 more rows
    #> # ℹ 1 more variable: ess_tail <num>
    fit$print()
    #>    variable   mean median   sd  mad     q5    q95 rhat ess_bulk ess_tail
    #>  lp__       -66.00 -65.68 1.45 1.26 -68.86 -64.27 1.00     1950     2912
    #>  alpha        0.38   0.38 0.22 0.21   0.03   0.75 1.00     4584     2789
    #>  beta[1]     -0.67  -0.66 0.25 0.25  -1.09  -0.25 1.00     4669     3265
    #>  beta[2]     -0.28  -0.27 0.23 0.23  -0.67   0.09 1.00     4399     2567
    #>  beta[3]      0.68   0.68 0.27 0.27   0.24   1.12 1.00     4179     3160
    #>  log_lik[1]  -0.52  -0.51 0.10 0.10  -0.69  -0.37 1.00     4439     2680
    #>  log_lik[2]  -0.40  -0.39 0.15 0.14  -0.68  -0.20 1.00     4528     3426
    #>  log_lik[3]  -0.50  -0.46 0.22 0.21  -0.92  -0.21 1.00     4265     2821
    #>  log_lik[4]  -0.45  -0.43 0.15 0.15  -0.73  -0.23 1.00     4175     2970
    #>  log_lik[5]  -1.18  -1.16 0.28 0.28  -1.67  -0.75 1.00     4417     3002
    #>
    #>  # showing 10 of 105 rows (change via 'max_rows' argument or 'cmdstanr_max_rows' option)
    fit$print(max_rows = 2) # same as print(fit, max_rows = 2)
    #>  variable   mean median   sd  mad     q5    q95 rhat ess_bulk ess_tail
    #>     lp__  -66.00 -65.68 1.45 1.26 -68.86 -64.27 1.00     1950     2912
    #>     alpha   0.38   0.38 0.22 0.21   0.03   0.75 1.00     4584     2789
    #>
    #>  # showing 2 of 105 rows (change via 'max_rows' argument or 'cmdstanr_max_rows' option)

    # include only certain variables
    fit$summary("beta")
    #> # A tibble: 3 × 10
    #>   variable   mean median    sd   mad     q5     q95  rhat ess_bulk ess_tail
    #>   <chr>     <num>  <num> <num> <num>  <num>   <num> <num>    <num>    <num>
    #> 1 beta[1]  -0.669 -0.662 0.254 0.252 -1.09  -0.248   1.00    4669.    3265.
    #> 2 beta[2]  -0.277 -0.273 0.231 0.232 -0.665  0.0927  1.00    4400.    2568.
    #> 3 beta[3]   0.676  0.677 0.268 0.267  0.242  1.12    1.00    4179.    3161.
    fit$print(c("alpha", "beta[2]"))
    #>  variable  mean median   sd  mad    q5  q95 rhat ess_bulk ess_tail
    #>   alpha    0.38   0.38 0.22 0.21  0.03 0.75 1.00     4584     2789
    #>   beta[2] -0.28  -0.27 0.23 0.23 -0.67 0.09 1.00     4399     2567

    # include all variables but only certain summaries
    fit$summary(NULL, c("mean", "sd"))
    #> # A tibble: 105 × 3
    #>    variable      mean     sd
    #>    <chr>        <num>  <num>
    #>  1 lp__       -66.0   1.45
    #>  2 alpha        0.380 0.218
    #>  3 beta[1]     -0.669 0.254
    #>  4 beta[2]     -0.277 0.231
    #>  5 beta[3]      0.676 0.268
    #>  6 log_lik[1]  -0.515 0.0986
    #>  7 log_lik[2]  -0.405 0.146
    #>  8 log_lik[3]  -0.501 0.221
    #>  9 log_lik[4]  -0.450 0.155
    #> 10 log_lik[5]  -1.18  0.281
    #> # ℹ 95 more rows

    # can use functions created from formulas
    # for example, calculate Pr(beta > 0)
    fit$summary("beta", prob_gt_0 = ~ mean(. > 0))
    #> # A tibble: 3 × 2
    #>   variable prob_gt_0
    #>   <chr>        <num>
    #> 1 beta[1]     0.0035
    #> 2 beta[2]     0.112
    #> 3 beta[3]     0.995

    # can combine user-specified functions with
    # the default summary functions
    fit$summary(variables = c("alpha", "beta"),
      posterior::default_summary_measures()[1:4],
      quantiles = ~ quantile2(., probs = c(0.025, 0.975)),
      posterior::default_convergence_measures()
      )
    #> # A tibble: 4 × 10
    #>   variable   mean median    sd   mad    q2.5  q97.5  rhat ess_bulk ess_tail
    #>   <chr>     <num>  <num> <num> <num>   <num>  <num> <num>    <num>    <num>
    #> 1 alpha     0.380  0.376 0.218 0.214 -0.0392  0.823  1.00    4585.    2790.
    #> 2 beta[1]  -0.669 -0.662 0.254 0.252 -1.18   -0.180  1.00    4669.    3265.
    #> 3 beta[2]  -0.277 -0.273 0.231 0.232 -0.736   0.165  1.00    4400.    2568.
    #> 4 beta[3]   0.676  0.677 0.268 0.267  0.157   1.20   1.00    4179.    3161.

    # the functions need to calculate the appropriate
    # value for a matrix input
    fit$summary(variables = "alpha", dim)
    #> # A tibble: 1 × 3
    #>   variable dim.1 dim.2
    #>   <chr>    <num> <num>
    #> 1 alpha     1000     4

    # the usual [stats::var()] is therefore not directly suitable as it
    # will produce a covariance matrix unless the data is converted to a vector
    fit$print(c("alpha", "beta"), var2 = ~var(as.vector(.x)))
    #>  variable var2
    #>   alpha   0.05
    #>   beta[1] 0.06
    #>   beta[2] 0.05
    #>   beta[3] 0.07

    # }