How to not run an example using roxygen2?

Question

I'm writing a geocoding function right now that relies on having a Bing Maps Key. Obviously I'd rather not publish mine, and the examples fail without one.

How do I include an example for users to run manually, but not have it executed during R CMD check?

Fluellen

Answer 1

Use \dontrun{}

#'@examples
#'\dontrun{
#'geocode("3817 Spruce St, Philadelphia, PA 19104")
#'geocode("Philadelphia, PA")
#'dat <- data.frame(value=runif(3),address=c("3817 Spruce St, Philadelphia, PA 19104","Philadelphia, PA","Neverneverland"))
#'geocode(dat)
#'}

Flashgun

this is documented in ?example and Writing R Extensions – Flashgun

@Jeroen, I believe that roxygen2 made up the @example tag, so I think it's an roxygen2 problem. I don't think \example{} is valid -- see cran.r-project.org/doc/manuals/… – Flashgun

Judging from the topic title, the question is about roxygen2 syntax and not about .Rd syntax? – Thesis

Thanks for the answer. It didn't work for me first because I was using @example instead of @examples. Both tags come up in RStudio auto-complete. I'm happy now. – Deutschland

using @example, you can still use dontrun{} inside the example file. formatting multiline code in comments doesn't work well, so see my answer on the related question. – Likelihood

I think the correct answer for what is being asked for is donttest and not dontrun. See ?example and #12038660. See also cran.r-project.org/web/packages/roxygen2/vignettes/rd.html. – Carefree

Answer 2

You can use \donttest{} to your example. The snippet will be provided in your documentation, but won't get tested with the R CMD Check.

For more info --> ?example

#' @example
\donttest{
    2^2
    }

This 2^2 won't get run when you run devtools::check()

---

EDIT

Per the latest release notes or NEWS for R 4.0.0, examples within \donttest{} will now be tested by default. This can, however, be overridden by setting environment variable _R_CHECK_DONTTEST_EXAMPLES_ to FALSE.

R CMD check --as-cran now runs \donttest examples (which are run by example()) instead of instructing the tester to do so. This can be temporarily circumvented during development by setting environment variable R_CHECK_DONTTEST_EXAMPLES to a false value.

According to this GitHub issues discussion (credited here), Hadley Wickham noted that

Generally, now if you don't want to run tests on CRAN \dontrun{} is more likely to work, but using \dontrun{} may cause initial submission to fail.

There are other ways as well that will let you continue to use donttest{}, refer the aforementioned discussions for the workarounds.

Gibbet

It seems that this should be the accepted answer instead of dontrun. From ?example 'donttest encloses code that typically should be run, but not during package checking.' whereas 'dontrun encloses code that should not be run.' I also got a comment by cran maintainers to switch from dontrun to donttest. – Carefree

Totally agree with @JulianKarls. Got the same feedback from CRAN maintainers. – Blackett

Answer 3

For those who are using @example path/to/example.R instead of the @examples tag you can use the \dontrun environment directly in the example.R file. For example

# example.R
\dontrun{
# this is a long running example
for(i in seq(1, 1e5)) { lm(mpg ~ wt, data = mtcars) }
}

# some other shorter example
2 + 2

Frangipani

this doesn't work for me (running on Win 10, 64 bit, R version 3.5.0) – Jaffna

Answer 4

\dontrun{}

Is the correct function. See here:

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

Source: https://r-pkgs.org/man.html?q=donttest#man-functions

Connatural

This answer was already given and accepted. The link is not worth an answer, it is a comment – Cable

Answer 5

Ari, I also use roxygen2 (version 4.1.0). The following is the end of my roxygen2 mark-up in my function (gctemplate) definition till the beginning of the real part.

#' @examples
#' ## List all G-causalities in a VAR system of 5 variables that will be searched in the pattern of 1 
#' ## causer (like-independent) variable and 2 like-dependents conditional on 5-(1+2)=2 of the remaining 
#' ## variable(s) in the system. Variables are assigned to numbers 1 to nvars. 
#' ## "1 2 5 3 4" in the resulting line of gctemplate is to indicate the 
#' ## (conditonal, partial, etc.) G-causality from variable 1 to variables 2 and 5 
#' ## conditonal on variables 3 and 4.
#' # gctemplate(5,1,2)
#' ## The number of all G-causalities to be searched in the above pattern.
#' #dim(gctemplate(5,1,2))[[1]]
#' @importFrom combinat combn
#' @export
gctemplate <- function(nvars, ncausers, ndependents){
...

I know GSee's dontrun method.
In my technique, the numerical example and the text explaining the numerical example are both comments. I use indentation to make difference between these two; Notice there are 1 sharp and 2 sharps respectively after "#'". I always use the above "#' ## / #' #" technique in my packages. The user is left to copy-paste operation whenever s/he wanna test the function. This technique is - according to me - more parallel with the classical comment bombardment of the software coding philosophy.

Olvan

If you use dontrun{}, then the user can call example(myFunction, run.dontrun=TRUE), whereas if you simply comment out the examples, you have no way to run the examples other than to copy/paste. – Flashgun