Last data update: 2014.03.03

 R: Run an Examples Section from the Online Help
exampleR Documentation

Run an Examples Section from the Online Help

Description

Run all the R code from the Examples part of R's online help topic topic with possible exceptions dontrun, dontshow, and donttest, see ‘Details’ below.

Usage

example(topic, package = NULL, lib.loc = NULL,
        character.only = FALSE, give.lines = FALSE, local = FALSE,
        echo = TRUE, verbose = getOption("verbose"),
        setRNG = FALSE, ask = getOption("example.ask"),
        prompt.prefix = abbreviate(topic, 6),
        run.dontrun = FALSE, run.donttest = interactive())

Arguments

topic

name or literal character string: the online help topic the examples of which should be run.

package

a character vector giving the package names to look into for the topic, or NULL (the default), when all packages on the search path are used.

lib.loc

a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries.

character.only

a logical indicating whether topic can be assumed to be a character string.

give.lines

logical: if true, the lines of the example source code are returned as a character vector.

local

logical: if TRUE evaluate locally, if FALSE evaluate in the workspace.

echo

logical; if TRUE, show the R input when sourcing.

verbose

logical; if TRUE, show even more when running example code.

setRNG

logical or expression; if not FALSE, the random number generator state is saved, then initialized to a specified state, the example is run and the (saved) state is restored. setRNG = TRUE sets the same state as R CMD check does for running a package's examples. This is currently equivalent to setRNG = {RNGkind("default", "default"); set.seed(1)}.

ask

logical (or "default") indicating if devAskNewPage(ask = TRUE) should be called before graphical output happens from the example code. The value "default" (the factory-fresh default) means to ask if echo == TRUE and the graphics device appears to be interactive. This parameter applies both to any currently opened device and to any devices opened by the example code.

prompt.prefix

character; prefixes the prompt to be used if echo = TRUE.

run.dontrun

logical indicating that dontrun should be ignored.

run.donttest

logical indicating that donttest should be ignored.

Details

If lib.loc is not specified, the packages are searched for amongst those already loaded, then in the libraries given by .libPaths(). If lib.loc is specified, packages are searched for only in the specified libraries, even if they are already loaded from another library. The search stops at the first package found that has help on the topic.

An attempt is made to load the package before running the examples, but this will not replace a package loaded from another location.

If local = TRUE objects are not created in the workspace and so not available for examination after example completes: on the other hand they cannot overwrite objects of the same name in the workspace.

As detailed in the manual Writing R Extensions, the author of the help page can markup parts of the examples for 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.

donttest

encloses code that typically should be run, but not during package checking. The default run.donttest = interactive() leads example() use in other help page examples to skip donttest sections appropriately.

Value

The value of the last evaluated expression, unless give.lines is true, where a character vector is returned.

Author(s)

Martin Maechler and others

See Also

demo

Examples

example(InsectSprays)
## force use of the standard package 'stats':
example("smooth", package = "stats", lib.loc = .Library)

## set RNG *before* example as when R CMD check is run:

r1 <- example(quantile, setRNG = TRUE)
x1 <- rnorm(1)
u <- runif(1)
## identical random numbers
r2 <- example(quantile, setRNG = TRUE)
x2 <- rnorm(1)
stopifnot(identical(r1, r2))
## but x1 and x2 differ since the RNG state from before example()
## differs and is restored!
x1; x2

## Exploring examples code:
## How large are the examples of "lm...()" functions?
lmex <- sapply(apropos("^lm", mode = "function"),
               example, character.only = TRUE, give.lines = TRUE)
sapply(lmex, length)

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(utils)
> png(filename="/home/ddbj/snapshot/RGM3/R_rel/result/utils/example.Rd_%03d_medium.png", width=480, height=480)
> ### Name: example
> ### Title: Run an Examples Section from the Online Help
> ### Aliases: example
> ### Keywords: documentation utilities
> 
> ### ** Examples
> 
> example(InsectSprays)

InsctS> require(stats); require(graphics)

InsctS> boxplot(count ~ spray, data = InsectSprays,
InsctS+         xlab = "Type of spray", ylab = "Insect count",
InsctS+         main = "InsectSprays data", varwidth = TRUE, col = "lightgray")

