Package 'simEd'

Description

Contains various functions to be used for simulation education, including simple Monte Carlo simulation functions, queueing simulation functions, variate generation functions capable of producing independent streams and antithetic variates, functions for illustrating random variate generation for various discrete and continuous distributions, and functions to compute time-persistent statistics. Also contains functions for visualizing: event-driven details of a single-server queue model; a Lehmer random number generator; variate generation via acceptance-rejection; and of generating a non-homogeneous Poisson process via thinning. Also contains two queueing data sets (one fabricated, one real-world) to facilitate input modeling. More details on the use of these functions can be found in Lawson and Leemis (2015) <doi:10.1109/WSC.2017.8248124>, in Kudlay, Lawson, and Leemis (2020) <doi:10.1109/WSC48552.2020.9384010>, and in Lawson and Leemis (2021) <doi:10.1109/WSC52266.2021.9715299>.

Request From Authors: If you adopt and use this package for your simulation course, we would greatly appreciate were you to email us (addresses below) to let us know, as we would like to maintain a list of adopters. Please include your name, university/affiliation, and course name/number. Thanks!

Details

The goal of this package is to facilitate use of R for an introductory course in discrete-event simulation.

This package contains animation functions for visualizing:

• event-driven details of a single-server queue model (ssqvis);

• a Lehmer random number generator (lehmer);

• variate generation via acceptance-rejection (accrej);

• generation of a non-homogeneous Poisson process via thinning (thinning).

