Accelerating the pace of engineering and science

# stats::hypergeometricRandom

Generate a random number generator for hypergeometric deviates

### Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

## Syntax

```stats::hypergeometricRandom(N, X, n, <Seed = s>)
```

## Description

stats::hypergeometricRandom(N, X, n) returns a procedure that produces hypergeometric-deviates (random numbers) with population size N, success population size X and sample size n.

The procedure f:=stats::hypergeometricRandom(N, X, n) can be called in the form f().

The return value of f(x) is either an integer between max(0, X + n - N) and min(X, n) or a symbolic expression:

If N is a positive integer and both X and n are nonnegative integers, then an explicit numerical value is returned.

If any of the parameters is symbolic, then in some cases numerical or symbolic result will be returned:

0 will be returned if either n or X is zero, n will be returned if N = X and X will be returned if N = n.

The symbolic call stats::hypergeometricRandom(N, X, n)() is returned in all other cases.

Numerical values for N are only accepted if they are positive integers.

Numerical values for X and n are only accepted if they are integers that satisfy 0 ≤ X, nN.

The values R = f() are distributed randomly according to the hypergeometric distribution with poupulation size N, success population size X and sample size n.

For any max(0, X + n - N) ≤ xmin(X, n), the probability of Rx is given by

.

Without the option Seed = s, an initial seed is chosen internally. This initial seed is set to a default value when MuPAD® is started. Thus, each time MuPAD is started or re-initialized with the reset function, random generators produce the same sequences of numbers.

 Note:   With this option, the parameters N, X and n must evaluate to suitable numerical values at the time, when the generator is created.
 Note:   In contrast to the function random, the generators produced by stats::hypergeometricRandom do not react to the environment variable SEED.

For efficiency, it is recommended to produce sequences of K random numbers via

f := stats::hypergeometricRandom(N, X, n): f() \$k = 1..K;

rather than by

stats::hypergeometricRandom(N, X, n)() \$k = 1..K;

The latter call produces a sequence of generators each of which is called once. Also note that

stats::hypergeometricRandom(N, X, n, Seed = s)() \$k = 1..K;

does not produce a random sequence, because a sequence of freshly initialized generators would be created each of them producing the same number.

## Environment Interactions

The function is sensitive to the environment variable DIGITS which determines the numerical working precision.

## Examples

### Example 1

We generate hypergeometric deviates with parameters N = 100, X = 30, and n = 7:

`f := stats::hypergeometricRandom(100, 30, 7): f() \$ k = 1..10`

`delete f:`

### Example 2

With symbolic parameters, no random numbers can be produced:

`f := stats::hypergeometricRandom(N, X, n): f()`

When N, X and n evaluate to suitable numbers, the generator starts to produce random numbers:

`N := 200: X := 80: n := 20: f() \$ k= 1..10`

`delete f, N, X, n:`

### Example 3

We use the option Seed = s to reproduce a sequence of random numbers:

```f := stats::hypergeometricRandom(500, 100, 50, Seed = 1):
f() \$ k = 1..10```

```g := stats::hypergeometricRandom(500, 100, 50, Seed = 1):
g() \$ k = 1..10```

`f() = g(), f() = g()`

`delete f, g:`

## Parameters

 N The "population size": an arithmetical expression representing a positive integer X The "success population size": an arithmetical expression representing a nonnegative integer n The "sample size": an arithmetical expression representing a nonnegative integer

## Options

 Seed Option, specified as Seed = s Initializes the random generator with the integer seed s. s can also be the option CurrentTime, to make the seed depend on the current time. This option serves for generating generators that return predictable sequences of pseudo-random numbers. The generator is initialized with the seed s which may be an arbitrary integer. Several generators with the same initial seed produce the same sequence of numbers. When this option is used, the parameters N, X and n must be numerical values at the time when the random generator is generated.