<sampleRandomNumbers/>

<sampleRandomNumbers/> is a Math component that generates random numbers from a specified range of values, from a normal, log-normal, or mixture-of-normals distribution, or from one of the discrete count distributions (hypergeometric, binomial, and Poisson). It differs from the <selectRandomNumbers/> component in that the values can be altered within the document by resampling or changing one or more of the component’s attributes. The primary application of the <sampleRandomNumbers/> component is for use in simulations involving random numbers.

Attributes and Properties

Examples

Example: Default <sampleRandomNumbers/>

Without any attributes specified, the default sampling type is uniform, and the default interval is $[0, 1)$. In this example, there are two ways to view different samples: selecting another variant, or refreshing the page.

Example: Using a re-sampling button

Without any attributes specified, the default sampling type is uniform, and the default interval is $[0, 1)$. The <callAction> button can be used to resample the value.

Attribute Examples

Attribute Example: numSamples

<p>
  <sampleRandomNumbers numSamples="4" name="randomNumbers"/>
</p>
 
<callAction actionName="resample" target="$randomNumbers" >
  <label>Get New Numbers</label>
</callAction>
 
<p>The second number selected 
  <c>randomNumbers[2]</c> = $randomNumbers[2]
</p>

The <sampleRandomNumbers/> component is used with the numSamples attribute to select multiple random values in the default interval $[0,1)$. The default type is uniform.

Attribute Example: from, to

<p>
  <sampleRandomNumbers 
    name="x" 
    from="-5" 
    to="5" 
    numSamples="5" 
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>The second number selected 
  <c>x[2]</c> = $x[2]
</p>

The <sampleRandomNumbers/> component is used with the from and the to attributes to modify the default selection interval. The default type is uniform.

Attribute Example: type = “discreteUniform”

<p>
  <sampleRandomNumbers 
    name="x" 
    type="discreteUniform" 
    from="0" 
    to="10" 
    numSamples="5"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>The second number selected 
  <c>x[2]</c> = $x[2]
</p>

The type attribute of the <sampleRandomNumbers/> component is specified as discreteUniform. The discreteUniform selection generates values from an evenly spaced range defined by the attributes to, from, and step. If left unspecified, the default step is 1.

Attribute Example: exclude

<setup>
<sampleRandomNumbers 
  name="n" 
  type="discreteUniform" 
  from="-4" to="4" 
  numSamples="3" 
  exclude="0"
/>
<number name="a" extend="$n[1]"/>
<number name="b" extend="$n[2]"/>
<number name="c" extend="$n[3]"/>
</setup>
 
<p>
  <math simplify="numberspreserveorder">
    $a x^2 + $b x + $c
  </math>
</p>
 
<callAction actionName="resample" target="$n">
  <label>New Coefficients</label>
</callAction>

The type attribute of the <sampleRandomNumbers/> component is specified as discreteUniform. Values can be excluded from the specified range used with this type using the exclude attribute.

Attribute Example: step

<p>
  <sampleRandomNumbers 
    name="x" 
    type="discreteUniform" 
    from="0" 
    to="20" 
    numSamples="5" 
    step="2"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>The second number selected 
  <c>x[2]</c> = $x[2]
</p>

The type attribute of the <sampleRandomNumbers/> component is specified as discreteUniform. The discreteUniform selection generates values from an evenly spaced range defined by the attributes to, from, and step. If left unspecified, the default step is 1.

Attribute Example: type = “gaussian”

<p>
  <sampleRandomNumbers 
    name="x" 
    type="gaussian" 
    numSamples="10" 
    displayDigits="4"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>The second number selected 
  <c>x[2]</c> = $x[2]
</p>

The type attribute of the <sampleRandomNumbers/> component is specified as gaussian. The gaussian selection generates standard normal variables (mean 0, variance 1). Alternatively, the mean as well as the variance or the standardDeviation attributes may be defined.

Attribute Example: gaussian with mean and variance

<p>With <attr>mean</attr> and <attr>variance</attr> attribute:
  <sampleRandomNumbers 
    name="x" 
    type="gaussian" 
    mean="10" 
    variance="2" 
    numSamples="10" 
    displayDigits="4"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>The second number selected 
  <c>x[2]</c> = $x[2]
</p>

The type attribute of the <sampleRandomNumbers/> component is specified as gaussian. The gaussian selection generates standard normal variables (mean 0, variance 1). In this example, the mean and the variance are defined with attributes.

Attribute Example: gaussian with mean and standardDeviation

<p>With <attr>mean</attr> and <attr>standardDeviation</attr> attribute:
  <sampleRandomNumbers 
    name="x" 
    type="gaussian" 
    mean="10" 
    standardDeviation="2" 
    numSamples="10" 
    displayDigits="4"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>The second number selected 
  <c>x[2]</c> = $x[2]
</p>

The type attribute of the <sampleRandomNumbers/> component is specified as gaussian. The gaussian selection generates standard normal variables (mean 0, variance 1). In this example, the mean and the standardDeviation are defined with attributes.

Attribute Example: type = “logNormal”

<p>Ten times taken to finish a task, averaging about half an hour:
  <sampleRandomNumbers 
    name="x" 
    type="logNormal" 
    logMean="3.3" 
    logStandardDeviation="0.5" 
    numSamples="10" 
    displayDigits="4"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>Mean of the distribution: $x.mean</p>

The logNormal type raises $e$ to the power of a normal variable, so every sample is positive and the distribution is skewed to the right — the usual shape for quantities such as incomes, particle sizes, or times to finish a task.

