126

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?

4
  • 37
    just a related tip. You can run the example code by issuing "example(glm)". Sep 21, 2009 at 16:10
  • 6
    That is a good tip. And I'd bet that the vast majority of R users aren't aware of it. Sep 21, 2009 at 17:54
  • 1
    but note example(fn) will still not example code wrapped in dontRun
    – tim
    Aug 27, 2015 at 11:03
  • except if you set the run.dontrun parameter to TRUE Jun 29, 2018 at 7:25

5 Answers 5

84

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

4
  • 5
    ... how did I not know about this function? Sep 21, 2009 at 14:41
  • 6
    It's not just time-consuming code that typically is put inside of a \dontrun{}. Code that requires user input needs to be be inside dontrun as well or else it won't pass R CMD check
    – Dason
    Oct 11, 2012 at 23:03
  • 2
    Or: code that depends on a package that might not be installed on the user's machine. There are lots and lots and lots of reasons to use \dontrun{}
    – Jason
    Sep 12, 2016 at 6:45
  • @MattParker I know, whattttt
    – mitchus
    Aug 8, 2022 at 19:32
28

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.

17

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
5
  • 3
    Note that donttest is now tested Jan 28, 2015 at 0:40
  • 1
    For package submission, do you have to have any additional comments in the .Rd justifying omission of the code block? I had a package fail check because of a \donttest{} example and am wondering if it is a simple as changing it to \dontrun{}. The function is for downloading data from an ftp and the CRAN comment is: "That is not commented on in the .Rd files. Note that example() will run these sections". Jan 30, 2015 at 14:48
  • Yes it should be that simple. Jan 30, 2015 at 15:19
  • @TylerRinker you mean the function is verified as working, or the code with in @donttest{ } is now run by CRAN when doing checks?
    – tim
    Aug 27, 2015 at 11:05
  • 2
    Yes heres a quote from Hadley 's book: "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 not run. (You used to be able to use \donttest{} for a similar purpose, but it’s no longer recommended because it actually is tested.)" Aug 27, 2015 at 12:04
6

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.

5

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.