Vignettes

[rok-cesnovar]

Vignettes to-do list:

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

• [x] variational inference (done in #210)

• [x] optimization (done in #210)

• [x] profiling (done in #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

• [x] 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.

[rok-cesnovar]

It doesn't yet include things like changing adapt delta and max_treedepth.

Also added that to the list so we dont forget. Thanks!

[jgabry]

Just added another item to the list, which is a vignette going through the installation and various troubleshooting techniques. I think this would be helpful, at least until we can install the toolchain for people.

[rok-cesnovar]

What is the policy with regards to downloading data from other sources inside a vignette. Like for example, if we were to showcase threading and MPI in cmdstanr and use the redcard example that is used in the reduce_sum case study and Richard McElreath's MPI tutorial. Can we make downloading https://raw.githubusercontent.com/rmcelreath/cmdstan_map_rect_tutorial/master/redcard_input.R part of the vignette or must the data be part of the package to use it in a vignette?

[jgabry]

I haven't checked CRAN policies on that recently, but I think it should be fine. We're also going to submit the vignettes already rendered to CRAN (because CRAN won't have CmdStan) instead of having CRAN render them as they usually do, so I think it should be OK for that reason too.

[bbbales2]

I asked McElreath when we did that if we could use stuff from his map rect tutorial. He said feel free to use whatever.

I think as long as we prominently reference back to his thing we're good (he didn't ask for the reference, but it's appropriate), and if ever his thing gets outdated (and we feel like we shouldn't be linking people to it), I assume we can just send him an updated version or tell him about it.

That stuff is in the example models repo with the reduce_sum example (so it's self-contained)

[tiagocabaco]

Hey,

Are there any guidelines or templates for the structure of the vignettes one needs to follow ? Or is it more on o PR x vignette topic basis?

Thanks :slightly_smiling_face:

[rok-cesnovar]

Hey @tiagocabaco,

we dont have any guidelines or templates apart from our current vignettes. Its dependant on what the vignettes wants to showcase/explain.

Are you just wondering or are you interested in contributing a vignette? Let us know where we can help!