[R] To run or not to run examples, CTFS package

[Thomas Lumley]

On Tue, 15 Jun 2004, Pamela Hall wrote:

> Hi again;
>
> I have placed many examples in the CTFS Rd pages because my audience
> really really likes lots of examples in order to understand the options
> available in a functions.  At this time I have set them all to
> \dontrun{}.
>
> however, this isn't because the example command line with its function
> and options won't work, but rather that CTFS specific datasets must
> exist to have the function output mean anything (random number
> generation is not useful for understanding the function output).  The
> CTFS datasets are quite large...20-40 MB and for some functions many
> other datasets need to be available.  The functions can also take quite
> a bit of time to run in some cases, performing many simulations.
>
> So, my questions are:
>
> 1.  Does the R CMD check command actually run all of the examples if
> \dontrun{} isn't in the Rd file?  And won't this take a lot of time with
> real datasets?

Yes, they are all run. For some packages this takes a long time, for
others it doesn't.

> 2.  Should I consider making short versions of the datasets for the use
> of \example{} ?  This is trivial in some cases, but not in others as the
> function only makes sense on the entire dataset.  however, in those
> cases it is, so far, with some of the shorter datasets.

If possible, it would be useful to have short versions for examples.

> 3.  Or can I just leave everything as \dontrun{} and if my audience want
> to actually run a function, then can cut and paste the line out of the
> man page or just type it in with their versions of the correct datasets
> attached?

You can leave things as \dontrun{}, but this should be a last resort.  The
automatic running of examples is really useful for catching bugs.

Also, if you want examples of how to perform various tasks it may be more
useful to have vignettes than examples.

	-thomas

Thomas Lumley			Assoc. Professor, Biostatistics
tlumley at u.washington.edu	University of Washington, Seattle