start posterior vignette

vignettes/posterior.Rmd

@@ -0,0 +1,84 @@
+---
+title: "Working with Posteriors"
+output:
+  rmarkdown::html_vignette:
+    toc: true
+    toc_depth: 3
+params:
+  EVAL: !r identical(Sys.getenv("NOT_CRAN"), "true")
+vignette: >
+  %\VignetteIndexEntry{Working with Posteriors}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r child="children/settings-knitr.Rmd"}
+```
+
+## Summary
+
+We can easily customise the summary statistics reported by `$summary()` and `$print()`.
+
+```{r}
+fit <- cmdstanr::cmdstanr_example("schools", method = "sample")
+fit$summary()
+```
+
+By default all variables are summaries with the follow functions:
+```{r}
+posterior::default_summary_measures()
+```
+
+To change the variables summarised, we use the variables argument
+```{r}
+fit$summary(variables = c("mu", "tau"))
+```
+
+We can additionally change which functions are used
+```{r}
+fit$summary(variables = c("mu", "tau"), mean, sd)
+```
+
+To summarise all variables with non-default functions, it is necessary to set explicitly set the variables argument, either to `NULL` or the full vector of variable names.
+```{r}
+fit$metadata()$model_params
+fit$summary(variables = NULL, "mean", "median")
+```
+
+Summary functions can be specified by character string, function, or using a formula (or anything else supported by [rlang::as_function]). If these arguments are named, those names will be used in the tibble output. If the summary results are named they will take precedence.
+```{r}
+my_sd <- function(x) c(My_SD = sd(x))
+fit$summary(
+  c("mu", "tau"), 
+  MEAN = mean, 
+  "median",
+  my_sd,
+  ~quantile(.x, probs = c(0.1, 0.9)),
+  Minimum = \(x) min(x)
+)        
+```
+
+Arguments to all summary functions can also be specified with `.args`. 
+```{r}
+fit$summary(c("mu", "tau"), quantile, .args = list(probs = c(0.025, .05, .95, .975)))
+```
+
+The summary functions are applied to the array of sample values, with dimension `iter_sampling`x`chains`.
+```{r}
+fit$summary(variables = NULL, dim, colMeans)
+```
+
+For this reason users may have unexpected results if they use [stats::var()] directly, as it will return a covariance matrix. An alternative is the [distributional::variance] function.
+```{r}
+fit$summary(c("mu", "tau"), distributional::variance, ~var(as.vector(.x)))
+```
+
+Summary functions need not be numeric, but these won't work with `$print()`.
+
+```{r}
+strict_pos <- function(x) if (all(x > 0)) "yes" else "no"
+fit$summary(variables = NULL, "Strictly Positive" = strict_pos)
+# fit$print(variables = NULL, "Strictly Positive" = strict_pos)
+```
+
+For more information, see [posterior::summarise_draws()], which is is called by `$summary()`.