Chooses k unique random elements from a population sequence. Returns a new list containing elements from the population while leaving the original population unchanged. The resulting list is in selection order so that all sub-slices will also be valid random samples
(self, population, k, *, counts=None)
| 363 | x[i], x[j] = x[j], x[i] |
| 364 | |
| 365 | def sample(self, population, k, *, counts=None): |
| 366 | """Chooses k unique random elements from a population sequence. |
| 367 | |
| 368 | Returns a new list containing elements from the population while |
| 369 | leaving the original population unchanged. The resulting list is |
| 370 | in selection order so that all sub-slices will also be valid random |
| 371 | samples. This allows raffle winners (the sample) to be partitioned |
| 372 | into grand prize and second place winners (the subslices). |
| 373 | |
| 374 | Members of the population need not be hashable or unique. If the |
| 375 | population contains repeats, then each occurrence is a possible |
| 376 | selection in the sample. |
| 377 | |
| 378 | Repeated elements can be specified one at a time or with the optional |
| 379 | counts parameter. For example: |
| 380 | |
| 381 | sample(['red', 'blue'], counts=[4, 2], k=5) |
| 382 | |
| 383 | is equivalent to: |
| 384 | |
| 385 | sample(['red', 'red', 'red', 'red', 'blue', 'blue'], k=5) |
| 386 | |
| 387 | To choose a sample from a range of integers, use range() for the |
| 388 | population argument. This is especially fast and space efficient |
| 389 | for sampling from a large population: |
| 390 | |
| 391 | sample(range(10000000), 60) |
| 392 | |
| 393 | """ |
| 394 | |
| 395 | # Sampling without replacement entails tracking either potential |
| 396 | # selections (the pool) in a list or previous selections in a set. |
| 397 | |
| 398 | # When the number of selections is small compared to the |
| 399 | # population, then tracking selections is efficient, requiring |
| 400 | # only a small set and an occasional reselection. For |
| 401 | # a larger number of selections, the pool tracking method is |
| 402 | # preferred since the list takes less space than the |
| 403 | # set and it doesn't suffer from frequent reselections. |
| 404 | |
| 405 | # The number of calls to _randbelow() is kept at or near k, the |
| 406 | # theoretical minimum. This is important because running time |
| 407 | # is dominated by _randbelow() and because it extracts the |
| 408 | # least entropy from the underlying random number generators. |
| 409 | |
| 410 | # Memory requirements are kept to the smaller of a k-length |
| 411 | # set or an n-length list. |
| 412 | |
| 413 | # There are other sampling algorithms that do not require |
| 414 | # auxiliary memory, but they were rejected because they made |
| 415 | # too many calls to _randbelow(), making them slower and |
| 416 | # causing them to eat more entropy than necessary. |
| 417 | |
| 418 | if not isinstance(population, _Sequence): |
| 419 | raise TypeError("Population must be a sequence. " |
| 420 | "For dicts or sets, use sorted(d).") |
| 421 | n = len(population) |
| 422 | if counts is not None: |