In R, why does example() produce non-examples?

Question

If I type example(hist) in R, I get the following output:

hist> op <- par(mfrow = c(2, 2))

hist> hist(islands)

Hit <Return> to see next plot: 

The first line in the output doesn't even contain "hist". So how is it an example of how to use "hist"? Maybe I'm not understanding this, but all I wanted to see was examples of "hist" usage. Please help me interpret the output.

Answer 1

example(hist) produces these three images:

And the following text:

hist> op <- par(mfrow=c(2, 2))

hist> hist(islands)
Waiting to confirm page change...

hist> utils::str(hist(islands, col="gray", labels = TRUE))
List of 7
 $ breaks     : num [1:10] 0 2000 4000 6000 8000 10000 12000 14000 16000 18000
 $ counts     : int [1:9] 41 2 1 1 1 1 0 0 1
 $ intensities: num [1:9] 4.27e-04 2.08e-05 1.04e-05 1.04e-05 1.04e-05 ...
 $ density    : num [1:9] 4.27e-04 2.08e-05 1.04e-05 1.04e-05 1.04e-05 ...
 $ mids       : num [1:9] 1000 3000 5000 7000 9000 11000 13000 15000 17000
 $ xname      : chr "islands"
 $ equidist   : logi TRUE
 - attr(*, "class")= chr "histogram"

hist> hist(sqrt(islands), breaks = 12, col="lightblue", border="pink")

hist> ##-- For non-equidistant breaks, counts should NOT be graphed unscaled:
hist> r <- hist(sqrt(islands), breaks = c(4*0:5, 10*3:5, 70, 100, 140),
hist+           col='blue1')

hist> text(r$mids, r$density, r$counts, adj=c(.5, -.5), col='blue3')

hist> sapply(r[2:3], sum)
     counts intensities 
  48.000000    0.215625 

hist> sum(r$density * diff(r$breaks)) # == 1
[1] 1

hist> lines(r, lty = 3, border = "purple") # -> lines.histogram(*)

hist> par(op)

hist> require(utils) # for str

hist> str(hist(islands, breaks=12, plot= FALSE)) #-> 10 (~= 12) breaks
List of 7
 $ breaks     : num [1:10] 0 2000 4000 6000 8000 10000 12000 14000 16000 18000
 $ counts     : int [1:9] 41 2 1 1 1 1 0 0 1
 $ intensities: num [1:9] 4.27e-04 2.08e-05 1.04e-05 1.04e-05 1.04e-05 ...
 $ density    : num [1:9] 4.27e-04 2.08e-05 1.04e-05 1.04e-05 1.04e-05 ...
 $ mids       : num [1:9] 1000 3000 5000 7000 9000 11000 13000 15000 17000
 $ xname      : chr "islands"
 $ equidist   : logi TRUE
 - attr(*, "class")= chr "histogram"

hist> str(hist(islands, breaks=c(12,20,36,80,200,1000,17000), plot = FALSE))
List of 7
 $ breaks     : num [1:7] 12 20 36 80 200 1000 17000
 $ counts     : int [1:6] 12 11 8 6 4 7
 $ intensities: num [1:6] 0.03125 0.014323 0.003788 0.001042 0.000104 ...
 $ density    : num [1:6] 0.03125 0.014323 0.003788 0.001042 0.000104 ...
 $ mids       : num [1:6] 16 28 58 140 600 9000
 $ xname      : chr "islands"
 $ equidist   : logi FALSE
 - attr(*, "class")= chr "histogram"

hist> hist(islands, breaks=c(12,20,36,80,200,1000,17000), freq = TRUE,
hist+      main = "WRONG histogram") # and warning
Waiting to confirm page change...

hist> require(stats)

hist> set.seed(14)

hist> x <- rchisq(100, df = 4)

hist> ## Don't show: 
hist> op <- par(mfrow = 2:1, mgp = c(1.5, 0.6, 0), mar = .1 + c(3,3:1))

hist> ## End Don't show
hist> ## Comparing data with a model distribution should be done with qqplot()!
hist> qqplot(x, qchisq(ppoints(x), df = 4)); abline(0,1, col = 2, lty = 2)
Waiting to confirm page change...

hist> ## if you really insist on using hist() ... :
hist> hist(x, freq = FALSE, ylim = c(0, 0.2))

hist> curve(dchisq(x, df = 4), col = 2, lty = 2, lwd = 2, add = TRUE)

hist> ## Don't show: 
hist> par(op)

hist> ## End Don't show
hist> 
hist> 
hist>

If you don't hit Enter/Return, you just get what you posted, which is not the full example. Hitting Enter/Return advances the plot so you can see each image in order rather than all at once.