InsctS> fm1 <- aov(count ~ spray, data = InsectSprays)

InsctS> summary(fm1)
            Df Sum Sq Mean Sq F value Pr(>F)    
spray        5   2669   533.8    34.7 <2e-16 ***
Residuals   66   1015    15.4                   
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

InsctS> opar <- par(mfrow = c(2, 2), oma = c(0, 0, 1.1, 0))

InsctS> plot(fm1)

InsctS> fm2 <- aov(sqrt(count) ~ spray, data = InsectSprays)

InsctS> summary(fm2)
            Df Sum Sq Mean Sq F value Pr(>F)    
spray        5  88.44  17.688    44.8 <2e-16 ***
Residuals   66  26.06   0.395                   
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

InsctS> plot(fm2)

InsctS> par(opar)
> ## force use of the standard package 'stats':
> example("smooth", package = "stats", lib.loc = .Library)

smooth> require(graphics)

smooth> ## see also   demo(smooth) !
smooth> 
smooth> x1 <- c(4, 1, 3, 6, 6, 4, 1, 6, 2, 4, 2) # very artificial

smooth> (x3R <- smooth(x1, "3R")) # 2 iterations of "3"
3R Tukey smoother resulting from  smooth(x = x1, kind = "3R") 
 used 2 iterations
 [1] 3 3 3 6 6 4 4 4 2 2 2

smooth> smooth(x3R, kind = "S")
S Tukey smoother resulting from  smooth(x = x3R, kind = "S") 
 changed
 [1] 3 3 3 3 4 4 4 4 2 2 2

smooth> sm.3RS <- function(x, ...)
smooth+    smooth(smooth(x, "3R", ...), "S", ...)

smooth> y <- c(1, 1, 19:1)

smooth> plot(y, main = "misbehaviour of "3RSR"", col.main = 3)

smooth> lines(sm.3RS(y))

smooth> lines(smooth(y))

smooth> lines(smooth(y, "3RSR"), col = 3, lwd = 2)  # the horror

smooth> x <- c(8:10, 10, 0, 0, 9, 9)

smooth> plot(x, main = "breakdown of  3R  and  S  and hence  3RSS")

smooth> matlines(cbind(smooth(x, "3R"), smooth(x, "S"), smooth(x, "3RSS"), smooth(x)))

smooth> presidents[is.na(presidents)] <- 0 # silly

smooth> summary(sm3 <- smooth(presidents, "3R"))
3R Tukey smoother resulting from
 smooth(x = presidents, kind = "3R") ;  n = 120 
 used 4 iterations
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
    0.0    44.0    57.0    54.2    71.0    82.0 

smooth> summary(sm2 <- smooth(presidents,"3RSS"))
3RSS Tukey smoother resulting from
 smooth(x = presidents, kind = "3RSS") ;  n = 120 
 used 5 iterations
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
   0.00   44.00   57.00   55.45   69.00   82.00 

smooth> summary(sm  <- smooth(presidents))
3RS3R Tukey smoother resulting from
 smooth(x = presidents) ;  n = 120 
 used 7 iterations
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  24.00   44.00   57.00   55.88   69.00   82.00 

smooth> all.equal(c(sm2), c(smooth(smooth(sm3, "S"), "S")))  # 3RSS  === 3R S S
[1] TRUE

smooth> all.equal(c(sm),  c(smooth(smooth(sm3, "S"), "3R"))) # 3RS3R === 3R S 3R
[1] TRUE

smooth> plot(presidents, main = "smooth(presidents0, *) :  3R and default 3RS3R")

smooth> lines(sm3, col = 3, lwd = 1.5)

smooth> lines(sm, col = 2, lwd = 1.25)
> 
> ## set RNG *before* example as when R CMD check is run:
> 
> r1 <- example(quantile, setRNG = TRUE)

quantl> quantile(x <- rnorm(1001)) # Extremes & Quartiles by default
         0%         25%         50%         75%        100% 
-3.00804860 -0.69731820 -0.03472603  0.68924373  3.81027668 

