plot_mvgam_series: Plot observed time series used for 'mvgam' modelling

In mvgam: Multivariate (Dynamic) Generalized Additive Models

Plot observed time series used for mvgam modelling

Description

This function takes either a fitted mvgam object or a data.frame object and produces plots of observed time series, ACF, CDF and histograms for exploratory data analysis

Usage

plot_mvgam_series(
  object,
  data,
  newdata,
  y = "y",
  lines = TRUE,
  series = 1,
  n_bins = NULL,
  log_scale = FALSE
)

Arguments

object	Optional list object returned from mvgam. Either object or data must be supplied
data	Optional data.frame or list of training data containing at least 'series' and 'time'. Use this argument if training data have been gathered in the correct format for mvgam modelling but no model has yet been fitted.
newdata	Optional data.frame or list of test data containing at least 'series' and 'time' for the forecast horizon, in addition to any other variables included in the linear predictor of formula. If included, the observed values in the test data are compared to the model's forecast distribution for exploring biases in model predictions
y	Character. What is the name of the outcome variable in the supplied data? Defaults to 'y'
lines	Logical. If TRUE, line plots are used for visualizing time series. If FALSE, points are used.
series	Either an integer specifying which series in the set is to be plotted or the string 'all', which plots all series available in the supplied data
n_bins	integer specifying the number of bins to use for binning observed values when plotting a histogram. Default is to use the number of bins returned by a call to hist in base R
log_scale	logical. If series == 'all', this flag is used to control whether the time series plot is shown on the log scale (using log(Y + 1)). This can be useful when visualizing many series that may have different observed ranges. Default is FALSE

Value

A set of ggplot objects. If series is an integer, the plots will show observed time series, autocorrelation and cumulative distribution functions, and a histogram for the series. If series == 'all', a set of observed time series plots is returned in which all series are shown on each plot but only a single focal series is highlighted, with all remaining series shown as faint gray lines.

Author(s)

Nicholas J Clark and Matthijs Hollanders

Examples

# Simulate and plot series with observations bounded at 0 and 1 (Beta responses)
sim_data <- sim_mvgam(
  family = betar(),
  trend_model = RW(),
  prop_trend = 0.6
)

plot_mvgam_series(
  data = sim_data$data_train,
  series = 'all'
)

plot_mvgam_series(
  data = sim_data$data_train,
  newdata = sim_data$data_test,
  series = 1
)

# Now simulate series with overdispersed discrete observations
sim_data <- sim_mvgam(
  family = nb(),
  trend_model = RW(),
  prop_trend = 0.6,
  phi = 10
)

plot_mvgam_series(
  data = sim_data$data_train,
  series = 'all'
)

mvgam documentation built on Jan. 21, 2026, 9:07 a.m.