Difference between revisions of "Random"

(added exponential, geometric and hypergeometric to list supported by random)
m
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
= Function Random =
+
[[Category:Distribution Functions]]
 +
[[Category:Doc Status C]] <!-- For Lumina use, do not change -->
 +
 +
__TOC__
  
−
The Random function generates a single random variate.
+
==Random(''dist, method, over'')==
  
−
Random( ), with no parameters, returns a single uniformly-distributed random number between 0 and 1, even if it is evaluated in Mid-mode.
+
Function [[Random]] generates a single random value from a probability distribution. It is not a probability distribution ''per se'', such as [[Normal]]() or [[Uniform]](). It generates a single value, not a sample indexed by [[Run]], and it does so whether evaluated in a deterministic ([[Mid]]) or probabilistic context. For example.
 +
:<code>Random(Normal(10, 2))</code>
  
−
== Declaration ==
+
generates a single value generated at random from the specified [[Normal]] distribution. [[Random]]() with no parameters returns a single uniformly-distributed random number between 0 and 1.
  
−
  Random(dist:optional unevaluated ; method:optional scalar; Over:...optional atomic)
+
Because there is often a need to access a random number generator stream, such as for rejection sampling, Metropolis-Hastings simulation, etc, [[Random]]() makes it possible to get such values, even if the global sampling method is Latin hypercube, and efficiently since it isn't necessary to generate an entire sample. [[Random]] can return variates from a wide variety of distributions. It is even possible to write user-defined distribution functions for custom distributions that work with random.
  
−
Parameters:
+
The full declaration of  the function is
−
* dist : If specified, must be an explicit call to a distribution function that supports single-sample generation (see below).  Defaults to Uniform(0,1).
+
:[[Random]](''dist'': Optional Unevaluated; ''method'': Optional Scalar; ''over'': ... Optional Index)
−
* Method : Selects the algorithm used to generate the random number.  Possible value are: 0=use system default, 1=Minimal standard, 2=L'Ecuyer, 3=Knuth.
 
−
* Over: A convenient way to list indexes that independent random numbers will be generated over. (This will also occur if the index(es) occur in any of the other parameters).
 
  
−
== Description ==
+
==Optional parameters==
 +
===Dist===
 +
If specified, «dist» must be a call to a distribution function that supports single-sample generation (most do, but see below).  If you specify no distribution, it defaults to [[Uniform]](0,1). If «dist» is a multivariate distribution, indexed by <code>I</code>, it returns an array of random samples indexed by <code>I</code>.
  
−
Random is not a distribution-function per-se, as Uniform(0,1) is.  However, one often needs access to a random number generator stream, such as for rejection sampling, Metropolis-Hastings simulation, etc.  Random() makes it possible to get such values, even if the global sampling method is latin hypercube, and efficiently since it isn't necessary to generate an entire sample.  Random can return variates from a wide variety of distributions.  It is even possible to write user-defined distribution functions for custom distributions that work with random.
+
===Method===
 +
Selects the algorithm used to generate the random number.  Possible value are:
 +
:<code>0</code>: use system default
 +
:<code>1</code>: Minimal standard
 +
:<code>2</code>: L'Ecuyer
 +
:<code>3</code>: Knuth
  
−
== Examples ==
+
===Over===
  
−
Random(Uniform(-100,100)): Returns a single real-valued random number uniformly selected between -100 and 100.
+
Give it an index or list of indexes. Random will choose an independent random number for each index value, or combination of index values. It also does this if any of the other parameters is an array with one or more indexes.
  
−
  Random(Uniform(1,100,integer:true)): Returns a random integer between 1 and 100 inclusive.
+
== Examples ==
 +
:<code>Random(Uniform(-100, 100))</code>  
 +
::Returns a single real-valued random number uniformly selected between -100 and 100.
 +
:<code>Random(Uniform(1, 100, integer: True))</code>
 +
::Returns a random integer between 1 and 100 inclusive.
 +
:<code>Random(Over: I)</code>
 +
::Returns an array of independent uniform random numbers between 0 and 1 indexed by <code>I</code>.  The numbers are independent (i.e., Monte Carlo sampled, never Latin Hypercube).
 +
:<code>Random(Over: I, J)</code>
 +
::Returns a 2-D array of independent uniform random numbers between 0 and 1, indexed by <code>I</code> and <code>J</code>.  All numbers in the array are sampled independently.
 +
:<code>Random(Uniform(min: Array(I, J, 0), max: 1))</code>
 +
::This is functionally equivalent to the preceding example. It demonstrates how the «over» parameter is only a convenience, but results in an easier to interpret syntax.
  
