Plot MCMC Trace — urc

Creates trace plots for posterior samples from a JAGS MCMC model. Trace plots are displayed separately for each parameter, with MCMC chains distinguished by color.

urc_trace(
  model,
  parameters = NULL,
  exclude = NULL,
  deviance = FALSE,
  chains = NULL,
  labels = NULL,
  palette = NULL,
  alpha = 0.6,
  x_label = "Iteration",
  y_label = "Value",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  scales = "free",
  ncol = NULL,
  nrow = NULL,
  line_args = list(),
  theme = ggplot2::theme_minimal(),
  theme_args = list(),
  ...
)

Arguments

model: A fitted JAGS model object containing posterior samples.
parameters: Optional character vector specifying the parameters to plot. If NULL, all available parameters are plotted except loglik and, by default, deviance. Parameters can be specified by their exact name (e.g., "lambda[1]") or by their base name (e.g., "lambda"), which selects all indexed parameters.
exclude: Optional character vector specifying parameters to exclude from the plot. Exact parameter names or base parameter names can be used.
deviance: Logical; should posterior deviance be included? Defaults to FALSE.
chains: Optional numeric vector specifying the chains to plot. If NULL, all available chains are plotted.
labels: Optional named character vector used to rename parameter labels in the facets. Names can correspond to exact parameter names or base parameter names.
palette: Character vector of colors used for the MCMC chains. If NULL, a publication-friendly colorblind-safe palette is used. Colors are recycled if fewer colors are supplied than chains.
alpha: Numeric value between 0 and 1 controlling the transparency of the trace lines. Defaults to 0.6.
x_label: Character string specifying the x-axis label. Defaults to "Iteration".
y_label: Character string specifying the y-axis label. Defaults to "Value".
title: Optional plot title.
subtitle: Optional plot subtitle.
caption: Optional plot caption.
scales: Character string specifying the scales used for the facets. Must be one of "fixed", "free", "free_x", or "free_y". Defaults to "free".
ncol: Number of columns in the facet layout.
nrow: Number of rows in the facet layout.
line_args: Named list of additional arguments passed to ggplot2::geom_line(). These arguments override the corresponding defaults, including alpha.
theme: A ggplot2 theme object. Defaults to ggplot2::theme_minimal().
theme_args: Named list of arguments passed to ggplot2::theme().
...: Additional ggplot2 layers or components added to the plot.

Value

A ggplot object showing MCMC trace plots.

Examples

if (FALSE) { # \dontrun{
output <- urc_mcmc(x = mydata)

# Plot all parameters
urc_trace(output$models$poisson)

# Plot selected parameters
urc_trace(
  output$models$zip,
  parameters = c("lambda", "pi")
)

# Plot a specific indexed parameter
urc_trace(
  output$models$zip,
  parameters = "lambda[1]"
)

# Plot all lambda parameters
urc_trace(
  output$models$zip,
  parameters = "lambda"
)

# Exclude a parameter
urc_trace(
  output$models$zip,
  exclude = "pi"
)

# Plot only selected chains
urc_trace(
  output$models$poisson,
  chains = c(1, 2)
)

# Rename parameters
urc_trace(
  output$models$zip,
  labels = c(
    lambda = "Mean Count",
    pi = "Zero-Inflation Probability"
  )
)

# Change transparency
urc_trace(
  output$models$poisson,
  alpha = 0.3
)

# Customize chain colors
urc_trace(
  output$models$poisson,
  palette = c("#0072B2", "#D55E00")
)

# Use grayscale
urc_trace(
  output$models$poisson,
  palette = c("black", "grey50")
)

# Customize line appearance
urc_trace(
  output$models$poisson,
  line_args = list(
    linewidth = 0.4,
    alpha = 0.3
  )
)

# Publication-style theme
urc_trace(
  output$models$poisson,
  theme = ggplot2::theme_classic()
)

# Add additional ggplot layers
urc_trace(output$models$poisson) +
  ggplot2::geom_hline(
    yintercept = 0,
    linetype = "dashed"
  )
} # }