RE: [R] To run or not to run examples, CTFS package
My $0.02...
From: Pamela Hall
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. It might take a long time, depending on the specifics of your `real
data'.
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.
I would use the minimal amount of data that's sufficient to demonstrate
whatever points needed to be made in the example, and no more.
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?
One other possibility is to create a package vignette...
Cheers,
Andy
-ph
__
[EMAIL PROTECTED] mailing list
https://www.stat.math.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide!
http://www.R-project.org/posting-guide.html
__
[EMAIL PROTECTED] mailing list
https://www.stat.math.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Re: [R] To run or not to run examples, CTFS package
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
[EMAIL PROTECTED] University of Washington, Seattle
__
[EMAIL PROTECTED] mailing list
https://www.stat.math.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