Its parameters describe the normal distribution being exponentiated, not the samples themselves, which is why they are named logMean and logStandardDeviation rather than mean and standardDeviation. Either logStandardDeviation or logVariance may be given, as with the gaussian type. If unspecified, logMean is 0 and logStandardDeviation is 1.

Writing $\mu$ for logMean and $\sigma$ for logStandardDeviation, the reported mean is $e^{\mu + \sigma^2/2}$ and the reported variance is $(e^{\sigma^2} - 1)\,e^{2\mu + \sigma^2}$. Both grow very fast with $\sigma$, so a large one reports Infinity for a distribution whose true moments are beyond what a number can hold, and samples past about $e^{709}$ come back as Infinity for the same reason. At the other end, a sample below about $e^{-745}$ rounds to 0, which is the only way a value can fail to be strictly positive.

Attribute Example: type = “normalMixture”

<p>Twenty exam scores from a class with two distinct groups:
  <sampleRandomNumbers 
    name="x" 
    type="normalMixture" 
    means="55 85" 
    standardDeviations="6 5" 
    weights="1 2" 
    numSamples="20" 
    displayDigits="3"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>Mean of the distribution: $x.mean</p>

The normalMixture type draws each value from one of several normal distributions: a component is chosen at random, and the value comes from that component alone. It is the usual way to describe a population made of distinct groups — two study sections, two species, a process that sometimes runs slowly — and the usual way to produce a bimodal sample, which no single gaussian can.

The components are described by three lists. means gives each component’s center, and how many are listed is how many components there are — it is the one of the three with no default. standardDeviations (or variances, as with the gaussian type) gives each component’s spread, and weights gives each component’s share of the values. Weights are relative and need not add up to 1: weights="1 2" above means a third of the values come from the first component and two thirds from the second. A list holding a single value applies to every component, which is how the defaults — a spread of 1, and equal weights — are written, so standardDeviations="2" beside three means gives all three components a spread of 2.

The reported mean is the weighted average of the component means. The reported variance is the weighted average of the component variances plus a second term for how far the components sit from one another. That second term is zero exactly when every component carrying weight shares one center — a component whose weights entry is 0 contributes to neither term — and is positive otherwise. Writing $p_i$, $\mu_i$ and $\sigma_i$ for the proportion, mean and standard deviation of each component, it is $\sum_i p_i \sigma_i^2 + \sum_i p_i (\mu_i - \mu)^2$, where $\mu$ is the reported mean.

Whether the values actually come out looking bimodal depends on the components. Two equally weighted components of equal spread are visibly two humps only once their centers are more than $2\sigma$ apart; closer together than that, the mixture has a single peak. The type is named for what it does rather than for that outcome, and the separation is worth exploring in its own right.

Attribute Example: type = “hypergeometric”

<p>An urn holds 20 marbles, 7 of which are red. 
  Draw 5 marbles without replacement and count the red ones, 
  repeated 10 times:
  <sampleRandomNumbers 
    name="x" 
    type="hypergeometric" 
    numTotal="20" 
    numSuccesses="7" 
    numDraws="5" 
    numSamples="10"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>Expected number of red marbles in each set of 5 draws: $x.mean</p>

The hypergeometric type counts the successes obtained when drawing numDraws items without replacement from a population of numTotal items containing numSuccesses successes. Because the draws within a single sample deplete the population, this is the without-replacement counterpart of the binomial type.

Each sample lies between $\max(0, n - (N - K))$ and $\min(n, K)$, where $N$ is numTotal, $K$ is numSuccesses, and $n$ is numDraws.

Unlike most of the distributions, hypergeometric has no defaults at all to fall back on. If any of the three attributes is omitted, or they do not describe a population (for example, more successes or more draws than there are items), every sample is NaN, as are the reported mean, variance, and standardDeviation.

Attribute Example: type = “binomial”

<p>Flip a biased coin 10 times and count the heads, repeated 10 times:
  <sampleRandomNumbers 
    name="x" 
    type="binomial" 
    numTrials="10" 
    probability="0.3" 
    numSamples="10"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>Expected number of heads per sample: $x.mean</p>

The binomial type counts the successes in numTrials independent trials that each succeed with the given probability. If unspecified, numTrials is 1 and probability is 0.5, so type="binomial" on its own produces a fair coin flip reported as 0 or 1.

Attribute Example: type = “poisson”

<p>Number of calls arriving each hour, averaging 4 per hour:
  <sampleRandomNumbers 
    name="x" 
    type="poisson" 
    mean="4" 
    numSamples="10"
  />
</p>
 
<callAction actionName="resample" target="$x">
  <label>Get New Numbers</label>
</callAction>
 
<p>Variance of the distribution: $x.variance</p>

The poisson type is determined entirely by its mean, which also equals its variance. Unlike the gaussian type, whose mean defaults to 0, the mean of a poisson distribution defaults to 1, since a Poisson distribution with mean 0 always returns 0.

Limits on the discrete distributions

The three discrete distributions — hypergeometric, binomial, and poisson — draw their samples one item, trial, or event at a time, so very large parameters would take a long time and leave the page unresponsive while they ran. Parameters that would need more than ten million draws for a single sample are therefore treated as unusable, giving NaN samples and statistics along with a warning explaining what to change. The limit is far above the populations, trial counts, and rates that arise in practice; it is there so that mistyping an extra digit reports a problem instead of freezing the activity. An order of magnitude below that, from a million draws per sample, the samples are still drawn as asked, but a warning notes that sampling may be slow. Note that both figures apply to each sample individually — a large numSamples still takes proportionally longer.