MCMCresult {compareMCMCs}

R6 class to hold MCMC samples, timing results, and metrics

Description

R6 class to hold MCMC samples, timing results, and metrics

R6 class to hold MCMC samples, timing results, and metrics

Public fields

MCMC

Optional name for the MCMC method.

samples

Matrix of MCMC samples. Rows are for MCMC iterations. Columns are for parameters. Columns must be named.

times

A list of times including elements for setup, burnin, postburnin (sampling for recorded samples), and sampling (normally burnin + postburnin). Each list element should be a single numeric value.

metrics

A list of MCMC performance metrics such as effective sample size (ESS), efficiency, mean, median, and credible interval boundaries. metrics ' is organized as a list with three elements: byMCMC, byParameter, and other ' (currently unused).

byMCMC is for metrics with one number for an entire MCMC sample (as opposed to one number for each parameter). byMCMC is a data frame with one row and columns for MCMC name each metric. These would be metrics where there is a single

byParameter is for metrics with one number for each parameter in each MCMC sample. byParameter is a data.frame with one row for each MCMC-x-parameter combination and columns for MCMC method, parameter name, and each metric. There will only be one MCMC method name (all entries in the MCMC column will be the same).

The MCMC columns in byMCMC and byParameter are useful for combining metrics from a list of MCMCresult objects, such as done by combineMetrics, and for retaining MCMC method labels if these data.frames are copied and used outside of an MCMCresult object.

other is simply an arbitrary list. This allows arbitrarily structured metrics to be saved.

Elements of metrics are normally populated by addMetrics or compareMCMCs (which calls addMetrics).

sessionInfo

Result of running sessionInfo() prior to calling an MCMC engine, if requested.

Methods

Public methods

• MCMCresult$new()

• MCMCresult$setSamples()

• MCMCresult$rename()

• MCMCresult$initializeMetrics()

• MCMCresult$clearMetrics()

• MCMCresult$addMetricResult()

• MCMCresult$clone()

Method new()

Create a new MCMCresult object.

Usage

MCMCresult$new(...)

Arguments

...

Arbitrary initialization. If a matrix is passed, it will be used to initialize samples and the metrics elements. If a list with a matrix element named samples is passed, this element will be used as if the matrix itself was passed. Any other named elements of a list that correspond to fields of an MCMCresult object will be initialized from them.

Method setSamples()

Populate the samples and initialize the metrics

Usage

MCMCresult$setSamples(samples)

Arguments

samples

A data.frame with MCMC output.

Returns

NULL

Method rename()

Change the MCMC method name from oldName to newName

Usage

MCMCresult$rename(newName, oldName)

Arguments

newName

New name for MCMC method in metrics

oldName

Old name for MCMC method in metrics

Details

This change the MCMC field and the corresponding columns of metrics$byParameter and metrics$byMCMC.

If oldName is not the MCMC method name, this function does nothing.

Returns

NULL

Method initializeMetrics()

Initialize metrics if necessary

Usage

MCMCresult$initializeMetrics(silent = FALSE)

Arguments

silent

logical indicating whether to emit warnings

Details

This function does nothing if metrics are already initialized. It does not clear metrics. See clearMetrics for information on how metrics are initialized.

Returns

logical indicating whether metrics is well-formed or not.

Method clearMetrics()

Clear (reset) byParameter and/or byMCMC metrics

Usage

MCMCresult$clearMetrics(byParameter = TRUE, byMCMC = TRUE)

Arguments

byParameter

logical indicating whether to clear byParameter metrics

byMCMC

logical indicating whether to clear byMCMC metrics

Details

byParameter metrics are initialized to a data.frame with columns for MCMC (all the same entry, the MCMC field) and Parameter (taken from column names of the samples).

byMCMC metrics are initialized to a data.frame with a column for MCMC.

Method addMetricResult()

Add one set of metric results

Usage

MCMCresult$addMetricResult(metricResult)

Arguments

metricResult

A list with possible elements byParameter, byMCMC, and other. These are typically returned from a metric function called via addMetric. Each is combined with previous metrics already in the corresponding elements of metrics.

Method clone()

The objects of this class are cloneable with this method.

Usage

MCMCresult$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

See Also

renameMCMC to change the name of an MCMC method throughout the structure of a list of MCMCresult objects.