Quarto vignettes instead of R/Markdown (#7)

* move .Rmd vignettes to .qmd, change vignette builder engine, exclude all vignettes except gamlss2.qmd from building the package

* avoid evaluation of topmodels code chunk, need to make sure that this is installed in GHA first

* disable evaluation of last code chunk (incomplete library call, st_read does not work)

---------

Co-authored-by: Nikolaus Umlauf <[email protected]>

.Rbuildignore

@@ -1,7 +1,7 @@
-R/GA.R
-inst/tests.qmd
-inst/SGT.R
-inst/OpenTopics.qmd
+^R/GA\.R$
+^inst/tests\.qmd$
+^inst/SGT\.R$
+^inst/OpenTopics\.qmd$
 token
 README.qmd
 .github
@@ -10,3 +10,10 @@ README.qmd
 ^docs$
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^\.Rproj\.user$
+^vignettes/families\.qmd$
+^vignettes/random\.qmd$
+^vignettes/s_pb\.qmd$
+^vignettes/selection\.qmd$
+^vignettes/spatial\.qmd$
+^vignettes/topmodels\.qmd$

DESCRIPTION

@@ -19,7 +19,6 @@ URL: https://gamlss-dev.github.io/gamlss2/
 BugReports: https://github.com/gamlss-dev/gamlss2/issues
 Depends: R (>= 4.1.0), gamlss.dist, mgcv
 Imports: parallel, Formula, mvtnorm
-Suggests: gamlss, gamlss.data, colorspace, ggplot2, knitr, scoringRules, partykit, Matrix, nnet, lattice, rpart, distributions3, nlme, sf, spdep
+Suggests: gamlss, gamlss.data, colorspace, ggplot2, quarto, scoringRules, partykit, Matrix, nnet, lattice, rpart, distributions3, nlme, sf, spdep
 LazyLoad: yes
-VignetteBuilder: knitr
-
+VignetteBuilder: quarto

README.md

@@ -33,12 +33,12 @@ any type of model using these new infrastructures, making the package
 highly flexible and accommodating to a wide range of modeling
 requirements.
 
-- The main model function is `gamlss2()`.
-- The default optimizer functions is `RS()`. Optimizer functions can be
-  exchanged.
-- Most important methods: `summary()`, `plot()`, `predict()`.
-- Easy development of new family objects, see `?family.gamlss2`.
-- User-specific “special” terms are possible, see `?special_terms`.
+-   The main model function is `gamlss2()`.
+-   The default optimizer functions is `RS()`. Optimizer functions can
+    be exchanged.
+-   Most important methods: `summary()`, `plot()`, `predict()`.
+-   Easy development of new family objects, see `?family.gamlss2`.
+-   User-specific “special” terms are possible, see `?special_terms`.
 
 For examples, please visit the manual pages.
 

vignettes/families.Rmd → vignettes/families.qmd

@@ -1,16 +1,16 @@
 ---
 title: "Family Objects"
-output:
-  html_document:
+format: 
+  html:
+    html-math-method: mathjax
     toc: true
-    toc_float: true
-    theme: flatly
+    number-sections: true
 bibliography: gamlss2.bib
 nocite: |
   @Rigby+Stasinopoulos:2005
 vignette: >
   %\VignetteIndexEntry{Family Objects}
-  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEngine{quarto::html}
   %\VignetteDepends{gamlss2}
   %\VignetteKeywords{distributional regression, family objects}
   %\VignettePackage{gamlss2}
@@ -36,7 +36,7 @@ This document provides an overview of how to construct and use family objects wi
 By the end, you should have a good understanding of how to implement a custom family for
 use in statistical models.
 
-### Defining Family Objects
+## Defining Family Objects
 
 A family object in _gamlss2_ is a list that must meet the following minimum criteria:
 
@@ -72,7 +72,7 @@ In this example, we define a normal distribution with two parameters: `"mu"` (me
 it is the log function. The density function uses the standard `dnorm()` function from
 to calculate the normal density.
 
-### Density Function
+## Density Function
 
 The density function must accept the following arguments:
 
@@ -84,7 +84,7 @@ d(y, par, log = FALSE, ...)
 * `par`: A named list of parameters (e.g., `"mu"`, `"sigma"` for the normal distribution).
 * `log`: A logical value indicating whether to return the log-density.
 
-### Optional Derivatives
+## Optional Derivatives
 
 Family objects can optionally include functions to compute the first and second derivatives of
 the log-likelihood with respect to the predictors (or its expectations). These derivatives are used for
@@ -137,7 +137,7 @@ Normal <- function(...) {
 
 If no derivatives are provided, numerical approximations will be used by the package.
 
-### Additional Functions
+## Additional Functions
 
 Family objects can also include other functions such as:
 
@@ -148,7 +148,7 @@ Family objects can also include other functions such as:
 These functions should adhere to the same structure as the density function, taking the response
 (`y`), parameters (`par`), and other relevant arguments.
 
-### Flexible Links
+## Flexible Links
 
 Note that the example above used static link functions to define the family object.
 However, users can easily create families with flexible link functions as well.
@@ -173,7 +173,7 @@ functions is provided in the `Kumaraswamy()` family.
 In the following example, we will create the family object for the Kumaraswamy distribution
 using the `Kumaraswamy()` function and estimate a model using this distribution.
 
-#### Example: Modeling with the Kumaraswamy Distribution
+### Example: Modeling with the Kumaraswamy Distribution
 
 In this example, we will:
 
@@ -220,7 +220,7 @@ The `Kumaraswamy()` family in _gamlss2_ is flexible, allowing the user to specif
 different link functions for its parameters, such as the default `shiftlog` link function for
 parameter `a`, which ensures non-negative values.
 
-### Conclusion
+## Conclusion
 
 Family objects in the _gamlss2_ package are a fundamental component for defining flexible,
 distribution-based regression models, and beyond. By encapsulating the necessary elements,

vignettes/gamlss2.Rmd → vignettes/gamlss2.qmd

@@ -1,16 +1,16 @@
 ---
 title: "First Steps"
-output:
-  html_document:
+format: 
+  html:
+    html-math-method: mathjax
     toc: true
-    toc_float: true
-    theme: flatly
+    number-sections: true
 bibliography: gamlss2.bib
 nocite: |
   @Rigby+Stasinopoulos:2005
 vignette: >
   %\VignetteIndexEntry{First Steps}
-  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEngine{quarto::html}
   %\VignetteDepends{gamlss2}
   %\VignetteKeywords{distributional regression, first steps}
   %\VignettePackage{gamlss2}
@@ -43,7 +43,7 @@ being that summary outputs are provided for all parameters of the distribution.
 the model is estimated using the `NO` family of the _gamlss.dist_ package, a two-parameter
 distribution with parameters `mu` and `sigma`.
 
-### Residual Diagnostics
+## Residual Diagnostics
 
 Since we estimated a simple linear model with Gaussian errors up to now, we are assuming that
 the distribution of the response variable, the number of motorcycles (`bikes`), follows a

vignettes/random.Rmd → vignettes/random.qmd

@@ -1,16 +1,16 @@
 ---
 title: "Random Effects"
-output:
-  html_document:
+format: 
+  html:
+    html-math-method: mathjax
     toc: true
-    toc_float: true
-    theme: flatly
+    number-sections: true
 bibliography: gamlss2.bib
 nocite: |
   @Rigby+Stasinopoulos:2005
 vignette: >
   %\VignetteIndexEntry{Random Effects}
-  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEngine{quarto::html}
   %\VignetteDepends{gamlss2}
   %\VignetteKeywords{distributional regression, random effects}
   %\VignettePackage{gamlss2}

vignettes/s_pb.Rmd → vignettes/s_pb.qmd

@@ -1,10 +1,10 @@
 ---
 title: "Smooth Terms using s() and pb()"
-output:
-  html_document:
+format: 
+  html:
+    html-math-method: mathjax
     toc: true
-    toc_float: true
-    theme: flatly
+    number-sections: true
 bibliography: gamlss2.bib
 nocite: |
   @Rigby+Stasinopoulos:2005
@@ -27,7 +27,7 @@ nocite: |
   
 vignette: >
   %\VignetteIndexEntry{Smooth Terms}
-  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEngine{quarto::html}
   %\VignetteDepends{gamlss2}
   %\VignetteKeywords{distributional regression, inference, forecasting}
   %\VignettePackage{gamlss2}

vignettes/selection.Rmd → vignettes/selection.qmd

@@ -1,16 +1,16 @@
 ---
 title: "Variable and Model Selection"
-output:
-  html_document:
+format: 
+  html:
+    html-math-method: mathjax
     toc: true
-    toc_float: true
-    theme: flatly
+    number-sections: true
 bibliography: gamlss2.bib
 nocite: |
   @Rigby+Stasinopoulos:2005
 vignette: >
   %\VignetteIndexEntry{Selection}
-  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEngine{quarto::html}
   %\VignetteDepends{gamlss2}
   %\VignetteKeywords{distributional regression, model selection, variable selection}
   %\VignettePackage{gamlss2}

vignettes/spatial.Rmd → vignettes/spatial.qmd

@@ -1,16 +1,16 @@
 ---
 title: "Spatial Effects"
-output:
-  html_document:
+format: 
+  html:
+    html-math-method: mathjax
     toc: true
-    toc_float: true
-    theme: flatly
+    number-sections: true
 bibliography: gamlss2.bib
 nocite: |
   @Rigby+Stasinopoulos:2005
 vignette: >
   %\VignetteIndexEntry{Spatial Effects}
-  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEngine{quarto::html}
   %\VignetteDepends{gamlss2}
   %\VignetteKeywords{distributional regression, spatial effects}
   %\VignettePackage{gamlss2}
@@ -33,7 +33,7 @@ This vignette is divided into two parts: the first part demonstrates how to esti
 spatial effects using MRFs with the gamlss2 package, while the second part provides examples
 of modeling spatial effects with smooth functions like thin-plate splines or tensor product splines.
 
-### Example: Modeling Severe Storm Counts in Germany
+## Example: Modeling Severe Storm Counts in Germany
 
 In this example, we analyze severe storm counts recorded at various weather stations across
 Germany over multiple years. Our goal is to model these storm counts while accounting for the
@@ -59,7 +59,7 @@ for(j in levels(storms$id)) {
 The data contains storm counts per year for each station. A preliminary visualization
 of these counts allows us to inspect patterns of storm frequency over time and across stations.
 
-### Visualizing the Spatial Structure
+## Visualizing the Spatial Structure
 
 We begin by plotting the locations of weather stations on a map of Germany. The _sf_ package is
 used to manage and plot spatial data.
@@ -80,7 +80,7 @@ points(co, col = 2, pch = 4, lwd = 2)
 This map shows the geographical distribution of weather stations. The spatial structure will
 be incorporated into our model to account for the proximity of stations when estimating storm counts.
 
-### Defining the Neighborhood Structure
+## Defining the Neighborhood Structure
 
 Next, we define the neighborhood structure among the weather stations using a distance-based
 criterion. This is crucial for the Markov random field, as it specifies how spatial
@@ -102,7 +102,7 @@ The neighbor matrix is constructed using the `dneirneigh()` function from the _s
 which calculates the adjacency structure of the geographical regions. We then visualize
 the spatial network of neighbors on the map.
 
-### Constructing the Penalty Matrix
+## Constructing the Penalty Matrix
 
 The penalty matrix defines the spatial penalties imposed by the Markov random field.
 The matrix is constructed based on the neighbor relationships defined earlier.
@@ -127,7 +127,7 @@ The penalty matrix `K` is set up such that it reflects the neighborhood relation
 regions. Each element of the matrix represents how strongly each region is connected to its
 neighbors. The diagonal entries represent the total number of neighbors for each region.
 
-### Estimating the Model
+## Estimating the Model
 
 We now estimate the spatial count model using the Negative Binomial distribution (`NBI`).
 The model includes smooth functions of altitude, year, and an interaction between altitude and year,
@@ -162,7 +162,7 @@ Here, the spatial effect is modeled as an MRF smooth (`s(id, bs = "mrf")`), wher
 matrix `K` enforces spatial structure based on neighboring stations. We use the
 Bayesian Information Criterion (BIC) to select the optimal smoothing parameters.
 
-### Visualizing the Estimated Effects
+## Visualizing the Estimated Effects
 
 Finally, we visualize the estimated effects from the fitted model.
 
@@ -174,22 +174,23 @@ plot(b)
 The plot shows the estimated smooth functions for altitude, year, and the spatial effect.
 These visualizations help us interpret how storm counts vary across space and time.
 
-### Prediction
+## Prediction
 
 We predict the spatial risk of more than 2 severe storms in 2022. Therefore, we
 set up a new data frame containing only the unique loactions.
 
-```{r}
+```{r, eval=FALSE}
 nd <- unique(storms[, "id", drop = FALSE])
 
 ## add the year
 nd$year <- 2022
 
 ## add altitude information, this is stored
 ## in a raster file in
-library
-rf <- file.path(system.file(package = "gamlss2"), "extra", "GermanyElevation.grd")
-alt <- st_read(rf)
+
+#FIXME# library
+#FIXME# rf <- file.path(system.file(package = "gamlss2"), "extra", "GermanyElevation.grd")
+#FIXME# alt <- st_read(rf)
 
 ## prediction for the mu predictor,
 ## which is the mean of the NBI distribution

vignettes/topmodels.Rmd → vignettes/topmodels.qmd

@@ -1,16 +1,16 @@
 ---
 title: "Top Models"
-output:
-  html_document:
+format: 
+  html:
+    html-math-method: mathjax
     toc: true
-    toc_float: true
-    theme: flatly
+    number-sections: true
 bibliography: gamlss2.bib
 nocite: |
   @Rigby+Stasinopoulos:2005
 vignette: >
   %\VignetteIndexEntry{Top Models}
-  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEngine{quarto::html}
   %\VignetteDepends{gamlss2}
   %\VignetteKeywords{distributional regression, inference, forecasting}
   %\VignettePackage{gamlss2}
@@ -22,3 +22,11 @@ library("gamlss2")
 
 Introduction on how to use the _topmodels_ package with _gamlss2_.
 
+```{r, eval=FALSE}
+library("gamlss2")
+m <- gamlss2(dist ~ s(speed), data = cars)
+library("topmodels")
+proscore(m)
+rootogram(m)
+wormplot(m)
+```