The package contains variate generators capable of independent streams (based on Josef Leydold's rstream package) and antithetic variates for four discrete and eleven continuous distributions:

• discrete: vbinom, vgeom, vnbinom, vpois

• continuous: vbeta, vcauchy, vchisq, vexp, vgamma, vlnorm, vlogis, vnorm, vt, vunif, vweibull

All of the variate generators use inversion, and are therefore monotone and synchronized.

The package contains functions to visualize variate generation for the same four discrete and eleven continuous distributions:

• discrete: ibinom, igeom, inbinom, ipois

• continuous: ibeta, icauchy, ichisq, iexp, igamma, ilnorm, ilogis, inorm, it, iunif, iweibull

The package also contains functions that are event-driven simulation implementations of a single-server single-queue system and of a multiple-server single-queue system:

• single-server: ssq

• multiple-server: msq

Both queueing functions are extensible in allowing the user to provide custom arrival and service process functions. As of version 2.0.0, both of these functions provide animation capability.

The package contains functions that implement Monte Carlo simulation approaches for estimating probabilities in two different dice games:

• Galileo's dice problem: galileo

• craps: craps

The package contains three functions for computing time-persistent statistics:

• time-average mean: meanTPS

• time-average standard deviation: sdTPS

• time-average quantiles: quantileTPS

The package also masks two functions from the stats package:

• set.seed, which explicitly calls the stats version in addition to setting up seeds for the independent streams in the package;

• sample, which provides capability to use independent streams and antithetic variates.

Finally, the package provides two queueing data sets to facilitate input modeling:

• queueTrace, which contains 1000 arrival times and 1000 service times (all fabricated) for a single-server queueing system;

• tylersGrill, which contains 1434 arrival times and 110 (sampled) service times corresponding to actual data collected during one business day at Tyler's Grill at the University of Richmond.

Acknowledgments

The authors would like to thank Dr. Barry L. Nelson, Walter P. Murphy Professor in the Department of Industrial Engineering & Management Sciences at Northwestern University, for meaningful feedback during the development of this package.

Author(s)

Barry Lawson [aut, cre, cph], Larry Leemis [aut], Vadim Kudlay [aut] Maintainer: Barry Lawson <[email protected]>

Description

This function animates the process of generating variates via acceptance-rejection for a specified density function (pdf) bounded by a specified majorizing function.

Usage

accrej(
  n = 20,
  pdf = function(x) dbeta(x, 3, 2),
  majorizingFcn = NULL,
  majorizingFcnType = NULL,
  support = c(0, 1),
  seed = NA,
  maxTrials = Inf,
  plot = TRUE,
  showTitle = TRUE,
  plotDelay = plot * -1
)

Arguments

Details

There are three modes for visualizing the acceptance-rejection algorithm for generating random variates from a particular probability distribution:

• interactive advance (plotDelay = -1), where pressing the 'ENTER' key advances to the next step (an accepted random variate) in the algorithm, typing 'j #' jumps ahead # steps, typing 'q' quits immediately, and typing 'e' proceeds to the end;

• automatic advance (plotDelay > 0); or

• final visualization only (plotDelay = 0).

As an alternative to visualizing, variates can be generated

Value

Returns the n generated variates accepted.

Examples

accrej(n = 20, seed = 8675309, plotDelay = 0)
accrej(n = 10, seed = 8675309, plotDelay = 0.1)

# interactive mode
if (interactive()) {
  accrej(n = 10, seed = 8675309, plotDelay = -1)
}

# Piecewise-constant majorizing function
m <- function(x) {
  if      (x < 0.3)  1.0 
  else if (x < 0.85) 2.5
  else               1.5
}
accrej(n = 10, seed = 8675309, majorizingFcn = m, plotDelay = 0)

# Piecewise-constant majorizing function as data frame
m <- data.frame(
  x = c(0.0, 0.3, 0.85, 1.0),
  y = c(1.0, 1.0, 2.5,  1.5))
accrej(n = 10, seed = 8675309, majorizingFcn = m, 
       majorizingFcnType = "pwc", plotDelay = 0)

# Piecewise-linear majorizing function as data frame
m <- data.frame(
   x = c(0.0, 0.1, 0.3, 0.5, 0.7, 1.0), 
   y = c(0.0, 0.5, 1.1, 2.2, 1.9, 1.0))
accrej(n = 10, seed = 8675309, majorizingFcn = m, 
       majorizingFcnType = "pwl", plotDelay = 0)

# invalid majorizing function; should give warning
try(accrej(n = 20, majorizingFcn = function(x) dbeta(x, 1, 3), plotDelay = 0))

# Piecewise-linear majorizing function with power-distribution density function
m <- data.frame(x = c(0, 1, 2), y = c(0, 0.375, 1.5))
samples <- accrej(n = 10, pdf = function(x) (3 / 8) * x ^ 2, support = c(0,2),
                  majorizingFcn = m, majorizingFcnType = "pwl", plotDelay = 0)

Description

A Monte Carlo simulation of the dice game "craps". Returns a point estimate of the probability of winning craps using fair dice.

Usage

craps(nrep = 1000, seed = NA, showProgress = TRUE)

Arguments

Details

Implements a Monte Carlo simulation of the dice game craps played with fair dice. A single play of the game proceeds as follows:

• Two fair dice are rolled. If the sum is 7 or 11, the player wins immediately; if the sum is 2, 3, or 12, the player loses immediately. Otherwise the sum becomes the point.

• The two dice continue to be rolled until either a sum of 7 is rolled (in which case the player loses) or a sum equal to the point is rolled (in which case the player wins).

The simulation involves nrep replications of the game.

Note: When the value of nrep is large, the function will execute noticeably faster when showProgress is set to FALSE.

Value

Point estimate of the probability of winning at craps (a real-valued scalar).

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

base::set.seed

Examples

# set the initial seed externally using set.seed;
 # then use that current state of the generator with default nrep = 1000
 set.seed(8675309)
 craps()  # uses state of generator set above

 # explicitly set the seed in the call to the function,
 # using default nrep = 1000
 craps(seed = 8675309)

 # use the current state of the random number generator with nrep = 10000
 prob <- craps(10000)

 # explicitly set nrep = 10000 and seed = 8675309
 prob <- craps(10000, 8675309)

Description

A Monte Carlo simulation of the Galileo's Dice problem. Returns a vector containing point estimates of the probabilities of the sum of three fair dice for sums 3, 4, $\ldots$, 18.

Usage

galileo(nrep = 1000, seed = NA, showProgress = TRUE)

Arguments

Details

Implements a Monte Carlo simulation of the Galileo's Dice problem. The simulation involves nrep replications of rolling three dice and summing the up-faces, and computing point estimates of the probabilities of each possible sum 3, 4, $\ldots$, 18.

Note: When the value of nrep is large, the function will execute noticeably faster when showProgress is set to FALSE.

Value

An 18-element vector of point estimates of the probabilities. (Because a sum of 1 or 2 is not possible, the corresponding entries in the returned vector have value NA.)

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

Examples

# set the initial seed externally using set.seed;
 # then use that current state of the generator with default nrep = 1000
 set.seed(8675309)
 galileo()  # uses state of generator set above

 # explicitly set the seed in the call to the function,
 # using default nrep = 1000
 galileo(seed = 8675309)

 # use the current state of the random number generator with nrep = 10000
 prob <- galileo(10000)

 # explicitly set nrep = 10000 and seed = 8675309
 prob <- galileo(10000, 8675309)

Description

Generates random variates from the Beta distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability density function and a histogram of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

ibeta(
  u = runif(1),
  shape1,
  shape2,
  ncp = 0,
  minPlotQuantile = 0.01,
  maxPlotQuantile = 0.95,
  plot = TRUE,
  showCDF = TRUE,
  showPDF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

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

• the use of the inverse-CDF technique,

• the effect of random sampling variability in relation to the PDF 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 PDF and the histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The beta distribution has density

\deqn{f(x) = \frac{\Gamma(a+b)}{\Gamma(a) \ \Gamma(b)} x^{a-1}(1-x)^{b-1}}{
          f(x) = Gamma(a+b)/(Gamma(a)Gamma(b)) x^(a-1)(1-x)^(b-1)}

for $a > 0$, $b > 0$ and $0 \leq x \leq 1$ where the boundary values at $x=0$ or $x=1$ are defined as by continuity (as limits).

The mean is $\frac{a}{a+b}$ and the variance is ${ab}{(a+b)^2 (a+b+1)}$

The algorithm for generating random variates from the beta 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated beta random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qbeta 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 PDF and cdf are displayed according to plotting parameter values (defaulting to display of both the PDF 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, showPDF, 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 the Unix 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, showPDF, 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PDF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Beta random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rbeta

stats::runif, simEd::vunif

Examples

ibeta(0.5, shape1 = 3, shape2 = 1, ncp = 2)

 set.seed(8675309)
 ibeta(runif(10), 3, 1, showPDF = TRUE)

 set.seed(8675309)
 ibeta(runif(10), 3, 1, showECDF = TRUE)

 set.seed(8675309)
 ibeta(runif(10), 3, 1, showPDF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 ibeta(runif(10), 3, 1, showPDF = TRUE, showCDF = FALSE)

 ibeta(runif(100), 3, 1, showPDF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PDF and CDF without any variates
 ibeta(NULL, 3, 1, showPDF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PDF using show
 ibeta(runif(10), 3, 1, show = c(1,1,0))
 ibeta(runif(10), 3, 1, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 ibeta(vunif(10), 3, 1, show = c(1,0,1))
 ibeta(vunif(10), 3, 1, show = 5)

 # plot CDF with inversion, PDF, and ECDF using show
 ibeta(vunif(10), 3, 1, show = c(1,1,1))
 ibeta(vunif(10), 3, 1, show = 7)

 # plot three different CDF+PDF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 ibeta(runif(20), 3, 1, show = 7, respectLayout = TRUE, restorePar = FALSE)
 ibeta(runif(20), 3, 1, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 ibeta(runif(20), 3, 1, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 ibeta(runif(10), 3, 1, show = 7, plotDelay = 0.1)

 # display animation of CDF and PDF components only
 ibeta(runif(10), 3, 1, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   ibeta(runif(10), 3, 1, show = 7, plotDelay = -1)
 }

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 a histogram 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 = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

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 histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

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

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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored 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 the Unix 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PMF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Binomial random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rbinom

stats::runif, simEd::vunif

Examples

ibinom(0.5, size = 7, prob = 0.4,)

 set.seed(8675309)
 ibinom(runif(10), 10, 0.3, showPMF = TRUE)

 set.seed(8675309)
 ibinom(runif(10), 10, 0.3, showECDF = TRUE)

 set.seed(8675309)
 ibinom(runif(10), 10, 0.3, showPMF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 ibinom(runif(10), 10, 0.3, showPMF = TRUE, showCDF = FALSE)

 ibinom(runif(100), 10, 0.3, showPMF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PMF and CDF without any variates
 ibinom(NULL, 10, 0.3, showPMF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PMF using show
 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, using vunif
 ibinom(vunif(10), 10, 0.3, show = c(1,0,1))
 ibinom(vunif(10), 10, 0.3, show = 5)

 # plot CDF with inversion, PMF, and ECDF using show
 ibinom(vunif(10), 10, 0.3, show = c(1,1,1))
 ibinom(vunif(10), 10, 0.3, show = 7)

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

 # display animation of all components
 ibinom(runif(10), 10, 0.3, show = 7, plotDelay = 0.1)

 # display animation of CDF and PMF components only
 ibinom(runif(10), 10, 0.3, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   ibinom(runif(10), 10, 0.3, show = 7, plotDelay = -1)
 }

Description

Generates random variates from the Cauchy distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability density function and a histogram of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

icauchy(
  u = runif(1),
  location = 0,
  scale = 1,
  minPlotQuantile = 0.05,
  maxPlotQuantile = 0.95,
  plot = TRUE,
  showCDF = TRUE,
  showPDF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

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

• the use of the inverse-CDF technique,

• the effect of random sampling variability in relation to the PDF 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 PDF and the histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The Cauchy distribution has density
\deqn{f(x) = \frac{1}{\pi s} \ \left(1 + \left( \frac{x - l}{s} \right)^2
              \right)^{-1}}{
          f(x) = 1 / (\pi s (1 + ((x-l)/s)^2))}

for all $x$.

The mean is $a/(a+b)$ and the variance is $ab/((a+b)^2 (a+b+1))$.

The algorithm for generating random variates from the Cauchy 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated Cauchy random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qcauchy 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 PDF and cdf are displayed according to plotting parameter values (defaulting to display of both the PDF 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, showPDF, 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 the Unix 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, showPDF, 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PDF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Cauchy random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rcauchy

stats::runif, simEd::vunif

Examples

icauchy(0.5, location = 3, scale = 1)

 set.seed(8675309)
 icauchy(runif(10), 0, 3, showPDF = TRUE)

 set.seed(8675309)
 icauchy(runif(10), 0, 3, showECDF = TRUE)

 set.seed(8675309)
 icauchy(runif(10), 0, 3, showPDF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 icauchy(runif(10), 0, 3, showPDF = TRUE, showCDF = FALSE)

 icauchy(runif(100), 0, 3, showPDF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PDF and CDF without any variates
 icauchy(NULL, 0, 3, showPDF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PDF using show
 icauchy(runif(10), 0, 3, show = c(1,1,0))
 icauchy(runif(10), 0, 3, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 icauchy(vunif(10), 0, 3, show = c(1,0,1))
 icauchy(vunif(10), 0, 3, show = 5)

 # plot CDF with inversion, PDF, and ECDF using show
 icauchy(vunif(10), 0, 3, show = c(1,1,1))
 icauchy(vunif(10), 0, 3, show = 7)

 # plot three different CDF+PDF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 icauchy(runif(20), 0, 3, show = 7, respectLayout = TRUE, restorePar = FALSE)
 icauchy(runif(20), 0, 3, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 icauchy(runif(20), 0, 3, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 icauchy(runif(10), 0, 3, show = 7, plotDelay = 0.1)

 # display animation of CDF and PDF components only
 icauchy(runif(10), 0, 3, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   icauchy(runif(10), 0, 3, show = 7, plotDelay = -1)
 }

Description

Generates random variates from the Chi-Squared distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability density function and a histogram of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

ichisq(
  u = runif(1),
  df,
  ncp = 0,
  minPlotQuantile = 0.01,
  maxPlotQuantile = 0.99,
  plot = TRUE,
  showCDF = TRUE,
  showPDF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

Generates random variates from the Chi-Squared distribution, and optionally, illustrates

• the use of the inverse-CDF technique,

• the effect of random sampling variability in relation to the PDF 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 PDF and the histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The chi-squared distribution with df = $n \geq 0$ degrees of freedom has density

\deqn{f_n(x) = \frac{1}{2^{n/2} \ \Gamma(n/2)} x^{n/2-1} e^{-x/2}}{
          f_n(x) = 1 / (2^(n/2) \Gamma(n/2)) x^(n/2-1) e^(-x/2)}

for $x > 0$. The mean and variance are $n$ and $2n$.

The non-central chi-squared distribution with df = n degrees of freedom and non-centrality parameter ncp $= \lambda$ has density

\deqn{f(x) = e^{-\lambda/2} \sum_{r=0}^\infty \frac{(\lambda/2)^r}{r!} f_{n + 2r}(x)}{
          f(x) = exp(-\lambda/2) SUM_{r=0}^\infty ((\lambda/2)^r / r!) dchisq(x, df + 2r)}

for $x \geq 0$.

The algorithm for generating random variates from the chi-squared 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated chi-squared random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qchisq 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 PDF and cdf are displayed according to plotting parameter values (defaulting to display of both the PDF 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, showPDF, 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 the Unix 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, showPDF, 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PDF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Chi-Squared random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rchisq

stats::runif, simEd::vunif

Examples

ichisq(0.5, df = 3, ncp = 2)

 set.seed(8675309)
 ichisq(runif(10), 3, showPDF = TRUE)

 set.seed(8675309)
 ichisq(runif(10), 3, showECDF = TRUE)

 set.seed(8675309)
 ichisq(runif(10), 3, showPDF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 ichisq(runif(10), 3, showPDF = TRUE, showCDF = FALSE)

 ichisq(runif(100), 3, showPDF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PDF and CDF without any variates
 ichisq(NULL, 3, showPDF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PDF using show
 ichisq(runif(10), 3, show = c(1,1,0))
 ichisq(runif(10), 3, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 ichisq(vunif(10), 3, show = c(1,0,1))
 ichisq(vunif(10), 3, show = 5)

 # plot CDF with inversion, PDF, and ECDF using show
 ichisq(vunif(10), 3, show = c(1,1,1))
 ichisq(vunif(10), 3, show = 7)

 # plot three different CDF+PDF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 ichisq(runif(20), 3, show = 7, respectLayout = TRUE, restorePar = FALSE)
 ichisq(runif(20), 3, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 ichisq(runif(20), 3, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 ichisq(runif(10), 3, show = 7, plotDelay = 0.1)

 # display animation of CDF and PDF components only
 ichisq(runif(10), 3, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   ichisq(runif(10), 3, show = 7, plotDelay = -1)
 }

Description

Generates random variates from the Exponential distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability density function and a histogram of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

iexp(
  u = runif(1),
  rate = 1,
  minPlotQuantile = 0,
  maxPlotQuantile = 0.99,
  plot = TRUE,
  showCDF = TRUE,
  showPDF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

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

• the use of the inverse-CDF technique,

• the effect of random sampling variability in relation to the PDF 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 PDF and the histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

 The exponential distribution with rate \eqn{\lambda} has density

     \deqn{f(x) = \lambda e^{-\lambda x}}{
               f(x) = \lambda e^(-\lambda x)}

 for \eqn{x \geq 0}.

The algorithm for generating random variates from the exponential 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated exponential random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qexp 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 PDF and cdf are displayed according to plotting parameter values (defaulting to display of both the PDF 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, showPDF, 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 the Unix 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, showPDF, 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PDF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Exponential random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rexp

stats::runif, simEd::vunif

Examples

iexp(0.5, rate = 3)

 set.seed(8675309)
 iexp(runif(10), 2, showPDF = TRUE)

 set.seed(8675309)
 iexp(runif(10), 2, showECDF = TRUE)

 set.seed(8675309)
 iexp(runif(10), 2, showPDF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 iexp(runif(10), 2, showPDF = TRUE, showCDF = FALSE)

 iexp(runif(100), 2, showPDF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PDF and CDF without any variates
 iexp(NULL, 2, showPDF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PDF using show
 iexp(runif(10), 2, show = c(1,1,0))
 iexp(runif(10), 2, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 iexp(vunif(10), 2, show = c(1,0,1))
 iexp(vunif(10), 2, show = 5)

 # plot CDF with inversion, PDF, and ECDF using show
 iexp(vunif(10), 2, show = c(1,1,1))
 iexp(vunif(10), 2, show = 7)

 # plot three different CDF+PDF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 iexp(runif(20), 2, show = 7, respectLayout = TRUE, restorePar = FALSE)
 iexp(runif(20), 2, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 iexp(runif(20), 2, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 iexp(runif(10), 2, show = 7, plotDelay = 0.1)

 # display animation of CDF and PDF components only
 iexp(runif(10), 2, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   iexp(runif(10), 2, show = 7, plotDelay = -1)
 }

  # overlay visual exploration of ks.test results
  oldpar <- par(no.readonly = TRUE)
  set.seed(54321)
  vals <- iexp(runif(10), 2, showECDF = TRUE, restorePar = FALSE)
  D <- as.numeric(ks.test(vals, "pexp", 2)$statistic)
  for (x in seq(0.25, 0.65, by = 0.05)) {
    y <- pexp(x, 2)
    segments(x, y, x, y + D, col = "darkgreen", lwd = 2, xpd = NA)
  }
  par(oldpar) # restore original par values, since restorePar = FALSE above

Description

Generates random variates from the FALSE distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability density function and a histogram of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

ifd(
  u = runif(1),
  df1,
  df2,
  ncp = 0,
  minPlotQuantile = 0.01,
  maxPlotQuantile = 0.99,
  plot = TRUE,
  showCDF = TRUE,
  showPDF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

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

• the use of the inverse-CDF technique,

• the effect of random sampling variability in relation to the PDF 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 PDF and the histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The F distribution with df1 $= n_1$ and df2 $= n_2$ degrees of freedom has density

$f(x) = \frac {\Gamma(n_1/2 + n_2/2)} {\Gamma(n_1/2) \ \Gamma(n_2/2)} \left( \frac{n_1}{n_2} \right)^{n_1/2} x^{n_1/2 - 1} \left( 1 + \frac{n_1x}{n_2} \right) ^ {-(n_1 + n_2)/2}$

for $x > 0$.

The algorithm for generating random variates from the FALSE 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated FALSE random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qf 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 PDF and cdf are displayed according to plotting parameter values (defaulting to display of both the PDF 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, showPDF, 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 the Unix 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, showPDF, 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PDF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of FALSE random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rf

stats::runif, simEd::vunif

Examples

ifd(0.5, df1 = 1, df2 = 2, ncp = 10)

 set.seed(8675309)
 ifd(runif(10), 5, 5, showPDF = TRUE)

 set.seed(8675309)
 ifd(runif(10), 5, 5, showECDF = TRUE)

 set.seed(8675309)
 ifd(runif(10), 5, 5, showPDF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 ifd(runif(10), 5, 5, showPDF = TRUE, showCDF = FALSE)

 ifd(runif(100), 5, 5, showPDF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PDF and CDF without any variates
 ifd(NULL, 5, 5, showPDF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PDF using show
 ifd(runif(10), 5, 5, show = c(1,1,0))
 ifd(runif(10), 5, 5, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 ifd(vunif(10), 5, 5, show = c(1,0,1))
 ifd(vunif(10), 5, 5, show = 5)

 # plot CDF with inversion, PDF, and ECDF using show
 ifd(vunif(10), 5, 5, show = c(1,1,1))
 ifd(vunif(10), 5, 5, show = 7)

 # plot three different CDF+PDF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 ifd(runif(20), 5, 5, show = 7, respectLayout = TRUE, restorePar = FALSE)
 ifd(runif(20), 5, 5, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 ifd(runif(20), 5, 5, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 ifd(runif(10), 5, 5, show = 7, plotDelay = 0.1)

 # display animation of CDF and PDF components only
 ifd(runif(10), 5, 5, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   ifd(runif(10), 5, 5, show = 7, plotDelay = -1)
 }

Description

Generates random variates from the Gamma distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability density function and a histogram of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

igamma(
  u = runif(1),
  shape,
  rate = 1,
  scale = 1/rate,
  minPlotQuantile = 0,
  maxPlotQuantile = 0.95,
  plot = TRUE,
  showCDF = TRUE,
  showPDF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

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

• the use of the inverse-CDF technique,

• the effect of random sampling variability in relation to the PDF 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 PDF and the histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The gamma distribution with parameters \code{shape} = \eqn{a} and
\code{scale} = \eqn{s} has density

     \deqn{f(x) = \frac{1}{s^a\, \Gamma(a)} x^{a-1} e^{-x/s}}{
               f(x) = 1/(s^a Gamma(a)) x^(a-1) e^(-x/s)}

for \eqn{x \ge 0}, \eqn{a > 0}, and \eqn{s > 0}.
(Here \eqn{\Gamma(a)}{Gamma(a)} is the function implemented by
R's \code{\link[base:Special]{gamma}()} and defined in its help.)

The population mean and variance are \eqn{E(X) = as}
and \eqn{Var(X) = as^2}.

The algorithm for generating random variates from the gamma 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated gamma random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qgamma 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 PDF and cdf are displayed according to plotting parameter values (defaulting to display of both the PDF 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, showPDF, 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 the Unix 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, showPDF, 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PDF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Gamma random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rgamma

stats::runif, simEd::vunif

Examples

igamma(0.5, shape = 5, scale = 3)

 set.seed(8675309)
 igamma(runif(10), 3, 2, showPDF = TRUE)

 set.seed(8675309)
 igamma(runif(10), 3, 2, showECDF = TRUE)

 set.seed(8675309)
 igamma(runif(10), 3, 2, showPDF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 igamma(runif(10), 3, 2, showPDF = TRUE, showCDF = FALSE)

 igamma(runif(100), 3, 2, showPDF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PDF and CDF without any variates
 igamma(NULL, 3, 2, showPDF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PDF using show
 igamma(runif(10), 3, 2, show = c(1,1,0))
 igamma(runif(10), 3, 2, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 igamma(vunif(10), 3, 2, show = c(1,0,1))
 igamma(vunif(10), 3, 2, show = 5)

 # plot CDF with inversion, PDF, and ECDF using show
 igamma(vunif(10), 3, 2, show = c(1,1,1))
 igamma(vunif(10), 3, 2, show = 7)

 # plot three different CDF+PDF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 igamma(runif(20), 3, 2, show = 7, respectLayout = TRUE, restorePar = FALSE)
 igamma(runif(20), 3, 2, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 igamma(runif(20), 3, 2, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 igamma(runif(10), 3, 2, show = 7, plotDelay = 0.1)

 # display animation of CDF and PDF components only
 igamma(runif(10), 3, 2, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   igamma(runif(10), 3, 2, show = 7, plotDelay = -1)
 }

  # overlay visual exploration of ks.test results
  oldpar <- par(no.readonly = TRUE)
  set.seed(54321)
  vals <- igamma(runif(10), 3, 2, showECDF = TRUE, restorePar = FALSE)
  D <- as.numeric(ks.test(vals, "pgamma", 3, 2)$statistic)
  for (x in seq(1.20, 1.60, by = 0.05)) {
    y <- pgamma(x, 3, 2)
    segments(x, y, x, y + D, col = "darkgreen", lwd = 2, xpd = NA)
  }
  par(oldpar) # restore original par values, since restorePar = FALSE above

Description

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

Usage

igeom(
  u = runif(1),
  prob,
  minPlotQuantile = 0,
  maxPlotQuantile = 0.95,
  plot = TRUE,
  showCDF = TRUE,
  showPMF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

Generates random variates from the Geometric 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 histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The geometric distribution with parameter prob = $p$ has density

$p(x) = p (1-p)^x$

for $x = 0, 1, 2, \ldots$, where $0 < p \le 1$.

The algorithm for generating random variates from the geometric 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated geometric random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qgeom 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 the Unix 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PMF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Geometric random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rgeom

stats::runif, simEd::vunif

Examples

igeom(0.5, prob = 0.25)

 set.seed(8675309)
 igeom(runif(10), 0.4, showPMF = TRUE)

 set.seed(8675309)
 igeom(runif(10), 0.4, showECDF = TRUE)

 set.seed(8675309)
 igeom(runif(10), 0.4, showPMF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 igeom(runif(10), 0.4, showPMF = TRUE, showCDF = FALSE)

 igeom(runif(100), 0.4, showPMF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PMF and CDF without any variates
 igeom(NULL, 0.4, showPMF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PMF using show
 igeom(runif(10), 0.4, show = c(1,1,0))
 igeom(runif(10), 0.4, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 igeom(vunif(10), 0.4, show = c(1,0,1))
 igeom(vunif(10), 0.4, show = 5)

 # plot CDF with inversion, PMF, and ECDF using show
 igeom(vunif(10), 0.4, show = c(1,1,1))
 igeom(vunif(10), 0.4, show = 7)

 # plot three different CDF+PMF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 igeom(runif(20), 0.4, show = 7, respectLayout = TRUE, restorePar = FALSE)
 igeom(runif(20), 0.4, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 igeom(runif(20), 0.4, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 igeom(runif(10), 0.4, show = 7, plotDelay = 0.1)

 # display animation of CDF and PMF components only
 igeom(runif(10), 0.4, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   igeom(runif(10), 0.4, show = 7, plotDelay = -1)
 }

Description

Generates random variates from the Log-Normal distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability density function and a histogram of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

ilnorm(
  u = runif(1),
  meanlog = 0,
  sdlog = 1,
  minPlotQuantile = 0,
  maxPlotQuantile = 0.95,
  plot = TRUE,
  showCDF = TRUE,
  showPDF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

Generates random variates from the Log-Normal distribution, and optionally, illustrates

• the use of the inverse-CDF technique,

• the effect of random sampling variability in relation to the PDF 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 PDF and the histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The log-normal distribution has density

\deqn{f(x) = \frac{1}{\sqrt{2 \pi} \sigma x}
                 e^{-(\log{x} - \mu)^2 / (2 \sigma^2)} }{
          f(x) = 1/(\sqrt(2 \pi) \sigma x) e^-((log x - \mu)^2 / (2 \sigma^2))}

where $\mu$ and $\sigma$ are the mean and standard deviation of the logarithm.

The mean is $E(X) = \exp(\mu + 1/2 \sigma^2)$, the median is $med(X) = \exp(\mu)$, and the variance is $Var(X) = \exp(2\times \mu +\sigma^2)\times (\exp(\sigma^2)-1)$ and hence the coefficient of variation is $sqrt(\exp(\sigma^2)-1)$ which is approximately $\sigma$ when small (e.g., $\sigma < 1/2$).

The algorithm for generating random variates from the log-normal 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated log-normal random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qlnorm 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 PDF and cdf are displayed according to plotting parameter values (defaulting to display of both the PDF 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, showPDF, 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 the Unix 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, showPDF, 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PDF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Log-Normal random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rlnorm

stats::runif, simEd::vunif

Examples

ilnorm(0.5, meanlog = 5, sdlog = 0.5)

 set.seed(8675309)
 ilnorm(runif(10), 8, 2, showPDF = TRUE)

 set.seed(8675309)
 ilnorm(runif(10), 8, 2, showECDF = TRUE)

 set.seed(8675309)
 ilnorm(runif(10), 8, 2, showPDF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 ilnorm(runif(10), 8, 2, showPDF = TRUE, showCDF = FALSE)

 ilnorm(runif(100), 8, 2, showPDF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PDF and CDF without any variates
 ilnorm(NULL, 8, 2, showPDF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PDF using show
 ilnorm(runif(10), 8, 2, show = c(1,1,0))
 ilnorm(runif(10), 8, 2, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 ilnorm(vunif(10), 8, 2, show = c(1,0,1))
 ilnorm(vunif(10), 8, 2, show = 5)

 # plot CDF with inversion, PDF, and ECDF using show
 ilnorm(vunif(10), 8, 2, show = c(1,1,1))
 ilnorm(vunif(10), 8, 2, show = 7)

 # plot three different CDF+PDF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 ilnorm(runif(20), 8, 2, show = 7, respectLayout = TRUE, restorePar = FALSE)
 ilnorm(runif(20), 8, 2, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 ilnorm(runif(20), 8, 2, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 ilnorm(runif(10), 8, 2, show = 7, plotDelay = 0.1)

 # display animation of CDF and PDF components only
 ilnorm(runif(10), 8, 2, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   ilnorm(runif(10), 8, 2, show = 7, plotDelay = -1)
 }

Description

Generates random variates from the Logistic distribution by inversion. Optionally graphs the population cumulative distribution function and associated random variates, the population probability density function and a histogram of the random variates, and the empirical cumulative distribution function versus the population cumulative distribution function.

Usage

ilogis(
  u = runif(1),
  location = 0,
  scale = 1,
  minPlotQuantile = 0.01,
  maxPlotQuantile = 0.99,
  plot = TRUE,
  showCDF = TRUE,
  showPDF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

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

• the use of the inverse-CDF technique,

• the effect of random sampling variability in relation to the PDF 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 PDF and the histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The logistic distribution with location $= \mu$ and scale $= \sigma$ has distribution function

$F(x) = \frac{1}{1 + e^{-(x - \mu) / \sigma}}$

and density

$f(x) = \frac{1}{\sigma} \frac{e^{(x-\mu)/\sigma}} {(1 + e^{(x-\mu)/\sigma})^2}$

It is a long-tailed distribution with mean $\mu$ and variance $\pi^2 / 3 \sigma^2$.

The algorithm for generating random variates from the logistic 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated logistic random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qlogis 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 PDF and cdf are displayed according to plotting parameter values (defaulting to display of both the PDF 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, showPDF, 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 the Unix 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, showPDF, 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PDF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Logistic random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rlogis

stats::runif, simEd::vunif

Examples

ilogis(0.5, location = 5, scale = 0.5)

 set.seed(8675309)
 ilogis(runif(10), 5, 1.5, showPDF = TRUE)

 set.seed(8675309)
 ilogis(runif(10), 5, 1.5, showECDF = TRUE)

 set.seed(8675309)
 ilogis(runif(10), 5, 1.5, showPDF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 ilogis(runif(10), 5, 1.5, showPDF = TRUE, showCDF = FALSE)

 ilogis(runif(100), 5, 1.5, showPDF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PDF and CDF without any variates
 ilogis(NULL, 5, 1.5, showPDF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PDF using show
 ilogis(runif(10), 5, 1.5, show = c(1,1,0))
 ilogis(runif(10), 5, 1.5, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 ilogis(vunif(10), 5, 1.5, show = c(1,0,1))
 ilogis(vunif(10), 5, 1.5, show = 5)

 # plot CDF with inversion, PDF, and ECDF using show
 ilogis(vunif(10), 5, 1.5, show = c(1,1,1))
 ilogis(vunif(10), 5, 1.5, show = 7)

 # plot three different CDF+PDF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 ilogis(runif(20), 5, 1.5, show = 7, respectLayout = TRUE, restorePar = FALSE)
 ilogis(runif(20), 5, 1.5, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 ilogis(runif(20), 5, 1.5, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 ilogis(runif(10), 5, 1.5, show = 7, plotDelay = 0.1)

 # display animation of CDF and PDF components only
 ilogis(runif(10), 5, 1.5, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   ilogis(runif(10), 5, 1.5, show = 7, plotDelay = -1)
 }

Description

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

Usage

inbinom(
  u = runif(1),
  size,
  prob,
  mu,
  minPlotQuantile = 0,
  maxPlotQuantile = 0.95,
  plot = TRUE,
  showCDF = TRUE,
  showPMF = TRUE,
  showECDF = TRUE,
  show = NULL,
  maxInvPlotted = 50,
  plotDelay = 0,
  sampleColor = "red3",
  populationColor = "grey",
  showTitle = TRUE,
  respectLayout = FALSE,
  restorePar = TRUE,
  ...
)

Arguments

Details

Generates random variates from the Negative 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 histogram 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 by default, which can be changed by specifying sampleColor. All aspects of the population distribution are output in gray by default, which can be changed by specifying populationColor.

The negative binomial distribution with size $= n$ and prob $= p$ has density

      \deqn{p(x) = \frac{\Gamma(x+n)}{\Gamma(n) \ x!} p^n (1-p)^x}{
                p(x) = Gamma(x+n)/(Gamma(n) x!) p^n (1-p)^x}

for $x = 0, 1, 2, \ldots, n > 0$ and $0 < p \leq 1$. This represents the number of failures which occur in a sequence of Bernoulli trials before a target number of successes is reached.

The mean is $\mu = n(1 - p)/p$ and variance $n(1 - p)/p^2$

The algorithm for generating random variates from the negative 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 colored dots. A horizontal, dashed, colored line extends from the dot to the population cdf. At the intersection, a vertical, dashed colored line extends downward to the horizontal axis, where a second colored dot, denoting the associated negative binomial random variate is plotted.

This is not a particularly fast variate generation algorithm because it uses the base R qnbinom 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 the Unix 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. The most recent plot with this attribute can be further annotated after the call.

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 their prior state 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.

plotDelay can be used to slow down or halt the variate generation for classroom explanation.

In the plot associated with the PMF, the maximum plotting height is associated with 125\ that extends above this limit will have three dots appearing above it.

Value

A vector of Negative Binomial random variates

Author(s)

Barry Lawson ([email protected]),
Larry Leemis ([email protected]),
Vadim Kudlay ([email protected])

See Also

stats::rnbinom

stats::runif, simEd::vunif

Examples

inbinom(0.5, size = 10, mu = 10)

 set.seed(8675309)
 inbinom(runif(10), 10, 0.25, showPMF = TRUE)

 set.seed(8675309)
 inbinom(runif(10), 10, 0.25, showECDF = TRUE)

 set.seed(8675309)
 inbinom(runif(10), 10, 0.25, showPMF = TRUE, showECDF = TRUE, sampleColor = "blue3")

 set.seed(8675309)
 inbinom(runif(10), 10, 0.25, showPMF = TRUE, showCDF = FALSE)

 inbinom(runif(100), 10, 0.25, showPMF = TRUE, minPlotQuantile = 0.02, maxPlotQuantile = 0.98)

 # plot the PMF and CDF without any variates
 inbinom(NULL, 10, 0.25, showPMF = TRUE, showCDF = TRUE)

 # plot CDF with inversion and PMF using show
 inbinom(runif(10), 10, 0.25, show = c(1,1,0))
 inbinom(runif(10), 10, 0.25, show = 6)

 # plot CDF with inversion and ECDF using show, using vunif
 inbinom(vunif(10), 10, 0.25, show = c(1,0,1))
 inbinom(vunif(10), 10, 0.25, show = 5)

 # plot CDF with inversion, PMF, and ECDF using show
 inbinom(vunif(10), 10, 0.25, show = c(1,1,1))
 inbinom(vunif(10), 10, 0.25, show = 7)

 # plot three different CDF+PMF+ECDF horizontal displays,
 # with title only on the first display
 oldpar <- par(no.readonly = TRUE)
 par(mfrow = c(3,3))  # 3 rows, 3 cols, filling rows before columns
 set.seed(8675309)
 inbinom(runif(20), 10, 0.25, show = 7, respectLayout = TRUE, restorePar = FALSE)
 inbinom(runif(20), 10, 0.25, show = 7, respectLayout = TRUE, restorePar = FALSE, showTitle = FALSE)
 inbinom(runif(20), 10, 0.25, show = 7, respectLayout = TRUE, restorePar = TRUE,  showTitle = FALSE)
 par(oldpar)

 # display animation of all components
 inbinom(runif(10), 10, 0.25, show = 7, plotDelay = 0.1)

 # display animation of CDF and PMF components only
 inbinom(runif(10), 10, 0.25, show = 5, plotDelay = 0.1)

 if (interactive()) {
   # interactive -- pause at each stage of inversion
   inbinom(runif(10), 10, 0.25, show = 7, plotDelay = -1)
 }