<sampleRandomNumbers/>
<sampleRandomNumbers/> is a Math
component that generates random numbers from a specified range of values, from a normal distribution
around a specified mean, 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
Attributes for <sampleRandomNumbers>
Other (21)
asListboolean. Default value: true. Whether to render the items separated by commas (true) or with no separator (false).
avoidScientificNotationWhether to render numbers in full decimal form rather than scientific notation.
displayDecimalsNumber of decimal places to display when rendering this number.
displayDigitsNumber of significant digits to display when rendering this number.
displaySmallAsZeroThreshold below which numbers are displayed as zero.
numberList. Values to exclude from the sample space.
number. Lower bound of the sampling range.
meannumber. Mean of the sampling distribution (Gaussian or Poisson). Defaults to 0 for Gaussian and 1 for Poisson.
numDrawsnumber. Number of items drawn without replacement to form each sample (hypergeometric).
number. Default value: 1. Number of samples to draw.
numSuccessesnumber. Number of successes in the population drawn from (hypergeometric).
numTotalnumber. Size of the population drawn from (hypergeometric).
numTrialsnumber. Default value: 1. Number of independent trials making up each sample (binomial).
padZerosWhether to pad displayed numbers with trailing zeros to fill the requested digits/decimals.
probabilitynumber. Default value: 0.5. Probability that each trial succeeds (binomial).
standardDeviationnumber. Default value: 1. Standard deviation of the sampling distribution (Gaussian).
number. Default value: 1. Step size between samples for the discrete-uniform distribution.
number. Upper bound of the sampling range.
typekeyword. Distribution from which to sample.
| Value | Description |
|---|---|
uniform (default) | Continuous uniform distribution over [from, to]. |
discreteUniform | Discrete uniform distribution over integers in [from, to]. |
gaussian | Normal (Gaussian) distribution with the specified mean and standard deviation. |
hypergeometric | Number of successes when drawing numDraws items without replacement from a population of numTotal items containing numSuccesses successes. |
binomial | Number of successes in numTrials independent trials that each succeed with the given probability. |
poisson | Poisson distribution with the specified mean (which defaults to 1). |
variancenumber. Default value: 1. Variance of the sampling distribution (Gaussian).
variantDeterminesSeedboolean. Whether the document's variant index determines the random seed.
Common to all components (9)
copyreference. Create an independent copy of another component by reference. Enter a references a $name.
disabledboolean. Default value: false. Whether this component is disabled and cannot be interacted with.
extendreference. Extend another component by reference, inheriting its children and attributes. Enter a reference as $name.
fixedboolean. Default value: false. Whether this component's value is fixed and cannot be modified.
fixLocationboolean. Default value: false. Whether this component's location is fixed (preventing it from being moved while still allowing other modifications).
hideboolean. Default value: false. Whether to hide this component from the rendered output.
isResponseboolean. Default value: false. Whether this component is treated as a response for the purposes of assessment.
nametext. The name used to reference this component from elsewhere in the document.
styleNumberinteger. Default value: 1. The style number used to select this component's visual styling from the available style definitions.
Properties for <sampleRandomNumbers name="s">
Other (14)
$s.fromnumber. Lower bound of the sampling range.
$s.meannumber. Mean of the sampling distribution.
$s.numDrawsnumber. Number of items drawn without replacement to form each sample (hypergeometric).
$s.numSamplesnumber. Number of samples to draw.
$s.numSuccessesnumber. Number of successes in the population drawn from (hypergeometric).
$s.numTotalnumber. Size of the population drawn from (hypergeometric).
$s.numTrialsnumber. Number of independent trials making up each sample (binomial).
$s.probabilitynumber. Probability that each trial succeeds (binomial).
$s.standardDeviationnumber. Standard deviation of the sampling distribution.
$s.stepnumber. Step size between sample values (for discrete distributions).
$s.tonumber. Upper bound of the sampling range.
$s.typetext. Distribution from which to sample.
$s.variancenumber. Variance of the sampling distribution.
$s.variantDeterminesSeedboolean. Whether the document's variant index determines the random seed.
Common to all components (4)
$s.doenetMLtext. The DoenetML source code that produced this component.
$s.hideboolean. Whether to hide this component from the rendered output.
$s.isResponseboolean. Whether this component is treated as a response for the purposes of assessment.
$s.styleNumberinteger. The style number used to select this component's visual styling from the available style definitions.
Examples
Example: Default <sampleRandomNumbers/>
Without any attributes specified, the default sampling type is uniform, and the
default interval is . 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 . The <callAction> button can be used to
resample the value.
Attribute Examples
Attribute Example: numSamples
The <sampleRandomNumbers/> component is used with the numSamples attribute to
select multiple random values in the default interval . The default type is uniform.
Attribute Example: from, to
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”
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
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
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”
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
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
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 = “hypergeometric”
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 and , where
is numTotal, is numSuccesses, and is numDraws.
Unlike the other distributions, hypergeometric has no defaults 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”
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”
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.