# stats::finiteRandom

Generate a random generator for elements of a finite sample space

### Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

## Syntax

```stats::finiteRandom(`[x1, x2, …], [p1, p2, …]`, <`Seed = n`>)
stats::finiteRandom(`[[x1, p1], [x2, p2], …]`, <`Seed = n`>)
stats::finiteRandom(`n`, <`c1, c2`>, <`Seed = n`>)
stats::finiteRandom(`n`, <`[c1, c2]`>, <`Seed = n`>)
```

## Description

```stats::finiteRandom([x1, x2, …, xn], [p1, p2, …, pn])``` returns a procedure that picks out random elements from the data ```x1, x2``` etc. The chances of picking out elements are given by the probabilities ```p1, p2``` etc.

The procedure ```f := stats::finiteRandom([x1, x2, …], [p1, p2, …])``` can be called in the form `f()`. The call `f()` returns one of the data elements ```x1, x2, …```.

The values `X = f()` are distributed randomly according to the discrete distribution function of the sample space, i.e., the probability of Xx is given by ```stats::finiteCDF([x1, x2, …], [p1, p2, …])(x)```.

All probability values ```p1, p2, …``` must be convertible to floating-point numbers. They must add up to 1.

Without the option `Seed` = `n`, 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:   In contrast to the function `random`, the generators produced by `stats::finiteRandom` do not react to the environment variable `SEED`.

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

```f := stats::finiteRandom([x1, x2, …], [p1, p2, …])```:

`f() \$k = 1..K;`

rather than by

```stats::finiteRandom([x_1, x_2, dots], [p_1, p_2, dots])() \$k = 1..K;```

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

```stats::finiteRandom([x_1, x_2, dots], [p_1, p_2, dots], 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.

`stats::finiteRandom` generalizes `stats::empiricalRandom`, which assumes equiprobable data. For numerical data ```x1, x2, …```, the call ```stats::finiteRandom([x_1, dots, x_n], [1/n, dots, 1/n])``` corresponds to ```stats::empiricalRandom([x1, …, xn])```.

## Examples

### Example 1

We pick out random elements of some data:

```f := stats::finiteRandom([1, x, y, PI], [1/4, 3/8, 1/4, 1/8], Seed = 234): f(), f(), f(), f(), f(), f(), f(), f(), f()```

Alternatively, the data may be passed as a list:

```f := stats::finiteRandom([[1, 1/4], [x, 3/8], [y, 1/4], [PI, 1/8]], Seed = 234): f(), f(), f(), f(), f(), f(), f(), f(), f()```

`delete f:`

### Example 2

We create a sample of type `stats::sample` consisting of one string column and two non-string columns:

```s := stats::sample( [["1996", 1242, 2/5], ["1997", 1353, 0.1], ["1998", 1142, 0.2], ["1999", 1201, 0.2], ["2001", 1201, 0.1]])```
```"1996" 1242 2/5 "1997" 1353 0.1 "1998" 1142 0.2 "1999" 1201 0.2 "2001" 1201 0.1 ```

We pick random values using the data in the first and third column:

```f := stats::finiteRandom(s, 1, 3, Seed = 123): f(), f(), f(), f(), f(), f(), f()```

`delete s, f:`

### Example 3

We toss a loaded coin:

```f:= stats::finiteRandom([Head, Tail], [0.4, 0.6], Seed = 123): f(), f(), f(), f(), f(), f(), f(), f(), f(), f()```

We toss the coin 10000 times and count the number of Heads and Tails:

```t := [f() \$ k = 1..10^4]: NumberOfHeads = nops(select(t, _equal, Head)), NumberOfTails = nops(select(t, _equal, Tail))```

`delete f, t:`

### Example 4

The probability values must add up to 1:

`stats::finiteRandom([Head, TAIL], [0.45, 0.54]):`
```Error: The probabilities do not add up to one. [stats::finiteRandom] ```

## Parameters

 `x1, x2, …` The statistical data: arbitrary MuPAD objects `p1, p2, …` Probability values: real numerical values `s` A sample of domain type `stats::sample` `c1, c2` Column indices of the sample `s`: positive integers. Column c1 provides the data `x1`, `x2` etc. Column c2 provides the data `p1`, `p2` etc. There is no need to specify column numbers if the sample has only two columns.

## Options

 `Seed` Option, specified as `Seed = n` Initializes the random generator with the integer seed `n`. `n` 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 values. The generator is initialized with the seed `n` which may be an arbitrary integer. Several generators with the same initial seed produce the same sequence of values.

## Algorithms

The random values are chosen by applying the quantile function to uniformly distributed random numbers between 0 and 1.