Making and using R vignettes

[rdstern]

I suggest we might mainly use examples from the trio of agridat, agritutorial and agricolae. Let's see.

This will be a video and possibly also a practice.

R packages include examples at the end of their documentation on most of their datasets or commands. Some add vignettes and often they are largely the examples together with the results. That's then just like running the example with R-Instat or RStudio.

That's easy to do as we show here. Then we suggest, adding just a bit more to the vignette can often help the learning process.

We first show this with R-Instat and also with RStudio. We have developed R-Instat, but the comparison, is not to search for a "winner". If you are already a comfortable R user through RStudio, then we see no reason why you need more. R-Instat is designed for those who find R difficult to use, without a menu system. So, the ideas in this video are quite advanced for them, while they are relatively easy for seasoned R users.

Here is our first example. This is trivial in RStudio so we copy and run though it quite quickly with R-Instat. Shows it is easy.
Meanwhile many RStudio users often do this step routinely. They are not thinking of a vignette, they just use examples occasioanlly to help understand a new command, or see how these data are processed, because using their own.

Let's add to this. One concern we have is that users are not spending time looking at their data. We add this step - first interactively. Then we'll get more advanced an tweak the example script.

Why are we doing this? It is because our vignettes, built in this way, are often incomplete. Even when they are vignettes on data, they often emphasise particular modelling methods. And when they illustrate a command, then that's what they show.

We want to be more complete. There are, of course, many nice examples. For example here is a more complete vignette with the diamonds data.

With this example, we can do this interactively by simply opening the data file. So we do. We like to encourage users to look more at the data than is currently the case. And, often there are particular variables that we will be modelling. The pivot table package makes this easy and attractive as we show here.

Discuss.

In RStudio there is the R-viewer, to look at the data, and the RPivot table can easily be added if it is not already installed for you.

So that's part of being interactive. We like to encourage users to be data detectives and this helps.

The examples based on commands don't make it quite so easy to look at the data. Once there is a data frame it is easy to add the command to show it in R-Instat. .

etc. I see this as part of our teaching for using R-Instat to support agricultural research. @lilyclements could this be useful in our forthcoming stats for agriculture course.