plot.dsp: Plot the Bayesian trend filtering fitted values

In dsp: Dynamic Shrinkage Process and Change Point Detection

Plot the Bayesian trend filtering fitted values

Description

Plot the BTF posterior mean of the conditional expectation with posterior credible intervals (pointwise and joint), the observed data, and true curves (if known)

Usage

## S3 method for class 'dsp'
plot(
  x,
  type,
  true_values = NULL,
  times = NULL,
  y_obs = NULL,
  include_joint_bands = FALSE,
  alpha = 0.05,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  xlim = NULL,
  ylim = NULL,
  mar = NULL,
  par_args = list(),
  legend = TRUE,
  legend_cex = 1,
  legend_pt_cex = 2,
  nr = NULL,
  nc = NULL,
  cp_thres = 0.5,
  ...
)

Arguments

x	an object of class dsp from dsp_fit().
type	character string giving the parameter name to visualize; must be one of the entries in x$mcmc_output.
true_values	optional ground-truth values to overlay on the plot. For scalar parameters, this should be a length-1 numeric value; for time-varying parameters, a ⁠T x 1⁠ vector; and for multi-parameter time-varying quantities, a ⁠T x p⁠ matrix matching the plotted parameter dimensions.
times	optional vector of observation points. If NULL, the function assumes T equally spaced points on ⁠[0,1]⁠.
y_obs	optional vector of observed data point of length T. Only for 2-dimensional parameters.
include_joint_bands	logical; if TRUE, include simultaneous credible bands in addition to pointwise credible intervals when available. Joint bands are currently supported only for time-varying parameters: zeta, omega, ypred, and mu for 2D outputs, and zeta, omega, ypred, mu, and beta for 3D outputs.
alpha	numeric credibility level used to construct posterior intervals and bands. Defaults to 0.05, corresponding to 95% intervals/bands.
xlab	optional x-axis label. If NULL, defaults to "t".
ylab	optional y-axis label. If NULL, defaults to type.
main	optional plot title. For multi-panel plots, this may be either a single title or a vector of titles of length equal to the number of panels.
xlim	optional x-axis limits passed to the plotting routine.
ylim	optional y-axis limits passed to the plotting routine.
mar	optional numeric vector of length 4 giving plot margins, passed to graphics::par().
par_args	optional named list of additional graphical parameters passed to graphics::par(), such as cex.axis, cex.lab, cex.main, las, or mgp.
legend	logical; if TRUE, add a legend to the plot.
legend_cex	numeric scaling factor for legend text size.
legend_pt_cex	numeric scaling factor for legend symbol size.
nr	optional number of rows in the plotting layout for multi-panel (3-dimensional) parameters.
nc	optional number of columns in the plotting layout for multi-panel (3-dimensional) parameters.
cp_thres	(default 0.5) cutoff proportion for percentage of posterior samples exceeding the threshold needed to label a changepoint
...	additional graphical arguments passed to the main plotting call, such as graphics::plot() or graphics::hist() depending on the parameter dimension.

Details

The plotting behavior depends on the dimension of the posterior samples stored in x$mcmc_output[[type]]:

• 1D (scalar parameter): A density-style summary is produced using a histogram with an overlaid kernel density estimate. The posterior mean and equal-tailed (1-\alpha)100\% credible interval are marked, and the true value is added if supplied through true_values.

• 2D (time-varying parameter): A time-series plot is produced showing the posterior mean together with equal-tailed pointwise credible intervals. If include_joint_bands = TRUE and the parameter is one of zeta, omega, ypred, or mu, simultaneous credible bands are also displayed. If true_values is provided, the ground truth is overlaid.

• 3D (multi-parameter time-varying quantity): A multi-panel collection of time-series plots is produced, one panel for each slice of the third dimension. Each panel shows the posterior mean, pointwise credible intervals, optional joint bands when supported, and optional ground-truth values. The panel layout is controlled by nr and nc; if omitted, a near-square layout is chosen automatically.

Axis labels, titles, plotting limits, margins, legend display, and additional graphical settings can be customized through xlab, ylab, main, xlim, ylim, mar, legend, legend_cex, legend_pt_cex, and par_args.

The x-axis values are taken from times. If times is not supplied, evenly spaced points on [0,1] are used. For differenced variance parameters such as "evol_sigma_t2" and "zeta_sigma_t2", the initial time points associated with prior initialization are automatically removed before plotting.

For fitted changepoint models, changepoint annotations may be added when supported by the plotted parameter and the corresponding latent components are present in the MCMC output.

Value

No return value, called for side effects

References

Krivobokova, T., Kneib, T., and Claeskens, G. (2010). Simultaneous confidence bands for penalized spline estimators. Journal of the American Statistical Association, 105(490), 852–863. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1198/jasa.2010.tm09165")}

Examples

set.seed(200)
signal = c(rep(0, 50), rep(10, 50))
noise = rep(1, 100)
noise_var = rep(1, 100)
for (k in 2:100){
  noise_var[k] = exp(0.9*log(noise_var[k-1]) + rnorm(1, 0, 0.5))
  noise[k] = rnorm(1, 0, sqrt(noise_var[k])) }

y = signal + noise
model_spec = dsp_spec(family = "gaussian", model = "changepoint",
                      D = 1, useAnom = TRUE, obsSV = "SV")
mcmc_output = dsp_fit(y, model_spec = model_spec, nsave = 500, nburn = 500)
# Estimated posterior mean vs ground truth
plot(mcmc_output, type = "mu", true_values = signal)
# Estimated innovation variance vs ground truth for illustration only
plot(mcmc_output, type = "obs_sigma_t2", true_values = noise^2)

dsp documentation built on July 17, 2026, 1:06 a.m.