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
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