−
Random(Normal(0,1)) : Returns a single number from a standard normal distribution.
+
==Details and more examples==
 +
=== Distribution function support for single samples ===
 +
Random supports only those distribution functions with parameter «singleMethod», usually declared as:
 +
:<code>singleSampleMethod: Optional Atomic Numeric</code>
  
−
  Random(Over:I): Returns an array of independent uniform random numbers between 0 and 1 indexed by I.  The numbers are independent (i.e., Monte Carlo sampled, never Latin Hypercube).
+
When the parameter is provided, the distribution function must return a single random variate from the distribution indicated by the other parameters. Random will fill in this parameter with one of the following values, indicating which sampling method should be used:
−
 
+
Possible values for «singleMethod»:
−
Random(Over:I,J): Returns a 2-D array of independent uniform random numbers between 0 and 1, indexed by I and J.  All numbers in the array are sampled independently.
+
:<code>0</code>: use default method
 +
:<code>1</code>: use Minimal standard
 +
:<code>2</code>: use L'Ecuyer
 +
:<code>3</code>: use Knuth
  
−
Random(Uniform(min:Array(I,J,0),max:1)): This is functionally equivalent to the preceeding example. It demonstrates how the Over parameter is only a convenience, but results in an easier to interpret syntax.
+
As an example, consider what happens when <code>Random(Normal(2, 3))</code> is evaluated. The [[Random]] function checks that its parameter is an acceptable distribution function, and then it evaluates:
 +
:<code>Normal(2, 3, singleSampleMethod: 0)</code>
  
−
=== Distribution Function Support for Single Samples ===
+
User-defined functions can support single-variate generation, and therefore can be used as a parameter to [[Random]], if they have a parameter named «singleMethod».
  
−
In order to support single sample generation, and thus be permitted as a parameter in Random, a distribution function must have a parameter named singleMethod, usually declared as:  
+
===Functions supported===
−
singleSampleMethod : optional atomic numeric
+
[[Random]](dist) supports any of these built-in probability distributions functions as the distribution:
−
 
+
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
−
When the parameter is provided, the distribution function must return a single random variate from the distribution indicated by the other parameters.  Random will fill in this parameter with one of the following values, indicating which sampling method should be used:
+
* [[Bernoulli]]
−
Possible values for singleMethod:
+
* [[Beta]]
−
0 = use default method
+
* [[Binomial]]
−
1 = use Minimal standard
+
* [[Certain]]
−
2 = use L'Ecuyer
+
* [[ChiSquared]]
−
3 = use Knuth
+
* [[CumDist]]
 +
* [[Exponential]]
 +
* [[Gamma]]
 +
* [[Geometric]]
 +
* [[HyperGeometric]]
 +
* [[Logistic]]
 +
* [[LogNormal]]
 +
* [[Normal]]
 +
* [[Poisson]]
 +
* [[StudentT]]
 +
* [[Triangular]]
 +
* [[Uniform]]
 +
* [[Weibull]]
 +
</div>
  
−
As an example, consider what happens when Random(Normal(2,3)) is evaluated.  The Random function checks that its parameter is an acceptable distribution function, and then it evaluates:
+
It also works for these distributions from the ''Distribution variations'' library:
−
  Normal(2,3,singleSampleMethod:0)
+
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
−
The Normal function then returns a single random variate from Normal(2,3).
+
* [[Beta_m_sd]]
 +
* [[Erlang]]
 +
* [[Gamma_m_sd]]
 +
* [[InverseGaussian]]
 +
* [[Lognormal_m_sd]] (but note that this one is superseded by [[LogNormal]])
 +
* [[Lorenzian]]
 +
* [[NegBinomial]]
 +
* [[Pareto]]
 +
* [[Pert]]
 +
* [[Rayleigh]]
 +
* [[Smooth_Fractile]]
 +
* [[Wald]]
 +
</div>
  
−
Only some built-in functions currently support single variate generation.  These include:
+
It also works for these distributions from the ''Multivariate Distributions'' library:
−
* Bernoulli
+
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
−
* Beta
+
* [[BiNormal]]
−
* Binomial
+
* [[Dirichlet]]
−
* ChiSquared
+
* [[Dist_additive_growth]]
−
* Exponential
+
* [[Dist_compound_growth]]
−
* Gamma
+
* [[Dist_serial_correl]]
−
* Geometric
+
* [[Gaussian]]
−
* Hypergeometric
+
* [[Multinomial]]
−
* Logistic
+
* [[MultiNormal]]
−
* LogNormal
+
* [[MultiUniform]]
−
* Normal
+
* [[Normal_additive_gro]]
−
* Poisson
+
* [[Normal_compound_gro]]
−
* StudentT
+
* [[Normal_correl]]
−
* Triangular
+
* [[Normal_serial_correl]]
−
* Uniform
+
* [[UniformSpherical]]
−
* Weibull
+
</div>
  
