image

Writing Vignettes

(NOTE: This is currently in draft form, and there may be some errors that need to be corrected.)

To begin, one should have already created a suitable Sweave document. This document should include a title that contains the command being demonstrated, the author's name, and the date it was written.

Converting an Sweave Document into a Vignette

The changes that are made occur at the beginning of the document. These include changes to the preamble and the creation of an SweaveOpts section.

First, include the following commands in the preamble, prior to the \begin{document} command:

\documentclass[a4paper]{article} \\
\usepackage{a4wide} \\
\setlength{\parskip}{0.7ex plus0.1ex minus0.1ex} \\
\setlength{\parindent}{0em} \\

(NOTE: I am not sure if these are actually necessary for a vignette. However, all of the vignettes I have found in R have been in this format, and thus I am following them closely.)

Other necessary commands (such as \usepackage{amsmath}) can be also be included as part of this preamble.

Second, after the \begin{document} command, the SweaveOpts section should be added. Here is one example of this section:

\SweaveOpts{engine=R} \\
%\VignetteIndexEntry{Using MCMClogit} \\
%\VignetteDepends{MCMCpack} \\
%\VignetteKeywords{MCMClogit,logit,MCMCpack} \\
%\VignettePackage{MCMCpack} \\

These should be changed to fit your vignette. VignetteIndexEntry should be a title that describes what is being demonstrated. VignetteDepends should indicate all packages that are necessary for running the vignette. If your vignette requires more than one package, all packages should be included in this command, and the names should be separated by commas. VignetteKeywords should include words that indicate what follows in the vignette. Generally, this should include the command being demonstrated, as well as MCMCpack itself and other applicable words like the model name. VignettePackage for all of the vignettes in the package should be MCMCpack.

When completed, the vignette should be included in a folder labeled "doc" within a folder labeled "inst" inside the package.

Converting a .Rnw File Into a Vignette

If you wish to look at the final vignette without building an entire package, you can do so by following these steps:

1. With R open, make sure that the dataset is readable. Depending on the contents of your vignette, this may require simply changing the working directory. If the dataset is not loaded within the vignette, you may also need to load it with the following command:

load("//dataset//.rda")

where dataset is the name of the dataset used in the vignette.

2. Once the dataset is either loaded or prepared to be loaded by the vignette, enter the following command:

Sweave("//vignette//.Rnw")

where vignette is the name of the vignette file. The resulting files from this process should be a .tex file as well as any graphic files that were created.

3. The resulting .tex file and companion files can then be converted by any TeX driver, such as TeXshop, into a .pdf file.