Skip to contents

MCMC fit object

Source: R/MCMC_Fit.R
MCMC_Fit.Rd

MCMC fit object

MCMC fit object

Details

An R6 class storing posterior samples and related information from MCMC estimation.

Bayes factors are computed as ratios of marginal likelihoods estimated by bridge sampling. The comparison model can be constructed by fixing parameters with `fixed = list(...)`, or supplied as an already fitted `MCMC_Fit` object via `comparison_fit`. Bayes factors are computed only by marginal-likelihood model comparison.

Super class

BayesRTMB::RTMB_Fit_Base -> mcmc_fit

Public fields

model

An `RTMB_Model` object used for estimation.

fit

Posterior draws for model parameters.

random_fit

Posterior draws for random effects.

transform_fit

Posterior draws for transformed parameters.

transform_dims

Dimension information for transformed parameters.

generate_fit

Posterior draws for generated quantities.

generate_dims

Dimension information for generated quantities.

eps

Step size used by the sampler.

accept

Acceptance statistics from sampling.

treedepth

Tree depth used in HMC/NUTS sampling.

n_leapfrog

Number of leapfrog steps for retained draws.

divergent

Logical matrix indicating divergent transitions.

energy

Hamiltonian energy for retained draws.

metric

Per-chain inverse mass matrix used by NUTS.

metric_type

Effective mass matrix adaptation type used by NUTS.

metric_requested

Mass matrix adaptation type requested by the user.

metric_effective

Effective mass matrix adaptation type by chain.

metric_auto

Automatic metric selection details by chain, if used.

metric_init

Initial metric source used by NUTS.

metric_adaptation

Metric learning mode used during warmup.

nuts_variant

NUTS proposal selection variant used for sampling.

warmup_diagnostics

Per-chain warmup diagnostics.

laplace

Logical; whether Laplace approximation was used.

posterior_mean

Posterior mean estimates.

log_ml

Numeric value storing the calculated log marginal likelihood from bridge sampling.

comparison_fit

An MCMC_Fit object containing the fitted comparison model.

max_treedepth

Maximum tree depth requested for NUTS/HMC.

pd_error_count

Positive-definite/singularity errors treated as lp = -Inf by chain.

Methods

Public methods

Inherited methods

Method get_point_estimate()

Get point estimate for a target parameter.

Usage

MCMC_Fit$get_point_estimate(target, chains = NULL, best_chains = NULL)

Arguments

target

Target parameter name.

chains

Numeric vector of chains to include. If NULL, all chains are used.

best_chains

Integer; number of best chains to retain based on mean log-posterior.

Returns

Matrix, array, vector, or scalar point estimate.

Method new()

Create a new `MCMC_Fit` object.

Usage

MCMC_Fit$new(
  model,
  fit,
  random_fit,
  eps,
  accept,
  treedepth,
  laplace,
  posterior_mean,
  max_treedepth = NULL,
  pd_error_count = NULL,
  n_leapfrog = NULL,
  divergent = NULL,
  energy = NULL,
  metric = NULL,
  metric_type = NULL,
  metric_init = NULL,
  metric_requested = NULL,
  metric_effective = NULL,
  metric_auto = NULL,
  metric_adaptation = NULL,
  nuts_variant = NULL,
  warmup_diagnostics = NULL
)

Arguments

model

An `RTMB_Model` object used for estimation.

fit

Posterior draws for model parameters.

random_fit

Posterior draws for random effects, if available.

eps

Step size used by the sampler.

accept

Acceptance statistics from sampling.

treedepth

Tree depth used in HMC/NUTS sampling.

laplace

Logical; whether Laplace approximation was used.

posterior_mean

Posterior mean estimates.

max_treedepth

Maximum tree depth requested for NUTS/HMC.

pd_error_count

Positive-definite/singularity errors treated as `lp = -Inf` by chain.

n_leapfrog

Number of leapfrog steps for retained draws.

divergent

Logical matrix indicating divergent transitions.

energy

Hamiltonian energy for retained draws.

metric

