MCMCdiag {MCMCvis}

Diagnostics summaries for models

Description

Model diagnostics and summary. Function reads information embedded in model fit object. Output varies by model fit object type but includes model run inputs, diagnostic information, and parameter summary. See DETAILS below for more information.

Usage

MCMCdiag(
  object,
  file_name,
  dir = getwd(),
  mkdir,
  add_field,
  add_field_names,
  save_object = FALSE,
  obj_name,
  add_obj,
  add_obj_names,
  cp_file,
  cp_file_names,
  open_txt = TRUE,
  summary = TRUE,
  ...
)

Arguments

object

Object containing MCMC output. See DETAILS below.

file_name

Character string with name of .txt file to be saved to dir (or mkdir if specified). If not specified, 'MCMCdiag.txt' will be used.

dir

Character string with directory where file(s) (or directory is argument for mkdir is specified) will be created. Defaults to working directory. An absolute or relative (to the working directory) path can be used.

mkdir

Character string with name of directory to be created. If specified, a directory will be created within the directory specified by dir. If directory exists, '_1' will be appended to specified name.

add_field

Object (or vector of objects) to be added to the .txt file.

add_field_names

Character string (or vector of character strings) specifying the name(s) of the add_field object(s).

save_object

Logical specifying whether the model output provided to the function (object) should be saved as a .rds file to dir (or mkdir if specified). Note that .rds files can be opened with rdsRDS().

obj_name

Character string specifying the file name of the .rds file (created from object) if save_object = TRUE.

add_obj

List with additional object(s) to be saved as .rds files to dir (or mkdir if specified). Objects can be of any types. Multiple objects can be specified. Note that .rds files can be opened with rdsRDS().

add_obj_names

Character string (or vector of character strings) specifying the name(s) of the objects to be saved as .rds files, specified with add_obj.

cp_file

Character string (or vector of character strings) specifying file(s) to be copied to dir (or mkdir if specified). Absolute or relative (to the working directory) paths can be used.

cp_file_names

Character string (or vector of character strings) specifying new names for files to be copied specified by cp_file. If no argument is provided, the copy names will be identical to the originals.

open_txt

Logical - if open_txt = TRUE .txt file will open in default .txt viewer after being generated.

summary

Logical specifying whether or not to output summary information from MCMCsummary at the bottom of the .txt file.

...

Arguments to be passed to MCMCsummary when generating summary if summary = TRUE.

Details

Some diagnostic information is only provided for models fit with particular pieces of software. For example, rstan output includes additional diagnostics related to the NUTS sampler. Output from jagsUI includes runtime information, but output from rjags does not. Note that this information could be fed manually to the function using the add_field argument.

object argument can be a stanfit object (rstan package), a CmdStanMCMC object (cmdstanr package), a stanreg object (rstanarm package), a brmsfit object (brms package), an mcmc.list object (coda and rjags packages), mcmc object (coda and nimble packages), list object (nimble package), an R2jags model object (R2jags package), a jagsUI model object (jagsUI package), or a matrix containing MCMC chains (each column representing MCMC output for a single parameter, rows representing iterations in the chain). The function automatically detects the object type and proceeds accordingly.

Output presented in .txt file varies by model fit object type but includes: model run time, number of warmup/burn-in iterations, total iterations, thinning rate, number of chains, specified adapt delta, specified max tree depth, specific initial step size, mean accept stat, mean tree depth, mean step size, number of divergent transitions, number max tree depth exceeds, number of chains with BFMI warnings, max Rhat (maximum Rhat of any parameter printed), min n.eff (minimum n.eff of any parameter printed), parameter summary information (passed from MCMCsummary), and any additional information fed to the add_field argument. See documentation for specific software used to fit model for more information on particular diagnostics.

Examples

#Load data
data(MCMC_data)

# MCMCdiag(MCMC_data,
#          #name of .txt file to be saved
#          file_name = 'blog-model-summary-2021-01-15',
#          #directory within which to save .txt file
#          dir = '~/Desktop',
#          #round MCMCsummary output in .txt file to two digits
#          round = 2,
#          #add two fields to .txt file
#          add_field = c(50, '1.0'),
#          #names of two additional fields to add to .txt file
#          add_field_names = c('Time (min)', 'Data version'))