Arguments
- object
-A fitted mvgam model
list object returned from mvgam. See mvgam()
- formula
@@ -93,36 +93,43 @@ Argumentsgam)
-
RW (random walk with possible drift)
-
AR1 (with possible drift)
-
AR2 (with possible drift)
-
AR3 (with possible drift)
-
VAR1 (with possible drift; only available in Stan)
-
GP (Gaussian Process with squared exponential kernel;
+
'RW' or RW()
+
'AR1' or AR(p = 1)
+
'AR2' or AR(p = 2)
+
'AR3' or AR(p = 3)
+
'VAR1' or VAR()(only available in Stan)
+
'PWlogistic, 'PWlinear or PW() (only available in Stan)
+
'GP' (Gaussian Process with squared exponential kernel;
only available in Stan)
-
+
For all types apart from 'GP' and PW(), moving average and/or correlated
+process error terms can also be estimated (for example, RW(cor = TRUE) will set up a
+multivariate Random Walk if n_series > 1). See mvgam_trends for more details
trend_map
@@ -133,12 +140,12 @@
Argumentsmvgam for details
+for details
use_lv
logical. If TRUE, use dynamic factors to estimate series'
-latent trends in a reduced dimension format. If FALSE, estimate independent latent trends for each series
+latent trends in a reduced dimension format. Defaults to FALSE
n_lv
@@ -148,13 +155,23 @@ Argumentspoisson(), tweedie(), gaussian(), betar(), lognormal(), student_t() and Gamma()
+families are:nb() for count data
poisson() for count data
gaussian() for real-valued data
betar() for proportional data on (0,1)
lognormal() for non-negative real-valued data
student_t() for real-valued data
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 mvgam_families for more details
priors
An optional data.frame with prior
-definitions. See get_mvgam_priors and
-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
brmsprior (see.
prior for details). See
get_mvgam_priors and
+'Details' for more information on changing default prior distributions
lfo
diff --git a/man/piecewise_trends.Rd b/man/piecewise_trends.Rd
index 7789943a..aba9914c 100644
--- a/man/piecewise_trends.Rd
+++ b/man/piecewise_trends.Rd
@@ -65,3 +65,6 @@ transformed if you are using a \code{poisson()} or \code{nb()} family). It is th
that you specify the \code{cap} values on the scale of your outcome. Note also that
no missing values are allowed in \code{cap}.
}
+\references{
+Taylor, Sean J., and Benjamin Letham. "Forecasting at scale." The American Statistician 72.1 (2018): 37-45.
+}
diff --git a/src/RcppExports.o b/src/RcppExports.o
index 3738bd53..849c29a4 100644
Binary files a/src/RcppExports.o and b/src/RcppExports.o differ
diff --git a/src/mvgam.dll b/src/mvgam.dll
index 18c35555..82c9d40e 100644
Binary files a/src/mvgam.dll and b/src/mvgam.dll differ
diff --git a/src/trend_funs.o b/src/trend_funs.o
index 371ea49f..faf098a5 100644
Binary files a/src/trend_funs.o and b/src/trend_funs.o differ
diff --git a/vignettes/mvgam_overview.Rmd b/vignettes/mvgam_overview.Rmd
index 35f060d5..3192e5ef 100644
--- a/vignettes/mvgam_overview.Rmd
+++ b/vignettes/mvgam_overview.Rmd
@@ -107,6 +107,21 @@ z & \sim \text{MVNormal}(0, \Sigma_{error}) \\
The latent dynamic process evolves from a complex, high-dimensional Multivariate Normal distribution which depends on $\rho$ (often called the length scale parameter) to control how quickly the correlations between the model's errors decay as a function of time. For these models, covariance decays exponentially fast with the squared distance (in time) between the observations. The functions also depend on a parameter $\alpha$, which controls the marginal variability of the temporal function at all points; in other words it controls how much the GP term contributes to the linear predictor. `mvgam` capitalizes on some advances that allow GPs to be approximated using Hilbert space basis functions, which [considerably speed up computation at little cost to accuracy or prediction performance](https://link.springer.com/article/10.1007/s11222-022-10167-2){target="_blank"}.
+### Piecewise logistic and linear trends
+Modeling growth for many types of time series is often similar to modeling population growth in natural ecosystems, where there series exhibits nonlinear growth that saturates at some particular carrying capacity. The logistic trend model available in {`mvgam`} allows for a time-varying capacity $C(t)$ as well as a non-constant growth rate. Changes in the base growth rate $k$ are incorporated by explicitly defining changepoints throughout the training period where the growth rate is allowed to vary. The changepoint vector $a$ is represented as a vector of `1`s and `0`s, and the rate of growth at time $t$ is represented as $k+a(t)^T\delta$. Potential changepoints are selected uniformly across the training period, and the number of changepoints, as well as the flexibility of the potential rate changes at these changepoints, can be controlled using `trend_model = PW()`. The full piecewise logistic growth model is then:
+
+\begin{align*}
+z_t & = \frac{C_t}{1 + \exp(-(k+a(t)^T\delta)(t-(m+a(t)^T\gamma)))} \end{align*}
+
+For time series that do not appear to exhibit saturating growth, a piece-wise constant rate of growth can often provide a useful trend model. The piecewise linear trend is defined as:
+
+\begin{align*}
+z_t & = (k+a(t)^T\delta)t + (m+a(t)^T\gamma) \end{align*}
+
+In both trend models, $m$ is an offset parameter that controls the trend intercept. Because of this parameter, it is not recommended that you include an intercept in your observation formula because this will not be identifiable. You can read about the full description of piecewise linear and logistic trends [in this paper by Taylor and Letham](https://www.tandfonline.com/doi/abs/10.1080/00031305.2017.1380080){target="_blank"}.
+
+Sean J. Taylor and Benjamin Letham. "[Forecasting at scale.](https://www.tandfonline.com/doi/full/10.1080/00031305.2017.1380080)" *The American Statistician* 72.1 (2018): 37-45.
+
## Example time series data
The 'portal_data' object contains time series of rodent captures from the Portal Project, [a long-term monitoring study based near the town of Portal, Arizona](https://portal.weecology.org/){target="_blank"}. Researchers have been operating a standardized set of baited traps within 24 experimental plots at this site since the 1970's. Sampling follows the lunar monthly cycle, with observations occurring on average about 28 days apart. However, missing observations do occur due to difficulties accessing the site (weather events, COVID disruptions etc..). You can read about the full sampling protocol [in this preprint by Ernest et al on the Biorxiv](https://www.biorxiv.org/content/10.1101/332783v3.full){target="_blank"}.