Per-chain inverse mass matrix used by NUTS.

metric_type

Effective mass matrix adaptation type used by NUTS.

metric_init

Initial metric source used by NUTS.

metric_requested

Mass matrix adaptation type requested by the user.

metric_effective

Effective mass matrix adaptation type by chain.

metric_auto

Automatic metric selection details by chain, if used.

metric_adaptation

Metric learning mode used during warmup.

nuts_variant

NUTS proposal selection variant used for sampling.

warmup_diagnostics

Per-chain warmup diagnostics.

Method print()

Print a brief summary of the fitted object.

Usage

MCMC_Fit$print(...)

Arguments

...

Additional arguments.

Returns

The object itself, invisibly.

Method draws()

Extract posterior draws for selected parameters.

Usage

MCMC_Fit$draws(
  pars = NULL,
  chains = NULL,
  best_chains = NULL,
  inc_random = FALSE,
  inc_transform = TRUE,
  inc_generate = TRUE
)

Arguments

pars

Character or numeric vector specifying the names or indices of parameters to extract. If NULL, all available parameters are extracted.

chains

Numeric vector specifying the chains to extract. If NULL, draws from all chains are returned.

best_chains

Integer; number of best chains to retain based on mean log-posterior (lp).

inc_random

Logical; whether to include random effects in the output. Default is FALSE.

inc_transform

Logical; whether to include transformed parameters in the output. Default is TRUE.

inc_generate

Logical; whether to include generated quantities in the output. Default is TRUE.

Returns

Posterior draws.

Method summary()

Summarize posterior draws.

Usage

MCMC_Fit$summary(
  pars = NULL,
  chains = NULL,
  best_chains = NULL,
  max_rows = 10,
  digits = 2,
  inc_random = FALSE,
  inc_transform = TRUE,
  inc_generate = TRUE
)

Arguments

pars

Character or numeric vector specifying the names or indices of parameters to summarize. If NULL, all available parameters are summarized.

chains

Numeric vector specifying the chains to extract. If NULL, draws from all chains are used.

best_chains

Integer; number of best chains to retain based on mean log-posterior (lp).

max_rows

Integer; maximum number of rows to print in the summary table. Default is 10.

digits

Integer; number of decimal places to print. Default is 2.

inc_random

Logical; whether to include random effects in the summary. Default is FALSE.

inc_transform

Logical; whether to include transformed parameters in the summary. Default is TRUE.

inc_generate

Logical; whether to include generated quantities in the summary. Default is TRUE.

Returns

A summary object.

Method rhat_summary()

Summarize R-hat values.

Usage

MCMC_Fit$rhat_summary(
  pars = NULL,
  chains = NULL,
  best_chains = NULL,
  inc_random = FALSE,
  inc_transform = TRUE,
  inc_generate = FALSE,
  finite = TRUE,
  ...
)

Arguments

pars

Character or numeric vector specifying parameters to include.

chains

Numeric vector specifying chains to include.

best_chains

Integer; number of best chains to retain based on mean log-posterior.

inc_random

Logical; whether to include random effects. Default is FALSE.

inc_transform

Logical; whether to include transformed parameters. Default is TRUE.

inc_generate

Logical; whether to include generated quantities. Default is FALSE.

finite

Logical; whether to drop non-finite or missing R-hat values. Default is TRUE.

...

Additional arguments.

Returns

A numeric vector of R-hat values with class "rhat_summary".

Method unconstrain_draws()

Transform posterior draws to the unconstrained scale.

Usage

MCMC_Fit$unconstrain_draws()

Returns

Posterior draws on the unconstrained scale.

Method log_prob()

Evaluate log-probability values.

Usage

MCMC_Fit$log_prob(safe = FALSE)

Arguments

safe

Logical; whether to wrap the evaluation in a tryCatch block. Default is FALSE for speed.

Returns

Numeric vector of log-probability values.

Method bridgesampling()

Estimate the marginal likelihood by bridge sampling.

Usage

MCMC_Fit$bridgesampling(
  method = "normal",
  use_neff = TRUE,
  seed = NULL,
  max_iter = 100
)

