Merge pull request #816 from wlandau/340

Describe how to efficiently save model fit objects

Author: jgabry

vignettes/cmdstanr.Rmd

@@ -380,12 +380,9 @@ these links to their documentation pages.
 
 ## Saving fitted model objects
 
-In order to save a fitted model object to disk and ensure that all of the
-contents are available when reading the object back into R, we recommend using the
-[`$save_object()`](http://mc-stan.org/cmdstanr/reference/fit-method-save_object.html)
-method provided by CmdStanR. The reason for this is discussed in detail in the vignette
-[_How does CmdStanR work?_](http://mc-stan.org/cmdstanr/articles/cmdstanr-internals.html),
-so here we just demonstrate how to use the method.
+The [`$save_object()`](http://mc-stan.org/cmdstanr/reference/fit-method-save_object.html)
+method provided by CmdStanR is the most convenient way to save a fitted model object
+to disk and ensure that all of the contents are available when reading the object back into R.
 
 ```{r save_object, eval=FALSE}
 fit$save_object(file = "fit.RDS")
@@ -394,6 +391,48 @@ fit$save_object(file = "fit.RDS")
 fit2 <- readRDS("fit.RDS")
 ```
 
+But if your model object is large, then
+[`$save_object()`](http://mc-stan.org/cmdstanr/reference/fit-method-save_object.html)
+could take a long time. 
+[`$save_object()`](http://mc-stan.org/cmdstanr/reference/fit-method-save_object.html)
+reads the CmdStan results files into memory, stores them in the model object,
+and saves the object with `saveRDS()`. To speed up the process, you can emulate
+[`$save_object()`](http://mc-stan.org/cmdstanr/reference/fit-method-save_object.html)
+and replace `saveRDS` with the much faster `qsave()` function from the
+[`qs`](https://github.com/traversc/qs) package.
+
+```{r save_object_qs_full, eval = FALSE}
+# Load CmdStan output files into the fitted model object.
+fit$draws() # Load posterior draws into the object.
+try(fit$sampler_diagnostics(), silent = TRUE) # Load sampler diagnostics.
+try(fit$init(), silent = TRUE) # Load user-defined initial values.
+try(fit$profiles(), silent = TRUE) # Load profiling samples.
+
+# Save the object to a file.
+qs::qsave(x = fit, file = "fit.qs")
+
+# Read the object.
+fit2 <- qs::qread("fit.qs")
+```
+
+Storage is even faster if you discard results you do not need to save.
+The following example saves only posterior draws and discards
+sampler diagnostics, user-specified initial values, and profiling data.
+
+```{r save_object_qs_small, eval = FALSE}
+# Load posterior draws into the fitted model object and omit other output.
+fit$draws()
+
+# Save the object to a file.
+qs::qsave(x = fit, file = "fit.qs")
+
+# Read the object.
+fit2 <- qs::qread("fit.qs")
+```
+
+See the vignette [_How does CmdStanR work?_](http://mc-stan.org/cmdstanr/articles/cmdstanr-internals.html)
+for more information about the composition of CmdStanR objects.
+
 ## Comparison with RStan
 
 ```{r child="children/comparison-with-rstan.md"}