simEd (version 1.0.3)

ibinom: Random Variate Generation for the Binomial Distribution

Description

Generates random variates from the binomial distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability mass function and the empirical probability mass function of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

ibinom(u = runif(1), size, prob, 
         minPlotQuantile = 0,
         maxPlotQuantile = 1,
         plot            = TRUE,
         showCDF         = TRUE,
         showPMF         = FALSE,
         showECDF        = FALSE,
         show            = NULL,
         plotDelay       = 0,
         maxPlotTime     = 30,
         showTitle       = TRUE,
         respectLayout   = TRUE)

Arguments

u

vector of uniform(0,1) random numbers

size

integer number of trials (zero or more)

prob

probability of success on each trial

minPlotQuantile

controls the minimum quantile to appear in the plots

maxPlotQuantile

controls the maximum quantile to appear in the plots

plot

logical; if TRUE (default), one or more plots will appear (see parameters below); otherwise no plots appear

showCDF

logical; if TRUE (default), cdf plot appears, otherwise cdf plot is suppressed

showPMF

logical; if FALSE (default), pmf plot is suppressed, otherwise pmf plot appears

showECDF

logical; if FALSE (default), ecdf plot is suppressed, otherwise ecdf plot appears

show

shortcut way of denoting plots to display; either a binary vector of length three or an integer in [0,7] (see "Details" below)

plotDelay

delay, in seconds, between generation of the random variates

maxPlotTime

maximum time, in seconds, to plot all of the random variates

showTitle

logical; if TRUE (default), displays a title in the first of any displayed plots

respectLayout

logical; if TRUE (default), respects existing settings for device layout (see "Details" below)

Value

A vector of binomial random variates.

Details

Generates random variates from the binomial distribution, and optionally, illustrates

• the use of the inverse-cdf technique,

• the effect of random sampling variability in relation to the pmf and cdf.

When all of the graphics are requested,

• the first graph illustrates the use of the inverse-cdf technique by graphing the population cdf and the transformation of the random numbers to random variates,

• the second graph illustrates the effect of random sampling variability by graphing the population pmf and the empirical pmf associated with the random variates, and

• the third graph illustrates effect of random sampling variability by graphing the population cdf and the empirical cdf associated with the random variates.

All aspects of the random variate generation algorithm are output in red. All aspects of the population distribution are output in black.

The binomial distribution with parameters size = \(n\) and prob = \(p\) has pmf

$$p(x) = {n \choose x} p^x (1-p)^{(n-x)}$$

for \(x = 0, \ldots, n\). Note that binomial coefficients can be computed by choose in R.

The population mean and variance are \(E(X) = np\) and \(Var(X) = np(1-p)\).

The algorithm for generating random variates from the binomial distribution is synchronized (one random variate for each random number) and monotone in u. This means that the variates generated here might be useful in some variance reduction techniques used in Monte Carlo and discrete-event simulation.

Values from the u vector are plotted in the cdf plot along the vertical axis as red dots. A horizontal, dashed, red line extends from the red dot to the population cdf. At the intersection, a vertical, dashed red line extends downward to the horizontal axis, where a second red dot, denoting the associated binomial random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qbinom function to invert the values contained in u.

All of the elements of the u vector must be between 0 and 1. Alternatively, u can be NULL in which case plot(s) of the theoretical pmf and cdf are displayed according to plotting parameter values (defaulting to display of both the pmf and cdf).

The show parameter can be used as a shortcut way to denote plots to display. The argument to show can be either:

• a binary vector of length three, where the entries from left to right correspond to showCDF, showPMF, and showECDF, respectively. For each entry, a 1 indicates the plot should be displayed, and a 0 indicates the plot should be suppressed.

• an integer in [0,7] interpreted similar to Unix's chmod command. That is, the integer's binary representation can be transformed into a length-three vector discussed above (e.g., 6 corresponds to c(1,1,0)). See examples.

Any valid value for show takes precedence over existing individual values for showCDF, showPMF, and showECDF.

If respectLayout is TRUE, the function respects existing settings for device layout. Note, however, that if the number of plots requested (either via show or via showCDF, showPMF, and showECDF) exceeds the number of plots available in the current layout (as determined by prod(par("mfrow"))), the function will display all requested plots but will also display a warning message indicating that the current layout does not permit simultaneous viewing of all requested plots.