quantl> quantile(x,  probs = c(0.1, 0.5, 1, 2, 5, 10, 50, NA)/100)
       0.1%        0.5%          1%          2%          5%         10% 
-2.99694930 -2.59232767 -2.42431731 -2.24515257 -1.72663060 -1.33880074 
        50%             
-0.03472603          NA 

quantl> ### Compare different types
quantl> p <- c(0.1, 0.5, 1, 2, 5, 10, 50)/100

quantl> res <- matrix(as.numeric(NA), 9, 7)

quantl> for(type in 1:9) res[type, ] <- y <- quantile(x,  p, type = type)

quantl> dimnames(res) <- list(1:9, names(y))

quantl> round(res, 3)
    0.1%   0.5%     1%     2%     5%    10%    50%
1 -2.997 -2.592 -2.424 -2.245 -1.727 -1.339 -0.035
2 -2.997 -2.592 -2.424 -2.245 -1.727 -1.339 -0.035
3 -3.008 -2.596 -2.433 -2.265 -1.733 -1.344 -0.036
4 -3.008 -2.596 -2.433 -2.264 -1.733 -1.344 -0.035
5 -3.002 -2.594 -2.428 -2.255 -1.730 -1.341 -0.035
6 -3.008 -2.596 -2.432 -2.264 -1.733 -1.343 -0.035
7 -2.997 -2.592 -2.424 -2.245 -1.727 -1.339 -0.035
8 -3.004 -2.595 -2.430 -2.258 -1.731 -1.342 -0.035
9 -3.004 -2.595 -2.429 -2.257 -1.730 -1.341 -0.035
> x1 <- rnorm(1)
> u <- runif(1)
> ## identical random numbers
> r2 <- example(quantile, setRNG = TRUE)

quantl> quantile(x <- rnorm(1001)) # Extremes & Quartiles by default
         0%         25%         50%         75%        100% 
-3.00804860 -0.69731820 -0.03472603  0.68924373  3.81027668 

quantl> quantile(x,  probs = c(0.1, 0.5, 1, 2, 5, 10, 50, NA)/100)
       0.1%        0.5%          1%          2%          5%         10% 
-2.99694930 -2.59232767 -2.42431731 -2.24515257 -1.72663060 -1.33880074 
        50%             
-0.03472603          NA 

quantl> ### Compare different types
quantl> p <- c(0.1, 0.5, 1, 2, 5, 10, 50)/100

quantl> res <- matrix(as.numeric(NA), 9, 7)

quantl> for(type in 1:9) res[type, ] <- y <- quantile(x,  p, type = type)

quantl> dimnames(res) <- list(1:9, names(y))

quantl> round(res, 3)
    0.1%   0.5%     1%     2%     5%    10%    50%
1 -2.997 -2.592 -2.424 -2.245 -1.727 -1.339 -0.035
2 -2.997 -2.592 -2.424 -2.245 -1.727 -1.339 -0.035
3 -3.008 -2.596 -2.433 -2.265 -1.733 -1.344 -0.036
4 -3.008 -2.596 -2.433 -2.264 -1.733 -1.344 -0.035
5 -3.002 -2.594 -2.428 -2.255 -1.730 -1.341 -0.035
6 -3.008 -2.596 -2.432 -2.264 -1.733 -1.343 -0.035
7 -2.997 -2.592 -2.424 -2.245 -1.727 -1.339 -0.035
8 -3.004 -2.595 -2.430 -2.258 -1.731 -1.342 -0.035
9 -3.004 -2.595 -2.429 -2.257 -1.730 -1.341 -0.035
> x2 <- rnorm(1)
> stopifnot(identical(r1, r2))
> ## but x1 and x2 differ since the RNG state from before example()
> ## differs and is restored!
> x1; x2
[1] -1.30006
[1] -0.6914321
> 
> ## Exploring examples code:
> ## How large are the examples of "lm...()" functions?
> lmex <- sapply(apropos("^lm", mode = "function"),
+                example, character.only = TRUE, give.lines = TRUE)
> sapply(lmex, length)
          lm       lm.fit lm.influence      lm.wfit 
          33           37           18           37 
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>


Created & Maintained by Osamu Ogasawara (osamu.ogasawara@gmail.com) and IMSBIO