Skip to contents

Plot model convergence of a selected model

Source: R/mod_convergence_plot.R, R/mod_convergence_alpha.R, R/mod_convergence_rho.R
Convergence_plots.Rd

The convergence_plot() function generates and saves convergence diagnostics plots for the rho, alpha, omega, and beta parameters in an Hmsc model. These plots help assess whether the MCMC chains have reached stationarity. It supports parallel processing and can work with models fitted on HPC environments.

Usage

convergence_plot(
  path_coda = NULL,
  path_model = NULL,
  env_file = ".env",
  title = " ",
  n_omega = 1000L,
  n_cores = 8L,
  strategy = "multisession",
  n_RC = c(2L, 2L),
  beta_n_RC = c(3L, 3L),
  pages_per_file = 20L,
  chain_colors = NULL,
  margin_type = "histogram"
)

convergence_alpha(
  posterior = NULL,
  model_object = NULL,
  title = NULL,
  n_RC = NULL,
  add_footer = TRUE,
  add_title = TRUE,
  chain_colors = NULL,
  margin_type = "histogram"
)

convergence_rho(
  posterior = NULL,
  model_object = NULL,
  title = NULL,
  chain_colors = NULL,
  margin_type = "histogram"
)

convergence_Beta_ranges(model_dir)

Arguments

path_coda

Character. Path to a saved coda object containing MCMC samples.

path_model

Character. Path to a saved Hmsc model object.

env_file

Character. Path to the environment file containing paths to data sources. Defaults to .env.

title

Character. title for rho and alpha convergence plots. Default: " "

n_omega

Integer. Number of species interactions sampled for Omega parameter diagnostics. Default: 1000L

n_cores

Integer. Number of CPU cores to use for parallel processing. Default: 8.

strategy

Character. The parallel processing strategy to use. Valid options are "sequential", "multisession" (default), "multicore", and "cluster". See future::plan() and ecokit::set_parallel() for details.

n_RC

Numeric vector. Grid layout (rows×columns) for arranging alpha parameter plots. Default: c(2, 2). If NULL, the layout is automatically determined based on the number of alpha levels.

beta_n_RC

Numeric vector. The grid layout (rows×columns) for arranging beta parameter plots. Default: c(3, 3).

pages_per_file

Integer. Number of plots per page in the Omega parameter output. Default: 20L.

chain_colors

Character vector. MCMC chain colours (optional). Default: NULL.

margin_type

Character. The type of marginal plot to add to the main plot. Valid options are "histogram" (default) or "density".

posterior

mcmc.list or character. Either an MCMC object (mcmc.list) containing posterior samples, or a file path to a saved coda object.

model_object

Hmsc object or character. Either a fitted Hmsc model object, or a file path to a saved Hmsc model.

Logical. If TRUE (default), adds a footer with page numbers to each plot.

add_title

Logical. If TRUE (default), adds the main title (title) to the plot.

model_dir

Character. A path to the model directory.

Details

convergence_alpha(), convergence_rho(), and convergence_Beta_ranges are internal functions and should not be called directly. The convergence_Beta_ranges plots the convergence range of the each species beta parameters. It can be used to check if any of the chains show convergence issues; i.e., showing exceptionally high or low beta values.

Author

Ahmed El-Gabbas