# sample_without_replacement()

Sample items from a list without replacement.

## Synopsis

```sample_without_replacement(list-expression, expression)
sample_without_replacement(list-expression, expression, weight-list-expression)
```

## Description

This action returns a list of values randomly sampled from the first argument without replacement (i.e. without placing the values selected back in the pool being sampled so that they can be retrieved a second time). The number of samples is specified by the second argument.

An optional, weight list can be specified in order to set a normalized probability for the correspdonding index in the sample pool list being drawn. For example, a weight list: `list(1, 0, 1)` will have a 50% chance that the element with index 0, will be selected, a 50% chance that the element with index 2 will be selected, and a 0% chance that the element with index 1 will be selected.

## Parameters

`list-expression`

An expression that evaluates to the list to sample from.

`expression`

An expression that evaluates to the number of samples to return

`weight-list-expression`

An expression that evaluates to the list of weights to be used in the sampling.

## Returns

The function returns a list. The returned list is empty if the first argument evaluates to an empty list and the second argument evaluates to 0.

## Errors

The function causes a run-time error if the number of samples exceeds the length of the list.

## Examples

Example of an un-weighted sampling:

```x_list = list(1, 2, 3, 4, 5, 6, 7)
sample_list = sample_without_replacement(x_list, 4)
# possible result: sample_list = list(5, 2, 7, 1)
```

Example of a weighted sampling:

```x_list = list(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)

weight_list = apply(x_list, pow(_, 2))
# weight_list = list(1, 4, 9, 16, 25, 36, 49, 64, 81, 100)

sample_list = sample_without_replacement(x_list, 4, weight_list)
# possible result: sample_list = list(10, 9, 7, 5)
```

To sample the same positions in two or more lists, first sample from the list of indexes, and then select the indexes from the lists, as follows:

```x_list = list(10, 11, 12, 13, 14, 15)
y_list = list(20, 21, 22, 23, 24, 25)

sample_index_list = sample_without_replacement(range(6), 3)
# possible result: sample_index_list = list(2, 4, 0)

sample_from_x_list = select(x_list, sample_index_list)
# sample_from_x_list = list(12, 14, 10)

sample_from_y_list = select(y_list, sample_index_list)
# sample_from_y_list = list(22, 24, 20)
```

## Note

Each call to the function returns a distinct random sample.