What does "not run" mean in R help pages?
RR Problem Overview
Sometimes on an R help page the phrase "not run" appears in comments. Check out this from the help page for "with()":
Examples
require(stats); require(graphics)
#examples from glm:
**## Not run:**
library(MASS)
with(anorexia, {
anorex.1 <- glm(Postwt ~ Prewt + Treat + offset(Prewt),
family = gaussian)
summary(anorex.1)
})
## End(**Not run**)
What does the "not run" mean in the example code?
R Solutions
Solution 1 - R
"not run" encloses code that shouldn't be executed in the example function (e.g. time-consuming code parts, user-interaction, ...).
see e.g. ?example:
As detailed in the manual Writing R Extensions, the author of the help page can markup parts of the examples for two exception rules
-
'dontrun' encloses code that should not be run.
-
'dontshow' encloses code that is invisible on help pages, but will be run both by the package checking tools, and the 'example()' function. This was previously 'testonly', and that form is still accepted.
Solution 2 - R
In "Writing R Extensions" manual, in section about \examples{...} is said that > You can use \dontrun{} for text that should only be shown, but not run, and \dontshow{} for extra commands for testing that should not be shown to users, but will be run by example()
When you build a package then all code in \dontrun{} closure is visible in help as
## Not run:
...
## End(**Not run**)
edit: This answer was earlier.
Solution 3 - R
This adds \donttest{} and is taken (verbatim) from @hadley's R Packages.
>However for the purpose of illustration, it’s often useful to include code that causes an error. \dontrun{} allows you to include code in the example that is never used. There are two other special commands. \dontshow{} is run, but not shown in the help page: this can be useful for informal tests. \donttest{} is run in examples, but not run automatically in R CMD check. This is useful if you have examples that take a long time to run. The options are summarised below.
Command example help R CMD check
\dontrun{} x
\dontshow{} x x
\donttest{} x x
Solution 4 - R
C & p from Chapter 5.4 (R Documentation Files) of the MUST-TO-READ Creating R Packages: A Tutorial by Friedrich Leisch:
> The examples section should contain > executable R code, and automatically > running the code is part of checking > a package. There are two special > markup commands for the examples:
> dontrun: Everything inside \dontrun{} > is not executed by the tests or > example(). This is useful, e.g., for > interactive functions, functions > accessing the Internet etc.. Do not > misuse it to make life easier for you > by giving examples which cannot be > executed.
Solution 5 - R
The canonical example here might be in the help page for rm:
## Not run:
## remove (almost) everything in the working environment.
## You will get no warning, so don't do this unless you are really sure.
rm(list = ls())
## End(Not run)
If this ran it would of course have undesired effects.