If respectLayout is FALSE, any existing user settings for device layout are ignored. That is, the function uses par to explicitly set mfrow sufficient to show all requested plots stacked vertically to align their horizontal axes, and then resets row, column, and margin settings to R default values on exit.

The minPlotQuantile and maxPlotQuantile arguments are present in order to compress the plots horizontally. The random variates generated are not impacted by these two arguments. Vertical, dotted, black lines are plotted at the associated quantiles on the plots.

The plotDelay and maxPlotTime arguments can be used to slow down the variate generation for classroom explanation.

In the plot associated with the pmf, the maximum plotting height is associated with 125% of the maximum height of pmf. Any histogram cell that extends above this limit will have three black dots appearing above it.

Examples

# NOT RUN {
ibinom(0.7, 7, 0.4)

par(mfrow = c(2,1)) # 2 rows, 1 col for CDF and PMF plots
set.seed(8675309)
ibinom(runif(10), 7, 0.4, showPMF = TRUE)

par(mfrow = c(1,1)) # 1 row, 1 col for PMF only plot
set.seed(8675309)
ibinom(runif(10), 7, 0.4, showPMF = TRUE, showCDF = FALSE)

par(mfrow = c(2,1)) # 2 rows, 1 col for CDF and PMF plots
ibinom(runif(120), 200, 0.5, showPMF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

# overlay visual exploration of ks.test results
par(mfrow = c(2,1)) # 2 rows, 1 col for CDF and ECDF plots
set.seed(54321)
vals <- ibinom(runif(10), 10, 0.3, showECDF = TRUE)
D <- as.numeric(ks.test(vals, "pbinom", 10, 0.3)$statistic)
x <- 2.5
y <- pbinom(x, 10, 0.3)
segments(x, y, x, y + D, col = "darkgreen", lwd = 3)

# plot the PMF and CDF without any variates
par(mfrow = c(2,1)) # 2 rows, 1 col for PMF and CDF plots
ibinom(NULL, 10, 0.3)

# plot CDF with inversion and PMF using show
par(mfrow = c(2,1)) # 2 rows, 1 col for CDF and PMF plots
ibinom(runif(10), 10, 0.3, show = c(1,1,0))
ibinom(runif(10), 10, 0.3, show = 6)

# plot CDF with inversion and ECDF using show
par(mfrow = c(2,1)) # 2 rows, 1 col for CDF and ECDF plots
ibinom(runif(10), 10, 0.3, show = c(1,0,1))
ibinom(runif(10), 10, 0.3, show = 5)

# plot CDF with inversion, PMF, and ECDF using show
par(mfrow = c(3,1)) # 3 rows, 1 col for CDF, PMF, and ECDF plots
ibinom(runif(10), 10, 0.3, show = c(1,1,1))
ibinom(runif(10), 10, 0.3, show = 7)

# plot three different CDF+PMF+ECDF vertical displays
par(mfcol = c(3,3))  # 3 rows, 3 cols, filling columns before rows
set.seed(8675309)
ibinom(runif(20), size = 10, prob = 0.3, show = 7)
ibinom(runif(20), size = 10, prob = 0.3, show = 7)
ibinom(runif(20), size = 10, prob = 0.3, show = 7)

# plot three different CDF+PMF+ECDF horizontal displays, with title only
# on the first display
par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
set.seed(8675309)
ibinom(runif(20), size = 10, prob = 0.3, show = 7)
ibinom(runif(20), size = 10, prob = 0.3, show = 7, showTitle = FALSE)
ibinom(runif(20), size = 10, prob = 0.3, show = 7, showTitle = FALSE)

# exhibit use of the respectLayout = FALSE option
par(mfrow = c(3,3))  # this will be ignored below since respectLayout = FALSE
set.seed(8675309)
ibinom(runif(20), size = 10, prob = 0.3, show = 7, respectLayout = FALSE)
par("mfrow")  # will have been reset c(1,1)
par("mar")    # will have been reset to c(5.1, 4.1, 4.1, 2.1)

# }