Vignettes

[rok-cesnovar]

Vignettes to-do list:

• filtering returned parameters from $draws()
  Showcase how one can read in only selected parameters.

• variational inference (done in add example of optimize and variational to vignette #210)

• optimization (done in add example of optimize and variational to vignette #210)

• profiling (done in Profiling vignette #435)

• standalone generate_quantities

• vignette on how to use different draws formats

• example with changing adapt delta and max_treedepth

• Installation vignette

  • Show how to install cmdstan and go through various troubleshooting techniques.

• threading vignette

  • Showcase how to use threading. Use the redcard model from the case study in the reduce sum tutorial

• OpenCL vignette

  • Showcase using OpenCL with a model with one of the GLMs.

• MPI vignette

  • Use the redcard model.

[jgabry]

Thanks for creating the checklist.

• The only thing I am not completely sure here is how does this effect tests as not everyone can run these.

We can exclude that vignette from testing if necessary.

[bbbales2]

Small aside, I'm not really sure originally where the redcard model came from. I copied the code from here but that indicates the data came from further upstream.

[bbbales2]

Hmm what's the current status of vignettes/tutorials? These all sound like edge case things. There should be doc that goes over the non-edge case stuff (compile model, run model, look at summaries, extract draws, link to posterior, use with Bayesplot, change adapt delta, change max treedepth, save the model results to disk, etc.).

[jgabry]

@bbbales2 The one vignette we currently have at

http://mc-stan.org/cmdstanr/articles/cmdstanr.html

includes compiling, running a model, looking at summary, extracting draws, plotting a posterior, albeit only brief demonstrations of each of those.

It doesn't yet include things like changing adapt delta and max_treedepth. Not sure if those should go in that vignette or a separate one (e.g., a troubleshooting vignette), but I agree we should demonstrate that.

If you want to help flesh out the existing vignette (or just tell me what to flesh it out with) that'd be great!

[bbbales2]

If you want to help flesh out the existing vignette

I'm behind in all the things as is lol. Just trying to make your life harder.

[bbbales2]

albeit only brief demonstrations

I think a good vignette should basically be a bunch of ready to copy-paste code, so brief demonstrations are the thing. The full docs are there to handle the non-brief stuff.

[bbbales2]

I go to vignettes when I'm desperately using a new package I'm unfamiliar with or use infrequently and forget the basics (which is where this comment comes from)

[jgabry]

I go to vignettes when I'm desperately using a new package I'm unfamiliar with or use infrequently and forget the basics (which is where this comment comes from)

yeah me too. with that in mind, if you have suggestions for how the current vignette could be improved let me know. (if you have time, if not no worries!)

[jgabry]

Coming back to the various vignettes @rok-cesnovar mentions, I do think they would all be good to have but some can probably wait for after the beta release.

For example, it will be nice to have the GPU vignette but we could do a beta release without it.

Also, since we do have the threading case study we could wait on a threading vignette until after the beta release. (@bbbales2 that reminds me, I think the threading case study needs to be updated now that we merged #185 right?)

[bbbales2]

that reminds me

Yeah thanks for the reminder lemme go do that.

[rok-cesnovar]

but some can probably wait for after the beta release.

Yes definitely. Got a bit carried away :) Once we figure we have enough for beta we can move the milestone.