−
In addition, the following distributions in the ''Distribution variations'' library can be used in Random (the Distribution Variations library must be added to your model):
+
===Functions not supported===
−
* LogNormal_m_sd (but note that this one is superceded by LogNormal)
+
[[Random]] does not support these built-in distribution functions:
−
* Pert
+
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
−
* Gamma_m_sd
+
* [[ChanceDist]]
−
* Beta_m_sd
+
* [[Fractiles]]
−
* Erlang
+
* [[ProbDist]]
−
* Pareto
+
* [[Truncate]]
−
* Rayleigh
+
</div>
−
* Lorenzian
 
−
* NegBinomial
 
−
* InverseGaussian
 
−
* Wald
 
  
−
User-defined functions can support single-variate generation, and therefore can be used as a parameter to Random, if they have a parameter named singleMethod.
+
== See Also ==
 +
* [[RandomType]]
 +
* [[Shuffle]]
 +
* [[Sample]]
 +
* [[Distribution Functions]]
 +
* [[Distribution Densities Library]]

Latest revision as of 20:01, 13 April 2016


Random(dist, method, over)

Function Random generates a single random value from a probability distribution. It is not a probability distribution per se, such as Normal() or Uniform(). It generates a single value, not a sample indexed by Run, and it does so whether evaluated in a deterministic (Mid) or probabilistic context. For example.

Random(Normal(10, 2))

generates a single value generated at random from the specified Normal distribution. Random() with no parameters returns a single uniformly-distributed random number between 0 and 1.

Because there is often a need to access a random number generator stream, such as for rejection sampling, Metropolis-Hastings simulation, etc, Random() makes it possible to get such values, even if the global sampling method is Latin hypercube, and efficiently since it isn't necessary to generate an entire sample. Random can return variates from a wide variety of distributions. It is even possible to write user-defined distribution functions for custom distributions that work with random.

The full declaration of the function is

Random(dist: Optional Unevaluated; method: Optional Scalar; over: ... Optional Index)

Optional parameters

Dist

If specified, «dist» must be a call to a distribution function that supports single-sample generation (most do, but see below). If you specify no distribution, it defaults to Uniform(0,1). If «dist» is a multivariate distribution, indexed by I, it returns an array of random samples indexed by I.

Method

Selects the algorithm used to generate the random number. Possible value are:

0: use system default
1: Minimal standard
2: L'Ecuyer
3: Knuth

Over

Give it an index or list of indexes. Random will choose an independent random number for each index value, or combination of index values. It also does this if any of the other parameters is an array with one or more indexes.

Examples

Random(Uniform(-100, 100))
Returns a single real-valued random number uniformly selected between -100 and 100.
Random(Uniform(1, 100, integer: True))
Returns a random integer between 1 and 100 inclusive.
Random(Over: I)
Returns an array of independent uniform random numbers between 0 and 1 indexed by I. The numbers are independent (i.e., Monte Carlo sampled, never Latin Hypercube).
Random(Over: I, J)
Returns a 2-D array of independent uniform random numbers between 0 and 1, indexed by I and J. All numbers in the array are sampled independently.
Random(Uniform(min: Array(I, J, 0), max: 1))
This is functionally equivalent to the preceding example. It demonstrates how the «over» parameter is only a convenience, but results in an easier to interpret syntax.

Details and more examples

Distribution function support for single samples

Random supports only those distribution functions with parameter «singleMethod», usually declared as:

singleSampleMethod: Optional Atomic Numeric

When the parameter is provided, the distribution function must return a single random variate from the distribution indicated by the other parameters. Random will fill in this parameter with one of the following values, indicating which sampling method should be used: Possible values for «singleMethod»:

0: use default method
1: use Minimal standard
2: use L'Ecuyer
3: use Knuth

As an example, consider what happens when Random(Normal(2, 3)) is evaluated. The Random function checks that its parameter is an acceptable distribution function, and then it evaluates:

Normal(2, 3, singleSampleMethod: 0)

User-defined functions can support single-variate generation, and therefore can be used as a parameter to Random, if they have a parameter named «singleMethod».

Functions supported

Random(dist) supports any of these built-in probability distributions functions as the distribution:

It also works for these distributions from the Distribution variations library:

It also works for these distributions from the Multivariate Distributions library:

Functions not supported

Random does not support these built-in distribution functions:

See Also

Comments


You are not allowed to post comments.