tweak the getting started vignette

vignettes/getting-started.bib

@@ -0,0 +1,5 @@
+@article{Arel-BundockGreiferHeiss:2024,
+    title = {How to Interpret Statistical Models Using {marginaleffects} in {R} and {Python}},
+    author = {Vincent Arel-Bundock and Noah Greifer and Andrew Heiss},
+    year = {Forthcoming},
+    journal = {Journal of Statistical Software}}

vignettes/gratia.Rmd

@@ -5,6 +5,7 @@ output:
     fig_width: 8
     fig_height: 5.3333
     dev: "png"
+bibliography: getting-started.bib
 vignette: >
   %\VignetteIndexEntry{Getting started with gratia}
   %\VignetteEngine{knitr::rmarkdown}
@@ -46,26 +47,40 @@ summary(m)
 ## Plotting
 
 gratia provides the `draw()` function to produce plots using the ggplot2
-📦. To draw the estimated smooths from the GAM we fitted above, use
+📦. To plot the estimated smooths from the GAM we fitted above, use
 
 ```{r draw-gam}
 draw(m)
 ```
 
-This is intended as reasonable overview of the estimated model, but it offers
-limited option to modify the resulting plot. If you want full control, you can
-obtain the data used to create the plot above with `smooth_estimates()`
-
+The plots produced are *partial effect* plots, which show the component
+contributions, on the link scale, of each model term to the linear predictor.
+The y axis on these plots is typically centred around 0 due to most smooths
+having a sum-to-zero identifiability constraint applied to them. This
+constraint is what allows the model to include multiple smooths and remain
+identifiable. These plots allow you to read off the contributions of each
+smooth to the fitted response (on the link scale); they show link-scale
+predictions of the response for each smooth, conditional upon all other terms
+in the model, including any parametric effects and the intercept, having zero 
+contribution. In the parlance of the marginaleffects package
+[@Arel-BundockGreiferHeiss:2024], these plots show adjusted predictions, just
+where the adjustment includes setting the contribution of all other model terms
+to the predicted value to zero. For partial derivatives (what *marginaleffects*
+would call a marginal effect or slope), gratia provides `derivatives()`.
+
+The resulting plot is intended as reasonable overview of the estimated model,
+but it offers limited option to modify the resulting plot. If you want full
+control, you can obtain the data used to create the plot above with 
+`smooth_estimates()`
 ```{r smooth-estimates}
 sm <- smooth_estimates(m)
 sm
 ```
-
-which will evaluate all smooths are unevenly spaced values over the range of the
-covariate(s). If you want to evaluate only selected smooths, you can specify
-which via the `smooth` argument. This takes the *smooth labels* which are the
-names of the smooths as they are known to mgcv. To list the labels for the
-smooths in use
+which will evaluate all smooths at values that are evenly spaced over the range
+of the covariate(s). If you want to evaluate only selected smooths, you can
+specify which via the `smooth` argument. This takes the *smooth labels* which
+are the names of the smooths as they are known to mgcv. To list the labels for
+the smooths in use
 ```{r smooths}
 smooths(m)
 ```
@@ -119,3 +134,5 @@ draw(m, residuals = TRUE)
 currently lacking is documentation. To find out more about the package, look at
 the [help pages for the package](https://gavinsimpson.github.io/gratia/reference/index.html)
 and look at the examples for more code to help you get going.
+
+# References