add laplace section to vignette

Author: jgabry

vignettes/cmdstanr.Rmd

@@ -326,8 +326,8 @@ stanfit <- rstan::read_stan_csv(fit$output_files())
 
 CmdStanR also supports running Stan's optimization algorithms and its algorithms
 for variational approximation of full Bayesian inference. These are run via the
-`$optimize()` and `$variational()` methods, which are called in a similar way to
-the `$sample()` method demonstrated above.
+`$optimize()`, `$laplace()`, and `$variational()` methods, which are called in a
+similar way to the `$sample()` method demonstrated above.
 
 ### Optimization
 
@@ -347,34 +347,69 @@ mcmc_hist(fit$draws("theta")) +
   vline_at(fit_mle$mle("theta"), size = 1.5)
 ```
 
+For optimization, by default the mode is calculated without the Jacobian
+adjustment for constrained variables, which shifts the mode due to the change of
+variables. To include the Jacobian adjustment and obtain a maximum a posteriori
+(MAP) estimate set `jacobian=TRUE`. See the 
+[Maximum Likelihood Estimation](https://mc-stan.org/docs/cmdstan-guide/maximum-likelihood-estimation.html)
+section of the CmdStan User's Guide for more details. 
+
+```{r optimize-map}
+fit_map <- mod$optimize(data = data_list, jacobian = TRUE, seed = 123)
+```
+
+### Laplace Approximation
+
+The [`$laplace()`](https://mc-stan.org/cmdstanr/reference/model-method-laplace.html)
+produces a sample from a normal approximation centered at the mode of a
+distribution in the unconstrained space. If the mode is a MAP estimate, the
+samples provide an estimate of the mean and standard deviation of the posterior
+distribution. If the mode is the MLE, the sample provides an estimate of the
+standard error of the likelihood. Whether the mode is the MAP or MLE depends on
+the value of the `jacobian` argument when running optimization. See the
+[Laplace Sampling](https://mc-stan.org/docs/cmdstan-guide/laplace-sampling.html) 
+chapter of the CmdStan User's Guide for more details.
+
+Here we pass in the `fit_map` object from above as the `mode` argument. If
+`mode` is omitted then optimization will be run internally before taking draws
+from the normal approximation.
+
+```{r laplace}
+fit_laplace <- mod$laplace(mode = fit_map, draws = 4000, data = data_list, seed = 123)
+fit_laplace$summary("theta")
+mcmc_hist(fit_laplace$draws("theta"), binwidth = 0.025)
+```
+
 ### Variational Bayes
 
 We can run Stan's experimental variational Bayes algorithm (ADVI) using the
 [`$variational()`](https://mc-stan.org/cmdstanr/reference/model-method-variational.html)
 method.
 
 ```{r variational}
-fit_vb <- mod$variational(data = data_list, seed = 123, output_samples = 4000)
+fit_vb <- mod$variational(data = data_list, draws = 4000, seed = 123)
 fit_vb$summary("theta")
 ```
 
-The `$draws()` method can be used to access the approximate posterior draws.
-Let's extract the draws, make the same plot we made after MCMC, and compare the
-two. In this trivial example the distributions look quite similar, although
-the variational approximation slightly underestimates the posterior
-standard deviation.
-
-```{r plot-variational-1, message = FALSE, fig.cap="Posterior from MCMC"}
-mcmc_hist(fit$draws("theta"), binwidth = 0.025)
-```
-```{r plot-variational-2, message = FALSE, fig.cap="Posterior from variational"}
-mcmc_hist(fit_vb$draws("theta"), binwidth = 0.025)
+Let's extract the draws, make the same plot we made after MCMC and Laplace
+approximation, and compare them all. In this simple example the distributions
+are quite similar, but this will not always be the case.
+
+```{r plot-compare, message = FALSE, fig.width = 8, fig.cap="Comparing draws from the different algorithms"}
+bayesplot_grid(
+  mcmc_hist(fit$draws("theta"), binwidth = 0.025),
+  mcmc_hist(fit_laplace$draws("theta"), binwidth = 0.025),
+  mcmc_hist(fit_vb$draws("theta"), binwidth = 0.025), 
+  xlim = c(0, 1), 
+  subtitles = c("MCMC", "Laplace", "Variational")
+)
 ```
 
-For more details on the `$optimize()` and `$variational()` methods, follow
-these links to their documentation pages.
+For more details on the `$optimize()`, `$laplace()`  and `$variational()`
+methods, follow these links to their documentation pages.
 
 * [`$optimize()`](https://mc-stan.org/cmdstanr/reference/model-method-optimize.html)
+* [`$laplace()`](https://mc-stan.org/cmdstanr/reference/model-method-laplace.html)
 * [`$variational()`](https://mc-stan.org/cmdstanr/reference/model-method-variational.html)