diff --git a/README.Rmd b/README.Rmd index 48d2f18a..472a24ef 100644 --- a/README.Rmd +++ b/README.Rmd @@ -36,6 +36,7 @@ A series of [vignettes cover data formatting, forecasting and several extended c * [Ecological Forecasting with Dynamic Generalized Additive Models](https://www.youtube.com/watch?v=0zZopLlomsQ){target="_blank"} * [Distributed lags (and hierarchical distributed lags) using `mgcv` and `mvgam`](https://ecogambler.netlify.app/blog/distributed-lags-mgcv/){target="_blank"} +* [State-Space Vector Autoregressions in `mvgam`](https://ecogambler.netlify.app/blog/vector-autoregressions/){target="_blank"} * [Ecological Forecasting with Dynamic GAMs; a tutorial and detailed case study](https://www.youtube.com/watch?v=RwllLjgPUmM){target="_blank"} * [How to interpret and report nonlinear effects from Generalized Additive Models](https://ecogambler.netlify.app/blog/interpreting-gams/){target="_blank"} * [Phylogenetic smoothing using `mgcv`](https://ecogambler.netlify.app/blog/phylogenetic-smooths-mgcv/){target="_blank"} @@ -43,7 +44,7 @@ A series of [vignettes cover data formatting, forecasting and several extended c ## Installation Install the stable version from `CRAN` using: `install.packages('mvgam')`, or install the development version from `GitHub` using: -`devtools::install_github("nicholasjclark/mvgam")`. Note that to condition models on observed data, either `JAGS` (along with packages `rjags` and `runjags`) or `Stan` must be installed (along with either `rstan` and/or `cmdstanr`). Please refer to installation links for `JAGS` [here](https://sourceforge.net/projects/mcmc-jags/files/){target="_blank"}, for `Stan` with `rstan` [here](https://mc-stan.org/users/interfaces/rstan){target="_blank"}, or for `Stan` with `cmdstandr` [here](https://mc-stan.org/cmdstanr/){target="_blank"}. You will need a fairly recent version of `Stan` to ensure all syntax is recognized. If you see warnings such as `variable "array" does not exist`, this is usually a sign that you need to update `Stan`. +`devtools::install_github("nicholasjclark/mvgam")`. Note that to condition models on observed data, `Stan` must be installed (along with either `rstan` and/or `cmdstanr`). Please refer to installation links for `Stan` with `rstan` [here](https://mc-stan.org/users/interfaces/rstan){target="_blank"}, or for `Stan` with `cmdstandr` [here](https://mc-stan.org/cmdstanr/){target="_blank"}. We highly recommend you use `Cmdstan` through the `cmdstanr` interface. This is because `Cmdstan` is easier to install, is more up to date with new features, and uses less memory than `rstan`. See [this documentation from the `Cmdstan` team for more information](http://mc-stan.org/cmdstanr/articles/cmdstanr.html#comparison-with-rstan){target="_blank"}. @@ -54,17 +55,16 @@ When using `mvgam`, please cite the following: - Clark, N.J. and Wells, K. (2022). Dynamic Generalized Additive Models (DGAMs) for forecasting discrete ecological time series. *Methods in Ecology and Evolution*. DOI: https://doi.org/10.1111/2041-210X.13974 -As `mvgam` acts as an interface to `Stan` and `JAGS`, please additionally cite whichever software you use for parameter estimation: +As `mvgam` acts as an interface to `Stan`, please additionally cite: - Carpenter B., Gelman A., Hoffman M. D., Lee D., Goodrich B., Betancourt M., Brubaker M., Guo J., Li P., and Riddell A. (2017). Stan: A probabilistic programming language. *Journal of Statistical Software*. 76(1). 10.18637/jss.v076.i01 -- Plummer, M. (2013). JAGS: A program for analysis of Bayesian graphical models using Gibbs sampling. *Proceedings of the 3rd International Workshop on Distributed Statistical Computing*. 124(125.10). `mvgam` relies on several other `R` packages and, of course, on `R` itself. To find out how to cite R and its packages, use the `citation` function. There are -some features of `mvgam` which specifically rely on certain packages. The most important of these is the generation of data necessary to estimate smoothing splines, which entirely rely on `mgcv`. The `rstan` and `cmdstanr` packages together with `Rcpp` makes `Stan` conveniently accessible in `R`, while the `rjags` and `runjags` packages together with the `coda` package make `JAGS` accessible in `R`. If you use some of these features, please also consider citing the related packages. +some features of `mvgam` which specifically rely on certain packages. The most important of these is the generation of data necessary to estimate smoothing splines, which rely on `mgcv` and `splines2`. The `rstan` and `cmdstanr` packages together with `Rcpp` makes `Stan` conveniently accessible in `R`. If you use some of these features, please also consider citing the related packages. ## Cheatsheet [![`mvgam` usage cheatsheet](https://github.com/nicholasjclark/mvgam/raw/master/misc/mvgam_cheatsheet.png)](https://github.com/nicholasjclark/mvgam/raw/master/misc/mvgam_cheatsheet.pdf) @@ -231,14 +231,13 @@ plot(lynx_mvgam, type = 'residuals') * `binomial()` for count data with known number of trials * `beta_binomial()` for overdispersed count data with known number of trials * `nmix()` for count data with imperfect detection (unknown number of trials) -* `tweedie()` for overdispersed count data -Note that only `poisson()`, `nb()`, and `tweedie()` are available if using `JAGS`. All families, apart from `tweedie()`, are supported if using `Stan`. See `??mvgam_families` for more information. Below is a simple example for simulating and modelling proportional data with `Beta` observations over a set of seasonal series with independent Gaussian Process dynamic trends: +See `??mvgam_families` for more information. Below is a simple example for simulating and modelling proportional data with `Beta` observations over a set of seasonal series with independent Gaussian Process dynamic trends: ```{r beta_sim, message=FALSE, warning=FALSE, fig.width=6.5, fig.height=6.5, dpi=160} set.seed(100) data <- sim_mvgam(family = betar(), T = 80, - trend_model = 'GP', + trend_model = GP(), prop_trend = 0.5, seasonality = 'shared') plot_mvgam_series(data = data$data_train, series = 'all') @@ -247,7 +246,7 @@ plot_mvgam_series(data = data$data_train, series = 'all') ```{r, include=FALSE} mod <- mvgam(y ~ s(season, bs = 'cc', k = 7) + s(season, by = series, m = 1, k = 5), - trend_model = 'GP', + trend_model = GP(), data = data$data_train, newdata = data$data_test, family = betar()) @@ -256,7 +255,7 @@ mod <- mvgam(y ~ s(season, bs = 'cc', k = 7) + ```{r, eval=FALSE} mod <- mvgam(y ~ s(season, bs = 'cc', k = 7) + s(season, by = series, m = 1, k = 5), - trend_model = 'GP', + trend_model = GP(), data = data$data_train, newdata = data$data_test, family = betar()) @@ -285,10 +284,7 @@ for(i in 1:3){ } ``` -There are many more extended uses of `mvgam`, including the ability to fit hierarchical GAMs that include dynamic coefficient models, dynamic factor and Vector Autoregressive processes. See the [package documentation](https://nicholasjclark.github.io/mvgam/){target="_blank"} for more details. The package can also be used to generate all necessary data structures, initial value functions and modelling code necessary to fit DGAMs using `Stan` or `JAGS`. This can be helpful if users wish to make changes to the model to better suit their own bespoke research / analysis goals. The following resources can be helpful to troubleshoot: - -* [Stan Discourse](https://discourse.mc-stan.org/){target="_blank"} -* [JAGS Discourse](https://sourceforge.net/projects/mcmc-jags/){target="_blank"} +There are many more extended uses of `mvgam`, including the ability to fit hierarchical State-Space GAMs that include dynamic coefficient models, dynamic factors and Vector Autoregressive processes. See the [package documentation](https://nicholasjclark.github.io/mvgam/){target="_blank"} for more details. The package can also be used to generate all necessary data structures, initial value functions and modelling code necessary to fit DGAMs using `Stan`. This can be helpful if users wish to make changes to the model to better suit their own bespoke research / analysis goals. The [Stan Discourse](https://discourse.mc-stan.org/){target="_blank"} is a helpful place to troubleshoot. ## License This project is licensed under an `MIT` open source license diff --git a/README.md b/README.md index 82f80e6c..c1519663 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,9 @@ been compiled: - Distributed lags (and hierarchical distributed lags) using mgcv and mvgam +- State-Space Vector Autoregressions in + mvgam - Ecological Forecasting with Dynamic GAMs; a tutorial and detailed case study @@ -59,18 +62,12 @@ been compiled: Install the stable version from `CRAN` using: `install.packages('mvgam')`, or install the development version from `GitHub` using: `devtools::install_github("nicholasjclark/mvgam")`. Note -that to condition models on observed data, either `JAGS` (along with -packages `rjags` and `runjags`) or `Stan` must be installed (along with -either `rstan` and/or `cmdstanr`). Please refer to installation links -for `JAGS` here, for `Stan` with `rstan` +that to condition models on observed data, `Stan` must be installed +(along with either `rstan` and/or `cmdstanr`). Please refer to +installation links for `Stan` with `rstan` here, or for `Stan` with `cmdstandr` -here. You -will need a fairly recent version of `Stan` to ensure all syntax is -recognized. If you see warnings such as -`variable "array" does not exist`, this is usually a sign that you need -to update `Stan`. +here. We highly recommend you use `Cmdstan` through the `cmdstanr` interface. This is because `Cmdstan` is easier to install, is more up to date with @@ -93,27 +90,21 @@ When using `mvgam`, please cite the following: (DGAMs) for forecasting discrete ecological time series. *Methods in Ecology and Evolution*. DOI: -As `mvgam` acts as an interface to `Stan` and `JAGS`, please -additionally cite whichever software you use for parameter estimation: +As `mvgam` acts as an interface to `Stan`, please additionally cite: - Carpenter B., Gelman A., Hoffman M. D., Lee D., Goodrich B., Betancourt M., Brubaker M., Guo J., Li P., and Riddell A. (2017). Stan: A probabilistic programming language. *Journal of Statistical Software*. 76(1). 10.18637/jss.v076.i01 -- Plummer, M. (2013). JAGS: A program for analysis of Bayesian graphical - models using Gibbs sampling. *Proceedings of the 3rd International - Workshop on Distributed Statistical Computing*. 124(125.10). `mvgam` relies on several other `R` packages and, of course, on `R` itself. To find out how to cite R and its packages, use the `citation` function. There are some features of `mvgam` which specifically rely on certain packages. The most important of these is the generation of data -necessary to estimate smoothing splines, which entirely rely on `mgcv`. -The `rstan` and `cmdstanr` packages together with `Rcpp` makes `Stan` -conveniently accessible in `R`, while the `rjags` and `runjags` packages -together with the `coda` package make `JAGS` accessible in `R`. If you -use some of these features, please also consider citing the related -packages. +necessary to estimate smoothing splines, which rely on `mgcv` and +`splines2`. The `rstan` and `cmdstanr` packages together with `Rcpp` +makes `Stan` conveniently accessible in `R`. If you use some of these +features, please also consider citing the related packages. ## Cheatsheet @@ -235,28 +226,28 @@ summary(lynx_mvgam) #> #> GAM coefficient (beta) estimates: #> 2.5% 50% 97.5% Rhat n_eff -#> (Intercept) 6.400 6.60 6.900 1 1043 -#> s(season).1 -0.610 -0.12 0.380 1 1109 -#> s(season).2 0.740 1.30 1.900 1 930 -#> s(season).3 1.200 1.90 2.600 1 846 -#> s(season).4 -0.017 0.55 1.100 1 845 -#> s(season).5 -1.300 -0.69 -0.069 1 1103 -#> s(season).6 -1.300 -0.56 0.120 1 1057 -#> s(season).7 0.035 0.71 1.400 1 1061 -#> s(season).8 0.620 1.40 2.100 1 816 -#> s(season).9 -0.410 0.21 0.840 1 736 -#> s(season).10 -1.300 -0.86 -0.400 1 1225 +#> (Intercept) 6.400 6.60 6.900 1.00 910 +#> s(season).1 -0.640 -0.13 0.360 1.00 1169 +#> s(season).2 0.760 1.40 1.900 1.01 850 +#> s(season).3 1.300 1.90 2.500 1.01 953 +#> s(season).4 -0.018 0.55 1.200 1.00 1102 +#> s(season).5 -1.300 -0.70 -0.069 1.00 1019 +#> s(season).6 -1.200 -0.56 0.093 1.00 1011 +#> s(season).7 0.039 0.73 1.400 1.00 1006 +#> s(season).8 0.580 1.40 2.200 1.00 1041 +#> s(season).9 -0.360 0.23 0.820 1.00 735 +#> s(season).10 -1.400 -0.88 -0.380 1.00 908 #> #> Approximate significance of GAM smooths: #> edf Ref.df Chi.sq p-value -#> s(season) 9.98 10 47 <2e-16 *** +#> s(season) 9.99 10 48.3 <2e-16 *** #> --- #> Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1 #> #> Latent trend parameter AR estimates: #> 2.5% 50% 97.5% Rhat n_eff -#> ar1[1] 0.58 0.83 0.98 1.01 583 -#> sigma[1] 0.38 0.48 0.61 1.00 646 +#> ar1[1] 0.60 0.83 0.98 1 592 +#> sigma[1] 0.39 0.48 0.60 1 855 #> #> Stan MCMC diagnostics: #> n_eff / iter looks reasonable for all parameters @@ -265,7 +256,7 @@ summary(lynx_mvgam) #> 0 of 2000 iterations saturated the maximum tree depth of 12 (0%) #> E-FMI indicated no pathological behavior #> -#> Samples were drawn using NUTS(diag_e) at Thu Sep 19 11:37:30 AM 2024. +#> Samples were drawn using NUTS(diag_e) at Mon Sep 30 3:06:32 PM 2024. #> For each parameter, n_eff is a crude measure of effective sample size, #> and Rhat is the potential scale reduction factor on split MCMC chains #> (at convergence, Rhat = 1) @@ -402,7 +393,7 @@ series (testing and training) ``` r plot(lynx_mvgam, type = 'forecast', newdata = lynx_test) #> Out of sample DRPS: -#> 2434.43508625 +#> 2398.60613875 ``` Plotting forecast distributions using mvgam in R @@ -468,20 +459,17 @@ families. Currently, the package can handle data for the following: trials - `nmix()` for count data with imperfect detection (unknown number of trials) -- `tweedie()` for overdispersed count data -Note that only `poisson()`, `nb()`, and `tweedie()` are available if -using `JAGS`. All families, apart from `tweedie()`, are supported if -using `Stan`. See `??mvgam_families` for more information. Below is a -simple example for simulating and modelling proportional data with -`Beta` observations over a set of seasonal series with independent -Gaussian Process dynamic trends: +See `??mvgam_families` for more information. Below is a simple example +for simulating and modelling proportional data with `Beta` observations +over a set of seasonal series with independent Gaussian Process dynamic +trends: ``` r set.seed(100) data <- sim_mvgam(family = betar(), T = 80, - trend_model = 'GP', + trend_model = GP(), prop_trend = 0.5, seasonality = 'shared') plot_mvgam_series(data = data$data_train, series = 'all') @@ -492,7 +480,7 @@ plot_mvgam_series(data = data$data_train, series = 'all') ``` r mod <- mvgam(y ~ s(season, bs = 'cc', k = 7) + s(season, by = series, m = 1, k = 5), - trend_model = 'GP', + trend_model = GP(), data = data$data_train, newdata = data$data_test, family = betar()) @@ -516,7 +504,7 @@ summary(mod, include_betas = FALSE) #> logit #> #> Trend model: -#> GP +#> GP() #> #> N series: #> 3 @@ -566,7 +554,7 @@ summary(mod, include_betas = FALSE) #> 0 of 2000 iterations saturated the maximum tree depth of 12 (0%) #> E-FMI indicated no pathological behavior #> -#> Samples were drawn using NUTS(diag_e) at Thu Sep 19 11:38:16 AM 2024. +#> Samples were drawn using NUTS(diag_e) at Mon Sep 30 3:07:18 PM 2024. #> For each parameter, n_eff is a crude measure of effective sample size, #> and Rhat is the potential scale reduction factor on split MCMC chains #> (at convergence, Rhat = 1) @@ -584,20 +572,16 @@ for(i in 1:3){ There are many more extended uses of `mvgam`, including the ability to -fit hierarchical GAMs that include dynamic coefficient models, dynamic -factor and Vector Autoregressive processes. See the +fit hierarchical State-Space GAMs that include dynamic coefficient +models, dynamic factors and Vector Autoregressive processes. See the package documentation for more details. The package can also be used to generate all necessary data structures, initial -value functions and modelling code necessary to fit DGAMs using `Stan` -or `JAGS`. This can be helpful if users wish to make changes to the -model to better suit their own bespoke research / analysis goals. The -following resources can be helpful to troubleshoot: - -- Stan - Discourse -- JAGS Discourse +value functions and modelling code necessary to fit DGAMs using `Stan`. +This can be helpful if users wish to make changes to the model to better +suit their own bespoke research / analysis goals. The +Stan +Discourse is a helpful place to troubleshoot. ## License diff --git a/docs/authors.html b/docs/authors.html index f7444199..b8909014 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -68,7 +68,7 @@

Authors

Citation

Source: inst/CITATION

-

Clark & Wells (2021). Dynamic Generalized Additive Models (DGAMs) for forecasting discrete ecological time series. Methods in Ecology and Evolution, 14, 771-784. doi.org/10.1111/2041-210X.13974

+

Clark & Wells (2022). Dynamic Generalized Additive Models (DGAMs) for forecasting discrete ecological time series. Methods in Ecology and Evolution, 14, 771-784. doi.org/10.1111/2041-210X.13974

@Article{,
   title = {Dynamic Generalized Additive Models (DGAMs) for forecasting discrete ecological time series},
   author = {Nicholas J Clark and Konstans Wells},
diff --git a/docs/index.html b/docs/index.html
index a7c17548..6bd2d00d 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -78,12 +78,12 @@
 

mvgam

MultiVariate (Dynamic) Generalized Addivite Models

-

The goal of mvgam is to use a Bayesian framework to estimate parameters of Dynamic Generalized Additive Models (DGAMs) for time series with dynamic trend components. The package provides an interface to fit Bayesian DGAMs using either JAGS or Stan as the backend, but note that users are strongly encouraged to opt for Stan over JAGS. The formula syntax is based on that of the package mgcv to provide a familiar GAM modelling interface. The motivation for the package and some of its primary objectives are described in detail by Clark & Wells 2022 (published in Methods in Ecology and Evolution). An introduction to the package and some worked examples are shown in this seminar: Ecological Forecasting with Dynamic Generalized Additive Models.

+

The goal of mvgam is to use a Bayesian framework to estimate parameters of Dynamic Generalized Additive Models (DGAMs) for time series with dynamic trend components. The package provides an interface to fit Bayesian DGAMs using Stan as the backend. The formula syntax is based on that of the package mgcv to provide a familiar GAM modelling interface. The motivation for the package and some of its primary objectives are described in detail by Clark & Wells 2022 (published in Methods in Ecology and Evolution). An introduction to the package and some worked examples are shown in this seminar: Ecological Forecasting with Dynamic Generalized Additive Models.

Installation

-

Install the stable version from CRAN using: install.packages('mvgam'), or install the development version from GitHub using: devtools::install_github("nicholasjclark/mvgam"). Note that to actually condition models with MCMC sampling, either the JAGS software must be installed (along with the R packages rjags and runjags) or the Stan software must be installed (along with either rstan and/or cmdstanr). Only rstan is listed as a dependency of mvgam to ensure that installation is less difficult. If users wish to fit the models using mvgam, please refer to installation links for JAGS here, for Stan with rstan here, or for Stan with cmdstandr here. You will need a fairly recent version of Stan (preferably 2.29 or above) to ensure all the model syntax is recognized. We highly recommend you use Cmdstan through the cmdstanr interface as the backend. This is because Cmdstan is easier to install, is more up to date with new features, and uses less memory than Rstan. See this documentation from the Cmdstan team for more information.

+

Install the stable version from CRAN using: install.packages('mvgam'), or install the development version from GitHub using: devtools::install_github("nicholasjclark/mvgam"). Note that to actually condition models with MCMC sampling, the Stan software must be installed (along with either rstan and/or cmdstanr). Only rstan is listed as a dependency of mvgam to ensure that installation is less difficult. If users wish to fit the models using mvgam, please refer to installation links for Stan with rstan here, or for Stan with cmdstandr here. You will need a fairly recent version of Stan (preferably 2.29 or above) to ensure all the model syntax is recognized. We highly recommend you use Cmdstan through the cmdstanr interface as the backend. This is because Cmdstan is easier to install, is more up to date with new features, and uses less memory than Rstan. See this documentation from the Cmdstan team for more information.

Introductory seminar @@ -110,14 +110,14 @@

Getting started student_t() for heavy-tailed real-valued data
  • -lognormal() for non-negative real-valued data
  • +lognormal() for non-negative real-valued data
  • Gamma() for non-negative real-valued data
  • betar() for proportional data on (0,1)
  • -bernoulli() for binary data
  • +bernoulli() for binary data
  • poisson() for count data
  • @@ -125,13 +125,11 @@

    Getting started binomial() for count data with known number of trials

  • -beta_binomial() for overdispersed count data with known number of trials
  • +beta_binomial() for overdispersed count data with known number of trials
  • nmix() for count data with imperfect detection (unknown number of trials)
  • -
  • -tweedie() for overdispersed count data
  • -

    Note that only poisson(), nb(), and tweedie() are available if using JAGS. All families, apart from tweedie(), are supported if using Stan. See ??mvgam_families for more information. Below is a simple example for simulating and modelling proportional data with Beta observations over a set of seasonal series with independent Gaussian Process dynamic trends:

    +

    See ??mvgam_families for more information. Below is a simple example for simulating and modelling proportional data with Beta observations over a set of seasonal series with independent Gaussian Process dynamic trends:

     data <- sim_mvgam(family = betar(),
                       T = 80,
    @@ -145,8 +143,8 @@ 

    Getting started

    Fit a DGAM to these series that uses a hierarchical cyclic seasonal smooth term to capture variation in seasonality among series. The model also includes series-specific latent Gaussian Processes with squared exponential covariance functions to capture temporal dynamics

    -mod <- mvgam(y ~ s(season, bs = 'cc', k = 7) +
    -               s(season, by = series, m = 1, k = 5),
    +mod <- mvgam(y ~ s(season, bs = 'cc', k = 7) +
    +               s(season, by = series, m = 1, k = 5),
                  trend_model = GP(),
                  data = data$data_train,
                  newdata = data$data_test,
    @@ -172,16 +170,13 @@ 

    Other resourcesA number of case studies have been compiled to highlight how GAMs and DGAMs can be useful for working with time series data:

    -

    The package can also be used to generate all necessary data structures, initial value functions and modelling code necessary to fit DGAMs using Stan or JAGS. This can be helpful if users wish to make changes to the model to better suit their own bespoke research / analysis goals. The following resources can be helpful to troubleshoot:

    - +

    The package can also be used to generate all necessary data structures, initial value functions and modelling code necessary to fit DGAMs using Stan. This can be helpful if users wish to make changes to the model to better suit their own bespoke research / analysis goals.

    Interested in contributing? diff --git a/docs/reference/figures/README-beta_fc-1.png b/docs/reference/figures/README-beta_fc-1.png index 981099a5..ce3cd414 100644 Binary files a/docs/reference/figures/README-beta_fc-1.png and b/docs/reference/figures/README-beta_fc-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-12-1.png b/docs/reference/figures/README-unnamed-chunk-12-1.png index e3a0b6ab..22d526ad 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-12-1.png and b/docs/reference/figures/README-unnamed-chunk-12-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-13-1.png b/docs/reference/figures/README-unnamed-chunk-13-1.png index d046d092..52c9a7b5 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-13-1.png and b/docs/reference/figures/README-unnamed-chunk-13-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-14-1.png b/docs/reference/figures/README-unnamed-chunk-14-1.png index 69060a98..a4ba74fd 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-14-1.png and b/docs/reference/figures/README-unnamed-chunk-14-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-15-1.png b/docs/reference/figures/README-unnamed-chunk-15-1.png index 046c21bf..6a61fd8f 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-15-1.png and b/docs/reference/figures/README-unnamed-chunk-15-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-16-1.png b/docs/reference/figures/README-unnamed-chunk-16-1.png index bb33b48b..9d40c8f5 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-16-1.png and b/docs/reference/figures/README-unnamed-chunk-16-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-17-1.png b/docs/reference/figures/README-unnamed-chunk-17-1.png index 2c727472..4fe24996 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-17-1.png and b/docs/reference/figures/README-unnamed-chunk-17-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-18-1.png b/docs/reference/figures/README-unnamed-chunk-18-1.png index 20f53733..7fae3eaa 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-18-1.png and b/docs/reference/figures/README-unnamed-chunk-18-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-19-1.png b/docs/reference/figures/README-unnamed-chunk-19-1.png index 0ffe82a9..1a4a6698 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-19-1.png and b/docs/reference/figures/README-unnamed-chunk-19-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-20-1.png b/docs/reference/figures/README-unnamed-chunk-20-1.png index 5dca98be..85cc3201 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-20-1.png and b/docs/reference/figures/README-unnamed-chunk-20-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-21-1.png b/docs/reference/figures/README-unnamed-chunk-21-1.png index 0147b2f1..f567beab 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-21-1.png and b/docs/reference/figures/README-unnamed-chunk-21-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-22-1.png b/docs/reference/figures/README-unnamed-chunk-22-1.png index 23160dff..3a595e9e 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-22-1.png and b/docs/reference/figures/README-unnamed-chunk-22-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-23-1.png b/docs/reference/figures/README-unnamed-chunk-23-1.png index 1f660ff7..db66b595 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-23-1.png and b/docs/reference/figures/README-unnamed-chunk-23-1.png differ diff --git a/docs/reference/figures/README-unnamed-chunk-24-1.png b/docs/reference/figures/README-unnamed-chunk-24-1.png index b9708f8a..113a91bd 100644 Binary files a/docs/reference/figures/README-unnamed-chunk-24-1.png and b/docs/reference/figures/README-unnamed-chunk-24-1.png differ diff --git a/index.Rmd b/index.Rmd index a6950013..b65ae73c 100644 --- a/index.Rmd +++ b/index.Rmd @@ -10,11 +10,11 @@ always_allow_html: true ## mvgam **M**ulti**V**ariate (Dynamic) **G**eneralized **A**ddivite **M**odels -The goal of `mvgam` is to use a Bayesian framework to estimate parameters of Dynamic Generalized Additive Models (DGAMs) for time series with dynamic trend components. The package provides an interface to fit Bayesian DGAMs using either `JAGS` or `Stan` as the backend, but note that users are strongly encouraged to opt for `Stan` over `JAGS`. The formula syntax is based on that of the package `mgcv` to provide a familiar GAM modelling interface. The motivation for the package and some of its primary objectives are described in detail by [Clark & Wells 2022](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.13974) (published in *Methods in Ecology and Evolution*). An introduction to the package and some worked examples are shown in this seminar: [Ecological Forecasting with Dynamic Generalized Additive Models](https://www.youtube.com/watch?v=0zZopLlomsQ){target="_blank"}. +The goal of `mvgam` is to use a Bayesian framework to estimate parameters of Dynamic Generalized Additive Models (DGAMs) for time series with dynamic trend components. The package provides an interface to fit Bayesian DGAMs using `Stan` as the backend. The formula syntax is based on that of the package `mgcv` to provide a familiar GAM modelling interface. The motivation for the package and some of its primary objectives are described in detail by [Clark & Wells 2022](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.13974) (published in *Methods in Ecology and Evolution*). An introduction to the package and some worked examples are shown in this seminar: [Ecological Forecasting with Dynamic Generalized Additive Models](https://www.youtube.com/watch?v=0zZopLlomsQ){target="_blank"}. ## Installation Install the stable version from CRAN using: `install.packages('mvgam')`, or install the development version from `GitHub` using: -`devtools::install_github("nicholasjclark/mvgam")`. Note that to actually condition models with MCMC sampling, either the `JAGS` software must be installed (along with the `R` packages `rjags` and `runjags`) or the `Stan` software must be installed (along with either `rstan` and/or `cmdstanr`). Only `rstan` is listed as a dependency of `mvgam` to ensure that installation is less difficult. If users wish to fit the models using `mvgam`, please refer to installation links for `JAGS` [here](https://sourceforge.net/projects/mcmc-jags/files/), for `Stan` with `rstan` [here](https://mc-stan.org/users/interfaces/rstan), or for `Stan` with `cmdstandr` [here](https://mc-stan.org/cmdstanr/). You will need a fairly recent version of `Stan` (preferably 2.29 or above) to ensure all the model syntax is recognized. We highly recommend you use `Cmdstan` through the `cmdstanr` interface as the backend. This is because `Cmdstan` is easier to install, is more up to date with new features, and uses less memory than `Rstan`. See [this documentation from the `Cmdstan` team for more information](http://mc-stan.org/cmdstanr/articles/cmdstanr.html#comparison-with-rstan). +`devtools::install_github("nicholasjclark/mvgam")`. Note that to actually condition models with MCMC sampling, the `Stan` software must be installed (along with either `rstan` and/or `cmdstanr`). Only `rstan` is listed as a dependency of `mvgam` to ensure that installation is less difficult. If users wish to fit the models using `mvgam`, please refer to installation links for `Stan` with `rstan` [here](https://mc-stan.org/users/interfaces/rstan), or for `Stan` with `cmdstandr` [here](https://mc-stan.org/cmdstanr/). You will need a fairly recent version of `Stan` (preferably 2.29 or above) to ensure all the model syntax is recognized. We highly recommend you use `Cmdstan` through the `cmdstanr` interface as the backend. This is because `Cmdstan` is easier to install, is more up to date with new features, and uses less memory than `Rstan`. See [this documentation from the `Cmdstan` team for more information](http://mc-stan.org/cmdstanr/articles/cmdstanr.html#comparison-with-rstan). ## Introductory seminar ```{r echo=FALSE} @@ -38,9 +38,8 @@ vembedr::embed_url("https://www.youtube.com/watch?v=0zZopLlomsQ") * `binomial()` for count data with known number of trials * `beta_binomial()` for overdispersed count data with known number of trials * `nmix()` for count data with imperfect detection (unknown number of trials) -* `tweedie()` for overdispersed count data -Note that only `poisson()`, `nb()`, and `tweedie()` are available if using `JAGS`. All families, apart from `tweedie()`, are supported if using `Stan`. See `??mvgam_families` for more information. Below is a simple example for simulating and modelling proportional data with `Beta` observations over a set of seasonal series with independent Gaussian Process dynamic trends: +See `??mvgam_families` for more information. Below is a simple example for simulating and modelling proportional data with `Beta` observations over a set of seasonal series with independent Gaussian Process dynamic trends: ```{r, include = FALSE} library(mvgam) ``` @@ -88,15 +87,13 @@ You can set `build_vignettes = TRUE` when installing with either `devtools::inst A number of case studies have been compiled to highlight how GAMs and DGAMs can be useful for working with time series data: * [Ecological Forecasting with Dynamic Generalized Additive Models](https://www.youtube.com/watch?v=0zZopLlomsQ){target="_blank"} +* [State-Space Vector Autoregressions in `mvgam`](https://ecogambler.netlify.app/blog/vector-autoregressions/){target="_blank"} * [How to interpret and report nonlinear effects from Generalized Additive Models](https://ecogambler.netlify.app/blog/interpreting-gams/){target="_blank"} * [Phylogenetic smoothing using mgcv](https://ecogambler.netlify.app/blog/phylogenetic-smooths-mgcv/){target="_blank"} * [Distributed lags (and hierarchical distributed lags) using mgcv and mvgam](https://ecogambler.netlify.app/blog/distributed-lags-mgcv/){target="_blank"} * [Incorporating time-varying seasonality in forecast models](https://ecogambler.netlify.app/blog/time-varying-seasonality/){target="_blank"} -The package can also be used to generate all necessary data structures, initial value functions and modelling code necessary to fit DGAMs using `Stan` or `JAGS`. This can be helpful if users wish to make changes to the model to better suit their own bespoke research / analysis goals. The following resources can be helpful to troubleshoot: - -* [Stan Discourse](https://discourse.mc-stan.org/) -* [JAGS Discourse](https://sourceforge.net/projects/mcmc-jags/) +The package can also be used to generate all necessary data structures, initial value functions and modelling code necessary to fit DGAMs using `Stan`. This can be helpful if users wish to make changes to the model to better suit their own bespoke research / analysis goals. ## Interested in contributing? I'm actively seeking PhD students and other researchers to work in the areas of ecological forecasting, multivariate model evaluation and development of `mvgam`. Please reach out if you are interested (n.clark'at'uq.edu.au) diff --git a/index.md b/index.md index a9fce30b..51e21c8c 100644 --- a/index.md +++ b/index.md @@ -10,11 +10,10 @@ The goal of `mvgam` is to use a Bayesian framework to estimate parameters of Dynamic Generalized Additive Models (DGAMs) for time series with dynamic trend components. The package provides an interface -to fit Bayesian DGAMs using either `JAGS` or `Stan` as the backend, but -note that users are strongly encouraged to opt for `Stan` over `JAGS`. -The formula syntax is based on that of the package `mgcv` to provide a -familiar GAM modelling interface. The motivation for the package and -some of its primary objectives are described in detail by [Clark & Wells +to fit Bayesian DGAMs using `Stan` as the backend. The formula syntax is +based on that of the package `mgcv` to provide a familiar GAM modelling +interface. The motivation for the package and some of its primary +objectives are described in detail by [Clark & Wells 2022](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.13974) (published in *Methods in Ecology and Evolution*). An introduction to the package and some worked examples are shown in this seminar: @@ -27,21 +26,19 @@ Models. Install the stable version from CRAN using: `install.packages('mvgam')`, or install the development version from `GitHub` using: `devtools::install_github("nicholasjclark/mvgam")`. Note that to -actually condition models with MCMC sampling, either the `JAGS` software -must be installed (along with the `R` packages `rjags` and `runjags`) or -the `Stan` software must be installed (along with either `rstan` and/or -`cmdstanr`). Only `rstan` is listed as a dependency of `mvgam` to ensure -that installation is less difficult. If users wish to fit the models -using `mvgam`, please refer to installation links for `JAGS` -[here](https://sourceforge.net/projects/mcmc-jags/files/), for `Stan` -with `rstan` [here](https://mc-stan.org/users/interfaces/rstan), or for -`Stan` with `cmdstandr` [here](https://mc-stan.org/cmdstanr/). You will -need a fairly recent version of `Stan` (preferably 2.29 or above) to -ensure all the model syntax is recognized. We highly recommend you use -`Cmdstan` through the `cmdstanr` interface as the backend. This is -because `Cmdstan` is easier to install, is more up to date with new -features, and uses less memory than `Rstan`. See [this documentation -from the `Cmdstan` team for more +actually condition models with MCMC sampling, the `Stan` software must +be installed (along with either `rstan` and/or `cmdstanr`). Only `rstan` +is listed as a dependency of `mvgam` to ensure that installation is less +difficult. If users wish to fit the models using `mvgam`, please refer +to installation links for `Stan` with `rstan` +[here](https://mc-stan.org/users/interfaces/rstan), or for `Stan` with +`cmdstandr` [here](https://mc-stan.org/cmdstanr/). You will need a +fairly recent version of `Stan` (preferably 2.29 or above) to ensure all +the model syntax is recognized. We highly recommend you use `Cmdstan` +through the `cmdstanr` interface as the backend. This is because +`Cmdstan` is easier to install, is more up to date with new features, +and uses less memory than `Rstan`. See [this documentation from the +`Cmdstan` team for more information](http://mc-stan.org/cmdstanr/articles/cmdstanr.html#comparison-with-rstan). ## Introductory seminar @@ -79,14 +76,11 @@ package can handle data for the following families: trials - `nmix()` for count data with imperfect detection (unknown number of trials) -- `tweedie()` for overdispersed count data -Note that only `poisson()`, `nb()`, and `tweedie()` are available if -using `JAGS`. All families, apart from `tweedie()`, are supported if -using `Stan`. See `??mvgam_families` for more information. Below is a -simple example for simulating and modelling proportional data with -`Beta` observations over a set of seasonal series with independent -Gaussian Process dynamic trends: +See `??mvgam_families` for more information. Below is a simple example +for simulating and modelling proportional data with `Beta` observations +over a set of seasonal series with independent Gaussian Process dynamic +trends: ``` r data <- sim_mvgam(family = betar(), @@ -161,6 +155,9 @@ DGAMs can be useful for working with time series data: - Ecological Forecasting with Dynamic Generalized Additive Models +- State-Space Vector Autoregressions in + mvgam - How to interpret and report nonlinear effects from Generalized Additive Models @@ -175,12 +172,8 @@ DGAMs can be useful for working with time series data: The package can also be used to generate all necessary data structures, initial value functions and modelling code necessary to fit DGAMs using -`Stan` or `JAGS`. This can be helpful if users wish to make changes to -the model to better suit their own bespoke research / analysis goals. -The following resources can be helpful to troubleshoot: - -- [Stan Discourse](https://discourse.mc-stan.org/) -- [JAGS Discourse](https://sourceforge.net/projects/mcmc-jags/) +`Stan`. This can be helpful if users wish to make changes to the model +to better suit their own bespoke research / analysis goals. ## Interested in contributing? diff --git a/man/figures/README-unnamed-chunk-12-1.png b/man/figures/README-unnamed-chunk-12-1.png index c0d4af7e..22d526ad 100644 Binary files a/man/figures/README-unnamed-chunk-12-1.png and b/man/figures/README-unnamed-chunk-12-1.png differ diff --git a/man/figures/README-unnamed-chunk-13-1.png b/man/figures/README-unnamed-chunk-13-1.png index e884bf29..52c9a7b5 100644 Binary files a/man/figures/README-unnamed-chunk-13-1.png and b/man/figures/README-unnamed-chunk-13-1.png differ diff --git a/man/figures/README-unnamed-chunk-14-1.png b/man/figures/README-unnamed-chunk-14-1.png index bf894ac2..a4ba74fd 100644 Binary files a/man/figures/README-unnamed-chunk-14-1.png and b/man/figures/README-unnamed-chunk-14-1.png differ diff --git a/man/figures/README-unnamed-chunk-15-1.png b/man/figures/README-unnamed-chunk-15-1.png index 0c2d68b2..6a61fd8f 100644 Binary files a/man/figures/README-unnamed-chunk-15-1.png and b/man/figures/README-unnamed-chunk-15-1.png differ diff --git a/man/figures/README-unnamed-chunk-16-1.png b/man/figures/README-unnamed-chunk-16-1.png index a58ec57e..9d40c8f5 100644 Binary files a/man/figures/README-unnamed-chunk-16-1.png and b/man/figures/README-unnamed-chunk-16-1.png differ diff --git a/man/figures/README-unnamed-chunk-17-1.png b/man/figures/README-unnamed-chunk-17-1.png index 51e001d6..4fe24996 100644 Binary files a/man/figures/README-unnamed-chunk-17-1.png and b/man/figures/README-unnamed-chunk-17-1.png differ diff --git a/man/figures/README-unnamed-chunk-18-1.png b/man/figures/README-unnamed-chunk-18-1.png index 8c67708d..7fae3eaa 100644 Binary files a/man/figures/README-unnamed-chunk-18-1.png and b/man/figures/README-unnamed-chunk-18-1.png differ diff --git a/man/figures/README-unnamed-chunk-19-1.png b/man/figures/README-unnamed-chunk-19-1.png index d6c40c1d..1a4a6698 100644 Binary files a/man/figures/README-unnamed-chunk-19-1.png and b/man/figures/README-unnamed-chunk-19-1.png differ diff --git a/man/figures/README-unnamed-chunk-20-1.png b/man/figures/README-unnamed-chunk-20-1.png index 10b77250..85cc3201 100644 Binary files a/man/figures/README-unnamed-chunk-20-1.png and b/man/figures/README-unnamed-chunk-20-1.png differ diff --git a/man/figures/README-unnamed-chunk-21-1.png b/man/figures/README-unnamed-chunk-21-1.png index 69fdc444..f567beab 100644 Binary files a/man/figures/README-unnamed-chunk-21-1.png and b/man/figures/README-unnamed-chunk-21-1.png differ diff --git a/man/figures/README-unnamed-chunk-22-1.png b/man/figures/README-unnamed-chunk-22-1.png index c2015c03..3a595e9e 100644 Binary files a/man/figures/README-unnamed-chunk-22-1.png and b/man/figures/README-unnamed-chunk-22-1.png differ diff --git a/man/figures/README-unnamed-chunk-23-1.png b/man/figures/README-unnamed-chunk-23-1.png index d445eabf..db66b595 100644 Binary files a/man/figures/README-unnamed-chunk-23-1.png and b/man/figures/README-unnamed-chunk-23-1.png differ diff --git a/man/figures/README-unnamed-chunk-24-1.png b/man/figures/README-unnamed-chunk-24-1.png index 55b8a6ee..113a91bd 100644 Binary files a/man/figures/README-unnamed-chunk-24-1.png and b/man/figures/README-unnamed-chunk-24-1.png differ