diff --git a/R/conditional_effects.R b/R/conditional_effects.R index b0b759ec..116dd70b 100644 --- a/R/conditional_effects.R +++ b/R/conditional_effects.R @@ -35,6 +35,7 @@ #' and create more bespoke conditional effects plots. #' @name conditional_effects.mvgam #' @author Nicholas J Clark +#' @seealso \code{\link[marginaleffects]{plot_predictions}}, \code{\link[marginaleffects]{plot_slopes}} #' @examples #' \dontrun{ #' # Simulate some data diff --git a/R/forecast.mvgam.R b/R/forecast.mvgam.R index 59dfdc39..90b9047c 100644 --- a/R/forecast.mvgam.R +++ b/R/forecast.mvgam.R @@ -3,7 +3,7 @@ #'@importFrom parallel clusterExport stopCluster setDefaultCluster #'@importFrom stats predict #'@importFrom rlang missing_arg -#'@param object \code{list} object returned from \code{mvgam}. See [mvgam()] +#'@inheritParams predict.mvgam #'@param newdata Optional \code{dataframe} or \code{list} of test data containing at least 'series' and 'time' #'in addition to any other variables included in the linear predictor of the original \code{formula}. If included, the #'covariate information in \code{newdata} will be used to generate forecasts from the fitted model equations. If @@ -19,17 +19,11 @@ #'if the fitted model contained multivariate trends (either as a dynamic factor or \code{VAR} process), #'as it saves recomputing the full set of trends for each series individually #'@param n_cores \code{integer} specifying number of cores for generating forecasts in parallel -#'@param type When this has the value \code{link} the linear predictor is calculated on the link scale. -#'If \code{expected} is used, predictions reflect the expectation of the response (the mean) -#'but ignore uncertainty in the observation process. When \code{response} (default) is used, -#'the predictions take uncertainty in the observation process into account to return -#'predictions on the outcome scale. When \code{trend} is used, only the forecast distribution for the -#'latent trend is returned #'@param ... Ignored #'@details Posterior predictions are drawn from the fitted \code{mvgam} and used to simulate a forecast distribution #'@return An object of class \code{mvgam_forecast} containing hindcast and forecast distributions. #'See \code{\link{mvgam_forecast-class}} for details. -#' +#'@seealso \code{\link{hindcast}}, \code{\link{score}} #'@export forecast <- function(object, ...){ UseMethod("forecast", object) diff --git a/R/formula.mvgam.R b/R/formula.mvgam.R index 98814486..f99e7d85 100644 --- a/R/formula.mvgam.R +++ b/R/formula.mvgam.R @@ -1,13 +1,13 @@ -#'Extract model.frame from a fitted mvgam object +#'Extract formulae from mvgam objects #' #'@rdname formula.mvgam #'@param x `mvgam` or `mvgam_prefit` object -#'@param trend_effects \code{logical}, return the model.frame from the +#'@param trend_effects \code{logical}, return the formula from the #'observation model (if \code{FALSE}) or from the underlying process #'model (if\code{TRUE}) #'@param ... Ignored #'@author Nicholas J Clark -#'@return A \code{matrix} containing the fitted model frame +#'@return A \code{formula} object #'@export formula.mvgam = function(x, trend_effects = FALSE, ...){ # Check trend_effects diff --git a/R/get_mvgam_priors.R b/R/get_mvgam_priors.R index d6d2c8a5..c058e90d 100644 --- a/R/get_mvgam_priors.R +++ b/R/get_mvgam_priors.R @@ -4,13 +4,6 @@ #'changed for a given `mvgam` model, as well listing their default distributions #' #' @inheritParams mvgam -#'@param use_stan Logical. If \code{TRUE} and if \code{rstan} is installed, the model will be compiled and sampled using -#'the Hamiltonian Monte Carlo with a call to \code{\link[cmdstanr]{cmdstan_model}} or, if `cmdstanr` is not available, -#'a call to \code{\link[rstan]{stan}}. Note that this functionality is still in development and -#'not all options that are available in \code{JAGS} can be used, including: no option for a Tweedie family and no option for -#'dynamic factor trends. However, as \code{Stan} can estimate Hilbert base approximate Gaussian Processes, which -#'are much more computationally tractable than full GPs for time series with `>100` observations, estimation -#'in \code{Stan} can support latent GP trends while estimation in \code{JAGS} cannot #'@details Users can supply a model formula, prior to fitting the model, so that default priors can be inspected and #'altered. To make alterations, change the contents of the `prior` column and supplying this #'\code{data.frame} to the `mvgam` function using the argument `priors`. If using `Stan` as the backend, @@ -26,7 +19,7 @@ #' ensure that the code is legal (i.e. to check that lower bounds are smaller than upper bounds, for #' example) #'@author Nicholas J Clark -#'@seealso \code{\link{mvgam}} +#'@seealso \code{\link{mvgam}} \code{\link[brms]{prior}} #'@return either a \code{data.frame} containing the prior definitions (if any suitable #'priors can be altered by the user) or \code{NULL}, indicating that no priors in the model #'can be modified through the `mvgam` interface diff --git a/R/hindcast.mvgam.R b/R/hindcast.mvgam.R index f6ecd968..cce003d0 100644 --- a/R/hindcast.mvgam.R +++ b/R/hindcast.mvgam.R @@ -1,23 +1,17 @@ #'@title Extract hindcasts for a fitted \code{mvgam} object #'@name hindcast.mvgam #'@importFrom stats predict -#'@param object \code{list} object returned from \code{mvgam}. See [mvgam()] +#'@inheritParams predict.mvgam #'@param series Either a \code{integer} specifying which series in the set is to be forecast, #'or the character string \code{'all'}, specifying that all series should be forecast. This is preferable #'if the fitted model contained multivariate trends (either as a dynamic factor or \code{VAR} process), #'as it saves recomputing the full set of trends for each series individually -#'@param type When this has the value \code{link} the linear predictor is calculated on the link scale. -#'If \code{expected} is used, predictions reflect the expectation of the response (the mean) -#'but ignore uncertainty in the observation process. When \code{response} (default) is used, -#'the predictions take uncertainty in the observation process into account to return -#'predictions on the outcome scale. When \code{trend} is used, only the hindcast distribution for the -#'latent trend is returned #'@param ... Ignored #'@details Posterior retrodictions are drawn from the fitted \code{mvgam} and #'organized into a convenient format #'@return An object of class \code{mvgam_forecast} containing hindcast distributions. #'See \code{\link{mvgam_forecast-class}} for details. -#' +#'#'@seealso \code{\link{forecast.mvgam}} #'@export hindcast <- function(object, ...){ UseMethod("hindcast", object) diff --git a/R/index-mvgam.R b/R/index-mvgam.R index 0d0b1469..0b2c77df 100644 --- a/R/index-mvgam.R +++ b/R/index-mvgam.R @@ -12,7 +12,7 @@ NULL #' @rdname index-mvgam #' @importFrom posterior variables -#' @param x \code{list} object of class `mvgam` +#' @param x \code{list} object returned from \code{mvgam}. See [mvgam()] #' @method variables mvgam #' @export #' @export variables diff --git a/R/mcmc_plot.mvgam.R b/R/mcmc_plot.mvgam.R index 6667bc82..3b5331a7 100644 --- a/R/mcmc_plot.mvgam.R +++ b/R/mcmc_plot.mvgam.R @@ -9,15 +9,18 @@ #' @param type The type of the plot. #' Supported types are (as names) \code{hist}, \code{dens}, #' \code{hist_by_chain}, \code{dens_overlay}, -#' \code{violin}, \code{intervals}, \code{areas}, \code{acf}, -#' \code{acf_bar},\code{trace}, \code{trace_highlight}, \code{scatter}, +#' \code{violin}, \code{intervals}, \code{areas}, +#' \code{areas_ridges}, \code{combo}, \code{acf}, +#' \code{acf_bar}, \code{trace}, \code{trace_highlight}, +#' \code{scatter}, \code{hex}, \code{pairs}, \code{violin}, #' \code{rhat}, \code{rhat_hist}, \code{neff}, \code{neff_hist} #' and \code{nuts_energy}. #' For an overview on the various plot types see #' \code{\link[bayesplot:MCMC-overview]{MCMC-overview}}. #' @return A \code{\link[ggplot2:ggplot]{ggplot}} object #' that can be further customized using the \pkg{ggplot2} package. -#' +#' @seealso \code{\link{mvgam_draws}} for an overview of some of the shortcut strings +#' that can be used for argument `variable` #' @examples #' \dontrun{ #' simdat <- sim_mvgam(n_series = 1, trend_model = 'AR1') @@ -26,6 +29,8 @@ #' data = simdat$data_train) #' mcmc_plot(mod) #' mcmc_plot(mod, type = 'neff_hist') +#' mcmc_plot(mod, variable = 'betas', type = 'areas') +#' mcmc_plot(mod, variable = 'trend_params', type = 'combo') #' } #' @export mcmc_plot.mvgam = function(object, @@ -75,13 +80,21 @@ mcmc_plot.mvgam = function(object, # x refers to a data.frame of draws draws <- as.array(object, variable = variable, regex = regex, use_alias = use_alias) - sel_variables <- dimnames(draws)[[2]] + sel_variables <- dimnames(draws)$variable if(type %in% c("scatter", "hex") && length(sel_variables) != 2L){ stop("Exactly 2 parameters must be selected for this type.", "\nParameters selected: ", paste0("'", sel_variables, "'", collapse = ", "), call. = FALSE) } + + if(type == 'pairs' && length(sel_variables) == 1L){ + stop("2 or more parameters must be selected for this type.", + "\nParameters selected: ", + paste0("'", sel_variables, "'", collapse = ", "), + call. = FALSE) + } + mcmc_args$x <- draws } } diff --git a/R/mvgam.R b/R/mvgam.R index 08ad7f97..4c9d920b 100644 --- a/R/mvgam.R +++ b/R/mvgam.R @@ -63,6 +63,7 @@ #' \item`student_t()` for real-valued data #' \item`Gamma()` for non-negative real-valued data} #'Note that only `nb()` and `poisson()` are available if using `JAGS` as the backend. +#'Default is `poisson()`. #'See \code{\link{mvgam_families}} for more details #'@param use_lv \code{logical}. If \code{TRUE}, use dynamic factors to estimate series' #'latent trends in a reduced dimension format. Defaults to \code{FALSE} diff --git a/R/plot.mvgam.R b/R/plot.mvgam.R index 7e6f913f..3195bbfc 100644 --- a/R/plot.mvgam.R +++ b/R/plot.mvgam.R @@ -2,7 +2,6 @@ #' #'This function takes a fitted \code{mvgam} object and produces plots of smooth functions, forecasts, trends and #'uncertainty components -#' #'@param x \code{list} object returned from \code{mvgam}. See [mvgam()] #'@param type \code{character} specifying which type of plot to return. Options are: #'series, @@ -14,7 +13,7 @@ #'trend, #'uncertainty, #'factors -#'@param residuals \code{logical}. If \code{TRUE} and `type = residuals`, posterior quantiles of partial residuals are added +#'@param residuals \code{logical}. If \code{TRUE} and `type = 'smooths'`, posterior quantiles of partial residuals are added #'to plots of 1-D smooths as a series of ribbon rectangles. #'Partial residuals for a smooth term are the median Dunn-Smyth residuals that would be obtained by dropping the term #'concerned from the model, while leaving all other estimates fixed (i.e. the diff --git a/R/plot_mvgam_factors.R b/R/plot_mvgam_factors.R index baa0061f..be035c72 100644 --- a/R/plot_mvgam_factors.R +++ b/R/plot_mvgam_factors.R @@ -3,7 +3,7 @@ #'This function takes a fitted \code{mvgam} object and returns plots and summary statistics for #'the latent dynamic factors #' -#'@param object \code{list} object returned from \code{mvgam} +#'@inheritParams plot.mvgam #'@param plot \code{logical} specifying whether factors should be plotted #'@author Nicholas J Clark #'@details If the model in \code{object} was estimated using dynamic factors, it is possible that not all factors diff --git a/R/plot_mvgam_fc.R b/R/plot_mvgam_fc.R index e8287cdd..45729449 100644 --- a/R/plot_mvgam_fc.R +++ b/R/plot_mvgam_fc.R @@ -1,6 +1,6 @@ #'Plot mvgam posterior predictions for a specified series #'@importFrom stats formula terms -#'@param object \code{list} object returned from \code{mvgam} +#'@inheritParams plot.mvgam #'@param series \code{integer} specifying which series in the set is to be plotted #'@param newdata Optional \code{dataframe} or \code{list} of test data containing at least 'series' and 'time' #'in addition to any other variables included in the linear predictor of the original \code{formula}. If included, the diff --git a/R/plot_mvgam_pterms.R b/R/plot_mvgam_pterms.R index b59716df..6feebec6 100644 --- a/R/plot_mvgam_pterms.R +++ b/R/plot_mvgam_pterms.R @@ -4,9 +4,7 @@ #' #'@importFrom graphics layout title rug bxp #'@importFrom stats coef predict -#'@param object \code{list} object returned from \code{mvgam} -#'@param trend_effects logical. If `TRUE` and a `trend_formula` was used in model -#'fitting, terms from the trend (i.e. process) model will be plotted +#'@inheritParams plot.mvgam #'@details Posterior empirical quantiles of each parametric term's partial effect estimates #'(on the link scale) are calculated and visualised as ribbon plots. These effects can #'be interpreted as the partial effect that a parametric term contributes when all other diff --git a/R/plot_mvgam_randomeffects.R b/R/plot_mvgam_randomeffects.R index 419a4da7..3f05d65f 100644 --- a/R/plot_mvgam_randomeffects.R +++ b/R/plot_mvgam_randomeffects.R @@ -3,9 +3,7 @@ #'This function plots posterior empirical quantiles for random effect smooths (bs = re) #' #'@importFrom graphics layout title -#'@param object \code{list} object returned from \code{mvgam} -#'@param trend_effects logical. If `TRUE` and a `trend_formula` was used in model -#'fitting, terms from the trend (i.e. process) model will be plotted +#'@inheritParams plot.mvgam #'@details Posterior empirical quantiles of random effect coefficient estimates #'(on the link scale) are calculated and visualised as ribbon plots. #'Labels for coefficients are taken from the levels of the original factor variable diff --git a/R/plot_mvgam_resids.R b/R/plot_mvgam_resids.R index eff551f2..0318da36 100644 --- a/R/plot_mvgam_resids.R +++ b/R/plot_mvgam_resids.R @@ -5,7 +5,7 @@ #'@importFrom graphics layout title #'@importFrom stats complete.cases qqnorm qqline acf pacf na.pass #'@importFrom mgcv bam -#'@param object \code{list} object returned from \code{mvgam} +#'@inheritParams plot.mvgam #'@param series \code{integer} specifying which series in the set is to be plotted #'@param newdata Optional \code{dataframe} or \code{list} of test data containing at least 'series', 'y', and 'time' #'in addition to any other variables included in the linear predictor of \code{formula}. If included, the diff --git a/R/plot_mvgam_smooth.R b/R/plot_mvgam_smooth.R index 89827be7..2ce98030 100644 --- a/R/plot_mvgam_smooth.R +++ b/R/plot_mvgam_smooth.R @@ -4,9 +4,7 @@ #' #'@importFrom grDevices hcl.colors #'@importFrom stats quantile predict -#'@param object \code{list} object returned from \code{mvgam} -#'@param trend_effects logical. If `TRUE` and a `trend_formula` was used in model -#'fitting, terms from the trend (i.e. process) model will be plotted +#'@inheritParams plot.mvgam #'@param series \code{integer} specifying which series in the set is to be plotted #'@param smooth either a \code{character} or \code{integer} specifying which smooth term to be plotted #'@param residuals \code{logical}. If \code{TRUE} then posterior quantiles of partial residuals are added diff --git a/R/plot_mvgam_trend.R b/R/plot_mvgam_trend.R index 0abc4653..5fadbb6b 100644 --- a/R/plot_mvgam_trend.R +++ b/R/plot_mvgam_trend.R @@ -1,7 +1,7 @@ #'Plot mvgam latent trend for a specified series #'@importFrom graphics par lines polygon box abline #'@importFrom stats sd quantile -#'@param object \code{list} object returned from \code{mvgam} +#'@inheritParams plot.mvgam #'@param series \code{integer} specifying which series in the set is to be plotted #'@param newdata Optional \code{dataframe} or \code{list} of test data containing at least 'series' and 'time' #'in addition to any other variables included in the linear predictor of the original \code{formula}. diff --git a/R/plot_mvgam_uncertainty.R b/R/plot_mvgam_uncertainty.R index 693cfaca..2a095449 100644 --- a/R/plot_mvgam_uncertainty.R +++ b/R/plot_mvgam_uncertainty.R @@ -1,7 +1,7 @@ #'Plot mvgam forecast uncertainty contributions for a specified series #'@importFrom graphics legend #'@importFrom stats predict -#'@param object \code{list} object returned from \code{mvgam} +#'@inheritParams plot.mvgam #'@param series \code{integer} specifying which series in the set is to be plotted #'@param newdata A \code{dataframe} or \code{list} containing at least 'series' and 'time' for the forecast horizon, in #'addition to any other variables included in the linear predictor of \code{formula} diff --git a/R/ppc.mvgam.R b/R/ppc.mvgam.R index d1cb954d..47ddf108 100644 --- a/R/ppc.mvgam.R +++ b/R/ppc.mvgam.R @@ -39,7 +39,21 @@ #'series (for \code{type == 'hist'}), kernel density or empirical CDF estimates for #'posterior predictions (for \code{type == 'density'} or \code{type == 'cdf'}) or a Probability #'Integral Transform histogram (for \code{type == 'pit'}). +#' @examples +#' \dontrun{ +#' # Simulate some smooth effects and fit a model +#' set.seed(0) +#' dat <- mgcv::gamSim(1, n = 200, scale = 2) +#' dat$time <- 1:NROW(dat) +#' mod <- mvgam(y ~ s(x0) + s(x1) + s(x2) + s(x3), +#' data = dat, +#' family = gaussian()) #' +#' # Posterior checks +#' ppc(mod, type = 'hist') +#' ppc(mod, type = 'density') +#' ppc(mod, type = 'cdf') +#' } #'@export ppc <- function(object, ...){ UseMethod("ppc", object) diff --git a/R/predict.mvgam.R b/R/predict.mvgam.R index 2313b769..1d88c064 100644 --- a/R/predict.mvgam.R +++ b/R/predict.mvgam.R @@ -1,6 +1,6 @@ #'Predict from the GAM component of an mvgam model #'@importFrom stats predict -#'@param object Object of class `mvgam` +#'@param object \code{list} object returned from \code{mvgam}. See [mvgam()] #'@param newdata Optional \code{dataframe} or \code{list} of test data containing the #'variables included in the linear predictor of \code{formula}. If not supplied, #'predictions are generated for the original observations used for the model fit. diff --git a/R/score.mvgam_forecast.R b/R/score.mvgam_forecast.R index 3752b094..081e6c65 100644 --- a/R/score.mvgam_forecast.R +++ b/R/score.mvgam_forecast.R @@ -32,21 +32,23 @@ #'will only contain the linear predictors #'@examples #'\dontrun{ -#'#Simulate observations for three count-valued time series +#'# Simulate observations for three count-valued time series #'data <- sim_mvgam() -#'#Fit a dynamic model using 'newdata' to automatically produce forecasts +#'# Fit a dynamic model using 'newdata' to automatically produce forecasts #'mod <- mvgam(y ~ 1, #' trend_model = 'RW', #' data = data$data_train, #' newdata = data$data_test) #' -#'#Extract forecasts into a 'mvgam_forecast' object +#'# Extract forecasts into a 'mvgam_forecast' object #'fc <- forecast(mod) #' -#'#Score forecasts -#'score(fc, score = 'drps') +#'# Compute Discrete Rank Probability Scores and 0.90 interval coverages +#'fc_scores <- score(fc, score = 'drps') +#'str(fc_scores) #'} #'@method score mvgam_forecast +#'@seealso \code{\link{forecast.mvgam}} #'@export score.mvgam_forecast = function(object, score = 'crps', log = FALSE, weights, diff --git a/R/update.mvgam.R b/R/update.mvgam.R index f8ce3e2c..b61b003f 100644 --- a/R/update.mvgam.R +++ b/R/update.mvgam.R @@ -4,56 +4,11 @@ #'@name update.mvgam #'@importFrom mgcv nb betar #'@importFrom rlang missing_arg -#'@param object A fitted `mvgam` model +#'@inheritParams mvgam +#'@param object \code{list} object returned from \code{mvgam}. See [mvgam()] #'@param formula Optional new `formula` object. Note, `mvgam` currently does not support dynamic formula #'updates such as removal of specific terms with `- term`. When updating, the entire formula needs #'to be supplied -#'@param trend_formula An optional \code{character} string specifying the GAM process model formula. If -#'supplied, a linear predictor will be modelled for the latent trends to capture process model evolution -#'separately from the observation model. Should not have a response variable specified on the left-hand side -#'of the formula (i.e. a valid option would be `~ season + s(year)`). This feature is experimental, and is only -#'currently available for Random Walk trend models. -#'@param data A \code{dataframe} or \code{list} containing the model response variable and covariates -#'required by the GAM \code{formula}. Should include columns: -#''series' (character or factor index of the series IDs) -#''time' (numeric index of the time point for each observation). -#'Any other variables to be included in the linear predictor of \code{formula} must also be present -#'@param newdata Optional \code{dataframe} or \code{list} of test data containing at least 'series' and 'time' -#'in addition to any other variables included in the linear predictor of \code{formula}. If included, the -#'observations in variable \code{y} will be set to \code{NA} when fitting the model so that posterior -#'simulations can be obtained -#'@param trend_model \code{character} specifying the time series dynamics for the latent trend. Options are: -#'\itemize{ -#' \item `None` (no latent trend component; i.e. the GAM component is all that contributes to the linear predictor, -#'and the observation process is the only source of error; similarly to what is estimated by \code{\link[mgcv]{gam}}) -#' \item `RW` (random walk with possible drift) -#' \item `AR1` (with possible drift) -#' \item `AR2` (with possible drift) -#' \item `AR3` (with possible drift) -#' \item `VAR1` (with possible drift; only available in \code{Stan}) -#' \item `GP` (Gaussian Process with squared exponential kernel; -#'only available in \code{Stan})} -#'@param trend_map Optional `data.frame` specifying which series should depend on which latent -#'trends. Useful for allowing multiple series to depend on the same latent trend process, but with -#'different observation processes. If supplied, a latent factor model is set up by setting -#'`use_lv = TRUE` and using the mapping to set up the shared trends. Needs to have column names -#'`series` and `trend`, with integer values in the `trend` column to state which trend each series -#'should depend on. The `series` column should have a single unique entry for each series in the -#'data (names should perfectly match factor levels of the `series` variable in `data`). See examples -#'in \code{\link{mvgam}} for details -#'@param family \code{family} specifying the exponential observation family for the series. Currently supported -#'families are: `nb()`, `poisson()`, `tweedie()`, `gaussian()`, `betar()`, `lognormal()`, `student_t()` and `Gamma()` -#'@param use_lv \code{logical}. If \code{TRUE}, use dynamic factors to estimate series' -#'latent trends in a reduced dimension format. If \code{FALSE}, estimate independent latent trends for each series -#'@param n_lv \code{integer} the number of latent dynamic factors to use if \code{use_lv == TRUE}. -#'Cannot be \code{>n_series}. Defaults arbitrarily to \code{min(2, floor(n_series / 2))} -#'@param priors An optional \code{data.frame} with prior -#'definitions. See \code{\link{get_mvgam_priors}} and -#'[mvgam] for more information on changing default prior distributions -#'@param lfo Logical indicating whether this is part of a call to [lfo_cv.mvgam]. Returns a -#'lighter version of the model with no residuals and fewer monitored parameters to speed up -#'post-processing. But other downstream functions will not work properly, so users should always -#'leave this set as `FALSE` #'@param ... Other arguments to be passed to \code{\link{mvgam}} #' @examples #' \dontrun{ diff --git a/man/conditional_effects.mvgam.Rd b/man/conditional_effects.mvgam.Rd index 9b491b48..2f4da81b 100644 --- a/man/conditional_effects.mvgam.Rd +++ b/man/conditional_effects.mvgam.Rd @@ -101,6 +101,9 @@ conditional_effects(mod) conditional_effects(mod, conf_level = 0.5, type = 'link') } } +\seealso{ +\code{\link[marginaleffects]{plot_predictions}}, \code{\link[marginaleffects]{plot_slopes}} +} \author{ Nicholas J Clark } diff --git a/man/forecast.mvgam.Rd b/man/forecast.mvgam.Rd index 6e209f1d..3051e2d7 100644 --- a/man/forecast.mvgam.Rd +++ b/man/forecast.mvgam.Rd @@ -41,12 +41,12 @@ as it saves recomputing the full set of trends for each series individually} \item{n_cores}{\code{integer} specifying number of cores for generating forecasts in parallel} -\item{type}{When this has the value \code{link} the linear predictor is calculated on the link scale. +\item{type}{When this has the value \code{link} (default) the linear predictor is calculated on the link scale. If \code{expected} is used, predictions reflect the expectation of the response (the mean) -but ignore uncertainty in the observation process. When \code{response} (default) is used, +but ignore uncertainty in the observation process. When \code{response} is used, the predictions take uncertainty in the observation process into account to return -predictions on the outcome scale. When \code{trend} is used, only the forecast distribution for the -latent trend is returned} +predictions on the outcome scale. When \code{variance} is used, the variance of the response +with respect to the mean (mean-variance relationship) is returned} } \value{ An object of class \code{mvgam_forecast} containing hindcast and forecast distributions. @@ -87,3 +87,6 @@ plot(fc, series = 3) } } +\seealso{ +\code{\link{hindcast}}, \code{\link{score}} +} diff --git a/man/formula.mvgam.Rd b/man/formula.mvgam.Rd index cc8d2cf2..497051fc 100644 --- a/man/formula.mvgam.Rd +++ b/man/formula.mvgam.Rd @@ -3,7 +3,7 @@ \name{formula.mvgam} \alias{formula.mvgam} \alias{formula.mvgam_prefit} -\title{Extract model.frame from a fitted mvgam object} +\title{Extract formulae from mvgam objects} \usage{ \method{formula}{mvgam}(x, trend_effects = FALSE, ...) @@ -12,17 +12,17 @@ \arguments{ \item{x}{\code{mvgam} or \code{mvgam_prefit} object} -\item{trend_effects}{\code{logical}, return the model.frame from the +\item{trend_effects}{\code{logical}, return the formula from the observation model (if \code{FALSE}) or from the underlying process model (if\code{TRUE})} \item{...}{Ignored} } \value{ -A \code{matrix} containing the fitted model frame +A \code{formula} object } \description{ -Extract model.frame from a fitted mvgam object +Extract formulae from mvgam objects } \author{ Nicholas J Clark diff --git a/man/get_mvgam_priors.Rd b/man/get_mvgam_priors.Rd index 0a30f373..c261a995 100644 --- a/man/get_mvgam_priors.Rd +++ b/man/get_mvgam_priors.Rd @@ -54,6 +54,7 @@ families are: \item\code{student_t()} for real-valued data \item\code{Gamma()} for non-negative real-valued data} Note that only \code{nb()} and \code{poisson()} are available if using \code{JAGS} as the backend. +Default is \code{poisson()}. See \code{\link{mvgam_families}} for more details} \item{use_lv}{\code{logical}. If \code{TRUE}, use dynamic factors to estimate series' @@ -62,13 +63,11 @@ latent trends in a reduced dimension format. Defaults to \code{FALSE}} \item{n_lv}{\code{integer} the number of latent dynamic factors to use if \code{use_lv == TRUE}. Cannot be \code{>n_series}. Defaults arbitrarily to \code{min(2, floor(n_series / 2))}} -\item{use_stan}{Logical. If \code{TRUE} and if \code{rstan} is installed, the model will be compiled and sampled using -the Hamiltonian Monte Carlo with a call to \code{\link[cmdstanr]{cmdstan_model}} or, if \code{cmdstanr} is not available, -a call to \code{\link[rstan]{stan}}. Note that this functionality is still in development and -not all options that are available in \code{JAGS} can be used, including: no option for a Tweedie family and no option for -dynamic factor trends. However, as \code{Stan} can estimate Hilbert base approximate Gaussian Processes, which -are much more computationally tractable than full GPs for time series with \verb{>100} observations, estimation -in \code{Stan} can support latent GP trends while estimation in \code{JAGS} cannot} +\item{use_stan}{Logical. If \code{TRUE}, the model will be compiled and sampled using +Hamiltonian Monte Carlo with a call to \code{\link[cmdstanr]{cmdstan_model}} or +a call to \code{\link[rstan]{stan}}. Note that +there are many more options when using \code{Stan} vs \code{JAGS} (the only "advantage" of \code{JAGS} is the ability +to use a Tweedie family).} \item{trend_model}{\code{character} or \code{function} specifying the time series dynamics for the latent trend. Options are: \itemize{ @@ -241,7 +240,7 @@ code(mod2) } \seealso{ -\code{\link{mvgam}} +\code{\link{mvgam}} \code{\link[brms]{prior}} } \author{ Nicholas J Clark diff --git a/man/hindcast.mvgam.Rd b/man/hindcast.mvgam.Rd index 10e551eb..588c00d5 100644 --- a/man/hindcast.mvgam.Rd +++ b/man/hindcast.mvgam.Rd @@ -19,16 +19,17 @@ or the character string \code{'all'}, specifying that all series should be forec if the fitted model contained multivariate trends (either as a dynamic factor or \code{VAR} process), as it saves recomputing the full set of trends for each series individually} -\item{type}{When this has the value \code{link} the linear predictor is calculated on the link scale. +\item{type}{When this has the value \code{link} (default) the linear predictor is calculated on the link scale. If \code{expected} is used, predictions reflect the expectation of the response (the mean) -but ignore uncertainty in the observation process. When \code{response} (default) is used, +but ignore uncertainty in the observation process. When \code{response} is used, the predictions take uncertainty in the observation process into account to return -predictions on the outcome scale. When \code{trend} is used, only the hindcast distribution for the -latent trend is returned} +predictions on the outcome scale. When \code{variance} is used, the variance of the response +with respect to the mean (mean-variance relationship) is returned} } \value{ An object of class \code{mvgam_forecast} containing hindcast distributions. See \code{\link{mvgam_forecast-class}} for details. +#'@seealso \code{\link{forecast.mvgam}} } \description{ Extract hindcasts for a fitted \code{mvgam} object diff --git a/man/index-mvgam.Rd b/man/index-mvgam.Rd index 6d38c66e..1f5d8473 100644 --- a/man/index-mvgam.Rd +++ b/man/index-mvgam.Rd @@ -15,7 +15,7 @@ \method{variables}{mvgam}(x, ...) } \arguments{ -\item{x}{\code{list} object of class \code{mvgam}} +\item{x}{\code{list} object returned from \code{mvgam}. See \code{\link[=mvgam]{mvgam()}}} \item{...}{Arguments passed to individual methods (if applicable).} } diff --git a/man/mcmc_plot.mvgam.Rd b/man/mcmc_plot.mvgam.Rd index 42196808..7e178f76 100644 --- a/man/mcmc_plot.mvgam.Rd +++ b/man/mcmc_plot.mvgam.Rd @@ -19,8 +19,10 @@ \item{type}{The type of the plot. Supported types are (as names) \code{hist}, \code{dens}, \code{hist_by_chain}, \code{dens_overlay}, -\code{violin}, \code{intervals}, \code{areas}, \code{acf}, -\code{acf_bar},\code{trace}, \code{trace_highlight}, \code{scatter}, +\code{violin}, \code{intervals}, \code{areas}, +\code{areas_ridges}, \code{combo}, \code{acf}, +\code{acf_bar}, \code{trace}, \code{trace_highlight}, +\code{scatter}, \code{violin}, \code{rhat}, \code{rhat_hist}, \code{neff}, \code{neff_hist} and \code{nuts_energy}. For an overview on the various plot types see @@ -57,5 +59,11 @@ mod <- mvgam(y ~ s(season, bs = 'cc'), data = simdat$data_train) mcmc_plot(mod) mcmc_plot(mod, type = 'neff_hist') +mcmc_plot(mod, variable = 'betas', type = 'areas') +mcmc_plot(mod, variable = 'trend_params', type = 'combo') } } +\seealso{ +\code{\link{mvgam_draws}} for an overview of some of the shortcut strings +that can be used for argument \code{variable} +} diff --git a/man/mvgam.Rd b/man/mvgam.Rd index 94a26ff6..3d4da0e7 100644 --- a/man/mvgam.Rd +++ b/man/mvgam.Rd @@ -106,6 +106,7 @@ families are: \item\code{student_t()} for real-valued data \item\code{Gamma()} for non-negative real-valued data} Note that only \code{nb()} and \code{poisson()} are available if using \code{JAGS} as the backend. +Default is \code{poisson()}. See \code{\link{mvgam_families}} for more details} \item{use_lv}{\code{logical}. If \code{TRUE}, use dynamic factors to estimate series' diff --git a/man/plot.mvgam.Rd b/man/plot.mvgam.Rd index d0e0d2be..6c34742d 100644 --- a/man/plot.mvgam.Rd +++ b/man/plot.mvgam.Rd @@ -32,7 +32,7 @@ factors} \item{series}{\code{integer} specifying which series in the set is to be plotted. This is ignored if \code{type == 're'}} -\item{residuals}{\code{logical}. If \code{TRUE} and \code{type = residuals}, posterior quantiles of partial residuals are added +\item{residuals}{\code{logical}. If \code{TRUE} and \code{type = 'smooths'}, posterior quantiles of partial residuals are added to plots of 1-D smooths as a series of ribbon rectangles. Partial residuals for a smooth term are the median Dunn-Smyth residuals that would be obtained by dropping the term concerned from the model, while leaving all other estimates fixed (i.e. the diff --git a/man/plot_mvgam_factors.Rd b/man/plot_mvgam_factors.Rd index 859211de..d9f81f1e 100644 --- a/man/plot_mvgam_factors.Rd +++ b/man/plot_mvgam_factors.Rd @@ -7,8 +7,6 @@ plot_mvgam_factors(object, plot = TRUE) } \arguments{ -\item{object}{\code{list} object returned from \code{mvgam}} - \item{plot}{\code{logical} specifying whether factors should be plotted} } \value{ diff --git a/man/plot_mvgam_forecasts.Rd b/man/plot_mvgam_forecasts.Rd index e389682c..81bfe154 100644 --- a/man/plot_mvgam_forecasts.Rd +++ b/man/plot_mvgam_forecasts.Rd @@ -37,8 +37,6 @@ plot_mvgam_fc( ) } \arguments{ -\item{object}{\code{list} object returned from \code{mvgam}} - \item{series}{\code{integer} specifying which series in the set is to be plotted} \item{newdata}{Optional \code{dataframe} or \code{list} of test data containing at least 'series' and 'time' diff --git a/man/plot_mvgam_pterms.Rd b/man/plot_mvgam_pterms.Rd index 73ba2f9a..1799f82d 100644 --- a/man/plot_mvgam_pterms.Rd +++ b/man/plot_mvgam_pterms.Rd @@ -7,8 +7,6 @@ plot_mvgam_pterms(object, trend_effects = FALSE) } \arguments{ -\item{object}{\code{list} object returned from \code{mvgam}} - \item{trend_effects}{logical. If \code{TRUE} and a \code{trend_formula} was used in model fitting, terms from the trend (i.e. process) model will be plotted} } diff --git a/man/plot_mvgam_randomeffects.Rd b/man/plot_mvgam_randomeffects.Rd index 9fc4dfc1..9210005f 100644 --- a/man/plot_mvgam_randomeffects.Rd +++ b/man/plot_mvgam_randomeffects.Rd @@ -7,8 +7,6 @@ plot_mvgam_randomeffects(object, trend_effects = FALSE) } \arguments{ -\item{object}{\code{list} object returned from \code{mvgam}} - \item{trend_effects}{logical. If \code{TRUE} and a \code{trend_formula} was used in model fitting, terms from the trend (i.e. process) model will be plotted} } diff --git a/man/plot_mvgam_resids.Rd b/man/plot_mvgam_resids.Rd index 0d2d2d83..22503ad3 100644 --- a/man/plot_mvgam_resids.Rd +++ b/man/plot_mvgam_resids.Rd @@ -7,8 +7,6 @@ plot_mvgam_resids(object, series = 1, newdata, data_test) } \arguments{ -\item{object}{\code{list} object returned from \code{mvgam}} - \item{series}{\code{integer} specifying which series in the set is to be plotted} \item{newdata}{Optional \code{dataframe} or \code{list} of test data containing at least 'series', 'y', and 'time' diff --git a/man/plot_mvgam_smooth.Rd b/man/plot_mvgam_smooth.Rd index 65900446..6bf28bf6 100644 --- a/man/plot_mvgam_smooth.Rd +++ b/man/plot_mvgam_smooth.Rd @@ -18,8 +18,6 @@ plot_mvgam_smooth( ) } \arguments{ -\item{object}{\code{list} object returned from \code{mvgam}} - \item{trend_effects}{logical. If \code{TRUE} and a \code{trend_formula} was used in model fitting, terms from the trend (i.e. process) model will be plotted} diff --git a/man/plot_mvgam_trend.Rd b/man/plot_mvgam_trend.Rd index 36b9012e..900b09ce 100644 --- a/man/plot_mvgam_trend.Rd +++ b/man/plot_mvgam_trend.Rd @@ -20,8 +20,6 @@ plot_mvgam_trend( ) } \arguments{ -\item{object}{\code{list} object returned from \code{mvgam}} - \item{series}{\code{integer} specifying which series in the set is to be plotted} \item{newdata}{Optional \code{dataframe} or \code{list} of test data containing at least 'series' and 'time' diff --git a/man/plot_mvgam_uncertainty.Rd b/man/plot_mvgam_uncertainty.Rd index d7824ba6..8e217ee7 100644 --- a/man/plot_mvgam_uncertainty.Rd +++ b/man/plot_mvgam_uncertainty.Rd @@ -14,8 +14,6 @@ plot_mvgam_uncertainty( ) } \arguments{ -\item{object}{\code{list} object returned from \code{mvgam}} - \item{series}{\code{integer} specifying which series in the set is to be plotted} \item{newdata}{A \code{dataframe} or \code{list} containing at least 'series' and 'time' for the forecast horizon, in diff --git a/man/posterior_epred.mvgam.Rd b/man/posterior_epred.mvgam.Rd index c93368c6..1911f035 100644 --- a/man/posterior_epred.mvgam.Rd +++ b/man/posterior_epred.mvgam.Rd @@ -8,7 +8,7 @@ \method{posterior_epred}{mvgam}(object, newdata, data_test, process_error = TRUE, ...) } \arguments{ -\item{object}{Object of class \code{mvgam}} +\item{object}{\code{list} object returned from \code{mvgam}. See \code{\link[=mvgam]{mvgam()}}} \item{newdata}{Optional \code{dataframe} or \code{list} of test data containing the variables included in the linear predictor of \code{formula}. If not supplied, diff --git a/man/posterior_linpred.mvgam.Rd b/man/posterior_linpred.mvgam.Rd index 672f734b..dd125dcb 100644 --- a/man/posterior_linpred.mvgam.Rd +++ b/man/posterior_linpred.mvgam.Rd @@ -14,7 +14,7 @@ ) } \arguments{ -\item{object}{Object of class \code{mvgam}} +\item{object}{\code{list} object returned from \code{mvgam}. See \code{\link[=mvgam]{mvgam()}}} \item{transform}{Logical; if \code{FALSE} (the default), draws of the linear predictor are returned. diff --git a/man/posterior_predict.mvgam.Rd b/man/posterior_predict.mvgam.Rd index b765b6fc..0c437971 100644 --- a/man/posterior_predict.mvgam.Rd +++ b/man/posterior_predict.mvgam.Rd @@ -7,7 +7,7 @@ \method{posterior_predict}{mvgam}(object, newdata, data_test, process_error = TRUE, ...) } \arguments{ -\item{object}{Object of class \code{mvgam}} +\item{object}{\code{list} object returned from \code{mvgam}. See \code{\link[=mvgam]{mvgam()}}} \item{newdata}{Optional \code{dataframe} or \code{list} of test data containing the variables included in the linear predictor of \code{formula}. If not supplied, diff --git a/man/ppc.mvgam.Rd b/man/ppc.mvgam.Rd index 139a8d84..ca29054c 100644 --- a/man/ppc.mvgam.Rd +++ b/man/ppc.mvgam.Rd @@ -74,3 +74,19 @@ can also be compared to out of sample observations as long as these observations 'data_test' in the original model fit and supplied here. Rootograms are currently only plotted using the 'hanging' style } +\examples{ +\dontrun{ +# Simulate some smooth effects and fit a model +set.seed(0) +dat <- mgcv::gamSim(1, n = 200, scale = 2) +dat$time <- 1:NROW(dat) +mod <- mvgam(y ~ s(x0) + s(x1) + s(x2) + s(x3), + data = dat, + family = gaussian()) + +# Posterior checks +ppc(mod, type = 'hist') +ppc(mod, type = 'density') +ppc(mod, type = 'cdf') +} +} diff --git a/man/predict.mvgam.Rd b/man/predict.mvgam.Rd index 45f7535b..6a5265c0 100644 --- a/man/predict.mvgam.Rd +++ b/man/predict.mvgam.Rd @@ -7,7 +7,7 @@ \method{predict}{mvgam}(object, newdata, data_test, type = "link", process_error = TRUE, ...) } \arguments{ -\item{object}{Object of class \code{mvgam}} +\item{object}{\code{list} object returned from \code{mvgam}. See \code{\link[=mvgam]{mvgam()}}} \item{newdata}{Optional \code{dataframe} or \code{list} of test data containing the variables included in the linear predictor of \code{formula}. If not supplied, diff --git a/man/score.mvgam_forecast.Rd b/man/score.mvgam_forecast.Rd index a3a22cbb..8dedb3fd 100644 --- a/man/score.mvgam_forecast.Rd +++ b/man/score.mvgam_forecast.Rd @@ -59,18 +59,22 @@ Compute probabilistic forecast scores for mvgam objects } \examples{ \dontrun{ -#Simulate observations for three count-valued time series +# Simulate observations for three count-valued time series data <- sim_mvgam() -#Fit a dynamic model using 'newdata' to automatically produce forecasts +# Fit a dynamic model using 'newdata' to automatically produce forecasts mod <- mvgam(y ~ 1, trend_model = 'RW', data = data$data_train, newdata = data$data_test) -#Extract forecasts into a 'mvgam_forecast' object +# Extract forecasts into a 'mvgam_forecast' object fc <- forecast(mod) -#Score forecasts -score(fc, score = 'drps') +# Compute Discrete Rank Probability Scores and 0.90 interval coverages +fc_scores <- score(fc, score = 'drps') +str(fc_scores) } } +\seealso{ +\code{\link{forecast.mvgam}} +} diff --git a/man/update.mvgam.Rd b/man/update.mvgam.Rd index 85dbed0f..532918da 100644 --- a/man/update.mvgam.Rd +++ b/man/update.mvgam.Rd @@ -21,7 +21,7 @@ ) } \arguments{ -\item{object}{A fitted \code{mvgam} model} +\item{object}{\code{list} object returned from \code{mvgam}. See \code{\link[=mvgam]{mvgam()}}} \item{formula}{Optional new \code{formula} object. Note, \code{mvgam} currently does not support dynamic formula updates such as removal of specific terms with \code{- term}. When updating, the entire formula needs @@ -30,31 +30,39 @@ to be supplied} \item{trend_formula}{An optional \code{character} string specifying the GAM process model formula. If supplied, a linear predictor will be modelled for the latent trends to capture process model evolution separately from the observation model. Should not have a response variable specified on the left-hand side -of the formula (i.e. a valid option would be \code{~ season + s(year)}). This feature is experimental, and is only -currently available for Random Walk trend models.} +of the formula (i.e. a valid option would be \code{~ season + s(year)}). Also note that you should not use +the identifier \code{series} in this formula to specify effects that vary across time series. Instead you should use +\code{trend}. This will ensure that models in which a \code{trend_map} is supplied will still work consistently +(i.e. by allowing effects to vary across process models, even when some time series share the same underlying +process model). This feature is experimental, and is only currently available for Random Walk and AR trend models.} \item{data}{A \code{dataframe} or \code{list} containing the model response variable and covariates required by the GAM \code{formula}. Should include columns: -'series' (character or factor index of the series IDs) -'time' (numeric index of the time point for each observation). +\code{series} (a \code{factor} index of the series IDs;the number of levels should be identical +to the number of unique series labels (i.e. \code{n_series = length(levels(data$series))})) +\code{time} (\code{numeric} or \code{integer} index of the time point for each observation). Any other variables to be included in the linear predictor of \code{formula} must also be present} -\item{newdata}{Optional \code{dataframe} or \code{list} of test data containing at least 'series' and 'time' +\item{newdata}{Optional \code{dataframe} or \code{list} of test data containing at least \code{series} and \code{time} in addition to any other variables included in the linear predictor of \code{formula}. If included, the observations in variable \code{y} will be set to \code{NA} when fitting the model so that posterior simulations can be obtained} -\item{trend_model}{\code{character} specifying the time series dynamics for the latent trend. Options are: +\item{trend_model}{\code{character} or \code{function} specifying the time series dynamics for the latent trend. Options are: \itemize{ \item \code{None} (no latent trend component; i.e. the GAM component is all that contributes to the linear predictor, and the observation process is the only source of error; similarly to what is estimated by \code{\link[mgcv]{gam}}) -\item \code{RW} (random walk with possible drift) -\item \code{AR1} (with possible drift) -\item \code{AR2} (with possible drift) -\item \code{AR3} (with possible drift) -\item \code{VAR1} (with possible drift; only available in \code{Stan}) -\item \code{GP} (Gaussian Process with squared exponential kernel; -only available in \code{Stan})}} +\item \code{'RW'} or \code{RW()} +\item \code{'AR1'} or \code{AR(p = 1)} +\item \code{'AR2'} or \code{AR(p = 2)} +\item \code{'AR3'} or \code{AR(p = 3)} +\item \code{'VAR1'} or \code{VAR()}(only available in \code{Stan}) +\item \code{'GP'} (Gaussian Process with squared exponential kernel; +only available in \code{Stan})} + +For all types apart from \code{'GP'}, moving average and/or correlated +process error terms can also be estimated (for example, \code{RW(cor = TRUE)} will set up a +multivariate Random Walk if \code{n_series > 1}). See \link{mvgam_trends} for more details} \item{trend_map}{Optional \code{data.frame} specifying which series should depend on which latent trends. Useful for allowing multiple series to depend on the same latent trend process, but with @@ -63,20 +71,32 @@ different observation processes. If supplied, a latent factor model is set up by \code{series} and \code{trend}, with integer values in the \code{trend} column to state which trend each series should depend on. The \code{series} column should have a single unique entry for each series in the data (names should perfectly match factor levels of the \code{series} variable in \code{data}). See examples -in \code{\link{mvgam}} for details} +for details} \item{use_lv}{\code{logical}. If \code{TRUE}, use dynamic factors to estimate series' -latent trends in a reduced dimension format. If \code{FALSE}, estimate independent latent trends for each series} +latent trends in a reduced dimension format. Defaults to \code{FALSE}} \item{n_lv}{\code{integer} the number of latent dynamic factors to use if \code{use_lv == TRUE}. Cannot be \code{>n_series}. Defaults arbitrarily to \code{min(2, floor(n_series / 2))}} \item{family}{\code{family} specifying the exponential observation family for the series. Currently supported -families are: \code{nb()}, \code{poisson()}, \code{tweedie()}, \code{gaussian()}, \code{betar()}, \code{lognormal()}, \code{student_t()} and \code{Gamma()}} +families are: +\itemize{ +\item\code{nb()} for count data +\item\code{poisson()} for count data +\item\code{gaussian()} for real-valued data +\item\code{betar()} for proportional data on \verb{(0,1)} +\item\code{lognormal()} for non-negative real-valued data +\item\code{student_t()} for real-valued data +\item\code{Gamma()} for non-negative real-valued data} +Note that only \code{nb()} and \code{poisson()} are available if using \code{JAGS} as the backend. +Default is \code{poisson()}. +See \code{\link{mvgam_families}} for more details} \item{priors}{An optional \code{data.frame} with prior -definitions. See \code{\link{get_mvgam_priors}} and -\link{mvgam} for more information on changing default prior distributions} +definitions (in JAGS or Stan syntax). if using Stan, this can also be an object of +class \code{brmsprior} (see. \code{\link[brms]{prior}} for details). See \link{get_mvgam_priors} and +'Details' for more information on changing default prior distributions} \item{lfo}{Logical indicating whether this is part of a call to \link{lfo_cv.mvgam}. Returns a lighter version of the model with no residuals and fewer monitored parameters to speed up diff --git a/src/mvgam.dll b/src/mvgam.dll index b2557de6..ab047ba9 100644 Binary files a/src/mvgam.dll and b/src/mvgam.dll differ diff --git a/tests/testthat/Rplots.pdf b/tests/testthat/Rplots.pdf index 8dff305e..072501ea 100644 Binary files a/tests/testthat/Rplots.pdf and b/tests/testthat/Rplots.pdf differ