Arguments

method

Character; the method to use for bridge sampling (e.g., "warp3", "normal"). Default is "warp3".

use_neff

Logical; whether to use the effective sample size (ESS) to adjust for autocorrelation. Default is TRUE.

seed

Integer; random seed for reproducibility. Default is NULL.

max_iter

Integer; maximum number of iterations for the estimation algorithm. Default is 100.

Returns

Bridge sampling result.

Method WAIC()

Compute WAIC from pointwise generated log likelihood.

Usage

MCMC_Fit$WAIC(...)

Arguments

...

Additional arguments passed to `draws()`, such as `chains` or `best_chains`.

Returns

A `waic_BayesRTMB` object.

Method diagnose()

Run basic diagnostics for the MCMC fit.

Usage

MCMC_Fit$diagnose(...)

Arguments

...

Additional arguments passed to `diagnose_mcmc_fit()`.

Returns

A `diagnose_BayesRTMB` object.

Method bayes_factor()

Calculate the Bayes factor by marginal-likelihood model comparison.

Usage

MCMC_Fit$bayes_factor(
  fixed = NULL,
  comparison_fit = NULL,
  bs_method = "normal",
  error_threshold = 0.2,
  ...
)

Arguments

fixed

Named list of parameter values used to construct the comparison model. For example, fixed = list(delta = 0) or fixed = list("b[x]" = 0).

comparison_fit

Optional `MCMC_Fit` object for an already fitted comparison model.

bs_method

Character; the method to use for bridge sampling ("normal" or "warp3").

error_threshold

Numeric; threshold for the approximate error warning.

...

Additional arguments passed to `sample()` when fitting the comparison model (e.g., chains = 4, sampling = 4000).

Returns

A list of class bayes_factor_rtmb containing Bayes factor results.

Method transformed_draws()

Compute transformed parameters from posterior draws.

Usage

MCMC_Fit$transformed_draws(
  tran_fn = NULL,
  progress = c("auto", "none", "bar", "message"),
  tape = c("auto", "none", "force")
)

Arguments

tran_fn

A function for transformed parameters.

progress

Progress reporting style: `"auto"`, `"none"`, `"bar"`, or `"message"`. `"auto"` and `"bar"` use line-based messages.

tape

Derived-quantity evaluation mode. `"auto"` tries RTMB tape evaluation and falls back to R evaluation on error; `"none"` always uses R evaluation; `"force"` requires tape evaluation and errors if it fails.

Returns

Transformed parameter draws.

Method generated_quantities()

Compute generated quantities from posterior draws.

Usage

MCMC_Fit$generated_quantities(
  code,
  progress = c("auto", "none", "bar", "message"),
  tape = c("auto", "none", "force")
)

Arguments

code

An `rtmb_code({ ... })` or `{ ... }` block containing the logic to be calculated using posterior samples.

progress

Progress reporting style: `"auto"`, `"none"`, `"bar"`, or `"message"`. `"auto"` and `"bar"` use line-based messages.

tape

Derived-quantity evaluation mode. `"auto"` tries RTMB tape evaluation and falls back to R evaluation on error; `"none"` always uses R evaluation; `"force"` requires tape evaluation and errors if it fails.

Returns

The `MCMC_Fit` object itself (invisibly). Results are appended to the `generate_fit` field.

Method resolve_switching()

Resolve label switching in posterior draws.

Usage

MCMC_Fit$resolve_switching(
  target,
  linked = NULL,
  overwrite = TRUE,
  scalar_fns = list()
)

Arguments

target

Character string specifying the target variable to base the relabeling on.

linked

Character vector of variable names to be relabeled in the same order as the target. Default is NULL.

overwrite

Logical; whether to overwrite the stored draws in the current object. Default is TRUE.

scalar_fns

A named list of functions to apply to scalar variables for relabeling. Default is an empty list.

Returns

Relabeled draws or updated object.

Method clone()

The objects of this class are cloneable with this method.

Usage

MCMC_Fit$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.