From 4ee91c69734228e9db5238cc15d689f104257c39 Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Wed, 29 Nov 2023 16:08:09 -0700 Subject: [PATCH 01/29] new `random` concept --- concepts/random/.meta/config.json | 5 + concepts/random/about.md | 171 ++++++++++++++++++++++++++++++ concepts/random/introduction.md | 1 + concepts/random/links.json | 6 ++ config.json | 5 + 5 files changed, 188 insertions(+) create mode 100644 concepts/random/.meta/config.json create mode 100644 concepts/random/about.md create mode 100644 concepts/random/introduction.md create mode 100644 concepts/random/links.json diff --git a/concepts/random/.meta/config.json b/concepts/random/.meta/config.json new file mode 100644 index 0000000000..a37ac47160 --- /dev/null +++ b/concepts/random/.meta/config.json @@ -0,0 +1,5 @@ +{ + "blurb": "The random module contains functionality to generate random values for modelling, simulations and games. It should not be used for security or cryptographic applications.", + "authors": ["bethanyg", "colinleach"], + "contributors": [] +} diff --git a/concepts/random/about.md b/concepts/random/about.md new file mode 100644 index 0000000000..86b826e9fe --- /dev/null +++ b/concepts/random/about.md @@ -0,0 +1,171 @@ +# About + +Many programs need (apparently) random values to simulate real-world events. + +Common, familiar examples include: +- A coin toss: a random value from `('H', 'T')`. +- The roll of a die: a random integer from 1 to 6. +- Shuffling a deck of cards: a random ordering of a card list. + +Generating truly random values with a computer is a surprisingly difficult technical challenge, so you may see these results referred to as "pseudorandom". + +In practice, a well-designed library like the [`random`][random] module in the Python standard library is fast, flexible, and gives results that are amply good enough for most applications in modelling, simulation and games. + +The rest of this page will list a few of the most common functions in `random`. + +We encourage you to explore the full [`random`][random] documentation, as there are many more options. + +## Important Warning! + +The `random` module should __NOT__ be used for security and cryptographic applications. + +Instead, Python provides the [`secrets`][secrets] module. +This is specially optimized for cryptographic security. + +## Create random integers + +The `randrange()` function has three forms, to select a random value from `range(start, stop, step)`: +- `randrange(stop)` gives an integer `n` such that `0 <= n < stop` +- `randrange(start, stop)` gives an integer `n` such that `start <= n < stop` +- `randrange(start, stop, step)` gives an integer `n` such that `start <= n < stop` and `n` is in the sequence `start, start + step, start + 2*step...` + +For the common case where `step == 1`, the `randint(a, b)` function may be more convenient and readable. + +Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` is the same as `randrange(a, b+1)`. + +```python +>>> import random + +>>> random.randrange(500) +219 +>>> [random.randrange(0, 10, 2) for n in range(10)] +[2, 8, 4, 0, 4, 2, 6, 6, 8, 8] + +>>> random.randint(1, 6) # roll a die +4 +``` + +## Working with sequences + +The functions in this section assume that you are starting from some sequence. + +This will typically be a `list`, or with some limitations a `tuple` or `set` (`tuple` is immutable, and `set` is unordered). + +### `choice()` and `choices()` + +The `choice()` function will return one random entry from a sequence. + +At its simplest, the coin-flip example: + +```python +>>> [random.choice(['H', 'T']) for n in range(5)] +['T', 'H', 'H', 'T', 'H'] +``` + +We could do essentially the same with the `choices()` function, supplying a keyword argument with the list length: + +```python +>>> random.choices(['H', 'T'], k=5) +['T', 'H', 'T', 'H', 'H'] +``` + +We assumed a fair coin with equal probability of heads or tails. +Weights can also be specified. + +For example, if a bag contains 10 red balls and 15 green balls, and we pull one out at random: + +```python +>>> random.choices(['red', 'green'], [10, 15]) +['red'] +``` + +### `sample()` + +The `choices()` example above assumes what statisticians call "sampling with replacement". Each choice has no effect on the probability of future choices. + +For example, in the example with red and green balls: after each choice, we return the ball to the bag and shake well before the next choice. + +In a situation where we pull out a red ball and _it stays out_, there are now fewer red balls in the bag and the next choice is less likely to be red. + +To simulate this "sampling without replacement", we have the `sample()` function. + +The syntax of `sample()` is similar to choices, except with `counts` as a keyword parameter: + +```python +>>> random.sample(['red', 'green'], counts=[10, 15], k=10) +['green', 'green', 'green', 'green', 'green', 'red', 'red', 'red', 'red', 'green'] +``` + +Samples are listed in the order they were chosen. + +### `shuffle()` + +Both `choices()` and `sample()` return new lists when `k > 1`. + +In contrast, `shuffle()` randomizes the order of a list _in place_. + +```python +>>> my_list = [1, 2, 3, 4, 5] +>>> random.shuffle(my_list) +>>> my_list +[4, 1, 5, 2, 3] +``` + +The original ordering is lost. + +## Working with distributiions + +Until now, we have concentrated on cases where all outcomes are equally likely. + +For example, `random.randrange(100)` is equally likely to give any integer from 0 to 99. + +Many real-world situations are less simple than this. Statisticians have created a wide variety of `distributions` to describe the results mathematically. + +### Uniform distributions + +For integers, `randrange()` and `randint()` are used when all probabilities are equal. This is called a `uniform` distributuion. + +There are floating-point equivalents to `randrange()` and `randint()`. + +__`random()`__ gives a `float` value `x` such that `0.0 <= x < 1.0`. + +__`uniform(a, b)`__ gives `x` such that `a <= x <= b`. + +```python +>>> [round(random.random(), 3) for n in range(5)] +[0.876, 0.084, 0.483, 0.22, 0.863] + +>>> [round(random.uniform(2, 5), 3) for n in range(5)] +[2.798, 2.539, 3.779, 3.363, 4.33] +``` + +### Gaussian distribution + +Also called the "normal" or "bell-shaped" curve, this is a very common way to describe imprecision in measured values. + +For example, suppose the factory where you work has just bought 10,000 bolts which should be identical. +You want to set up the factory robot to handle them, so you weigh a sample of 100 and find that they have an average (or `mean`) weight of 4.731g. + +This is extremely unlikely to mean that they all weigh exactly 4.731g. +Perhaps you find that values range from 4.627 to 4.794g but cluster around 4.731g. + +This is the [`Gaussian distribution`][gaussian-distribution], for which probabilities peak at the mean and tails off symmetrically on both sides (hence "bell-shaped"). + +To simulate this in software, we need some way to specify the width of the curve (typically, expensive bolts will cluster more tightly around the mean than cheap bolts!) + +By convention, this is done with the [`standard deviation`][standard-deviation]: small values for a sharp, narrow curve, large for a low, broad curve. + +Mathematicians love Greek letters, so we use `mu` for the mean and `sigma` for the standard deviation. +Thus, if you read that "95% of values are within 2-sigma of the mean" or "the Higgs boson has been detected with 5-sigma confidence", such comments relate to the standard deviation. + +```python +>>> mu = 4.731 +>>> sigma = 0.316 +>>> [round(random.gauss(mu, sigma), 3) for n in range(5)] +[4.72, 4.957, 4.64, 4.556, 4.968] +``` + +[random]: https://docs.python.org/3/library/random.html +[secrets]: https://docs.python.org/3/library/secrets.html +[gaussian-distribution]: https://ned.ipac.caltech.edu/level5/Leo/Stats2_3.html +[standard-deviation]: https://www.nlm.nih.gov/oet/ed/stats/02-900.html diff --git a/concepts/random/introduction.md b/concepts/random/introduction.md new file mode 100644 index 0000000000..54ff7637ac --- /dev/null +++ b/concepts/random/introduction.md @@ -0,0 +1 @@ +#TODO: Add introduction for this concept. diff --git a/concepts/random/links.json b/concepts/random/links.json new file mode 100644 index 0000000000..9cf4b2874f --- /dev/null +++ b/concepts/random/links.json @@ -0,0 +1,6 @@ +[ + { + "url": "https://docs.python.org/3/library/random.html/", + "description": "Official documentation for the random module." + } +] diff --git a/config.json b/config.json index 98891388c2..d126b73be0 100644 --- a/config.json +++ b/config.json @@ -2567,6 +2567,11 @@ "uuid": "565f7618-4552-4eb0-b829-d6bacd03deaf", "slug": "with-statement", "name": "With Statement" + }, + { + "uuid": "af6cad74-50c2-48f4-a6ce-cfeb72548d00", + "slug": "random", + "name": "Random" } ], "key_features": [ From 29473312d28dcb236b1b036b51155eca90ae6683 Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Thu, 30 Nov 2023 08:07:23 -0700 Subject: [PATCH 02/29] changed unused variables to underscore --- concepts/random/about.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 86b826e9fe..1bbc702b78 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -38,7 +38,7 @@ Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` >>> random.randrange(500) 219 ->>> [random.randrange(0, 10, 2) for n in range(10)] +>>> [random.randrange(0, 10, 2) for _ in range(10)] [2, 8, 4, 0, 4, 2, 6, 6, 8, 8] >>> random.randint(1, 6) # roll a die @@ -58,7 +58,7 @@ The `choice()` function will return one random entry from a sequence. At its simplest, the coin-flip example: ```python ->>> [random.choice(['H', 'T']) for n in range(5)] +>>> [random.choice(['H', 'T']) for _ in range(5)] ['T', 'H', 'H', 'T', 'H'] ``` @@ -132,10 +132,10 @@ __`random()`__ gives a `float` value `x` such that `0.0 <= x < 1.0`. __`uniform(a, b)`__ gives `x` such that `a <= x <= b`. ```python ->>> [round(random.random(), 3) for n in range(5)] +>>> [round(random.random(), 3) for _ in range(5)] [0.876, 0.084, 0.483, 0.22, 0.863] ->>> [round(random.uniform(2, 5), 3) for n in range(5)] +>>> [round(random.uniform(2, 5), 3) for _ in range(5)] [2.798, 2.539, 3.779, 3.363, 4.33] ``` @@ -161,7 +161,7 @@ Thus, if you read that "95% of values are within 2-sigma of the mean" or "the Hi ```python >>> mu = 4.731 >>> sigma = 0.316 ->>> [round(random.gauss(mu, sigma), 3) for n in range(5)] +>>> [round(random.gauss(mu, sigma), 3) for _ in range(5)] [4.72, 4.957, 4.64, 4.556, 4.968] ``` From 28cc392c11ad72c037524ae65e1571e097164520 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:10:09 -0600 Subject: [PATCH 03/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 1bbc702b78..f9e4566b23 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -15,12 +15,17 @@ The rest of this page will list a few of the most common functions in `random`. We encourage you to explore the full [`random`][random] documentation, as there are many more options. -## Important Warning! +~~~~exercism/caution The `random` module should __NOT__ be used for security and cryptographic applications. Instead, Python provides the [`secrets`][secrets] module. This is specially optimized for cryptographic security. +Some of the prior issues and reasons for creating the secrets module can be found in [PEP 506][PEP 506]. + +[secrets]: https://docs.python.org/3.11/library/secrets.html#module-secrets +[PEP 506]: https://peps.python.org/pep-0506/ +~~~~ ## Create random integers From d0ac75d630dea75e8678cf7a76f9e8db3be64676 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:12:28 -0600 Subject: [PATCH 04/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index f9e4566b23..c17d4dda34 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -52,7 +52,8 @@ Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` ## Working with sequences -The functions in this section assume that you are starting from some sequence. +The functions in this section assume that you are starting from some [sequence][sequence-types], or other container. + This will typically be a `list`, or with some limitations a `tuple` or `set` (`tuple` is immutable, and `set` is unordered). From 4093f7a8798dde22e0a03369f7ed13e5df63e7ae Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:12:52 -0600 Subject: [PATCH 05/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index c17d4dda34..33fe4520c9 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -55,7 +55,8 @@ Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` The functions in this section assume that you are starting from some [sequence][sequence-types], or other container. -This will typically be a `list`, or with some limitations a `tuple` or `set` (`tuple` is immutable, and `set` is unordered). +This will typically be a `list`, or with some limitations a `tuple` or a `set` (_a `tuple` is immutable, and `set` is unordered_). + ### `choice()` and `choices()` From 33a5f90600c64410f5974e95d0aa331b5aca7807 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:13:06 -0600 Subject: [PATCH 06/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 33fe4520c9..8934d08fa5 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -60,7 +60,8 @@ This will typically be a `list`, or with some limitations a `tuple` or a `set` ( ### `choice()` and `choices()` -The `choice()` function will return one random entry from a sequence. +The `choice()` function will return one entry chosen at random from a given sequence. + At its simplest, the coin-flip example: From 96d1a60356435a511fb36d83ab0eb7dcaeb5ca72 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:13:26 -0600 Subject: [PATCH 07/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 8934d08fa5..08769eb5ce 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -63,7 +63,8 @@ This will typically be a `list`, or with some limitations a `tuple` or a `set` ( The `choice()` function will return one entry chosen at random from a given sequence. -At its simplest, the coin-flip example: +At its simplest, this might be a coin-flip example: + ```python >>> [random.choice(['H', 'T']) for _ in range(5)] From 999b443e5e09a40b9607480a79557b15929bfe53 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:13:40 -0600 Subject: [PATCH 08/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 08769eb5ce..9ecdd53ae8 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -132,7 +132,8 @@ Many real-world situations are less simple than this. Statisticians have created ### Uniform distributions -For integers, `randrange()` and `randint()` are used when all probabilities are equal. This is called a `uniform` distributuion. +For integers, `randrange()` and `randint()` are used when all probabilities are equal. This is called a [`uniform`][uniform-distribution] distribution. + There are floating-point equivalents to `randrange()` and `randint()`. From 18c185baa05153f9e27ea7ef757fe9207535dfcc Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:13:59 -0600 Subject: [PATCH 09/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 9ecdd53ae8..d68904b106 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -151,7 +151,8 @@ __`uniform(a, b)`__ gives `x` such that `a <= x <= b`. ### Gaussian distribution -Also called the "normal" or "bell-shaped" curve, this is a very common way to describe imprecision in measured values. +Also called the "normal" distribution or the "bell-shaped" curve, this is a very common way to describe imprecision in measured values. + For example, suppose the factory where you work has just bought 10,000 bolts which should be identical. You want to set up the factory robot to handle them, so you weigh a sample of 100 and find that they have an average (or `mean`) weight of 4.731g. From b318855c1e2203841a3d067fddaae739aa31ae59 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:15:35 -0600 Subject: [PATCH 10/29] Update concepts/random/about.md I have been avoiding $\LaTeX$ (very reluctantly, but Jeremy and Erik insist). I guess Unicode will save us here. Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index d68904b106..8cf1f2395e 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -166,7 +166,8 @@ To simulate this in software, we need some way to specify the width of the curve By convention, this is done with the [`standard deviation`][standard-deviation]: small values for a sharp, narrow curve, large for a low, broad curve. -Mathematicians love Greek letters, so we use `mu` for the mean and `sigma` for the standard deviation. +Mathematicians love Greek letters, so we use `μ` ('mu') to represent the mean and `σ` ('sigma') to represent the standard deviation. + Thus, if you read that "95% of values are within 2-sigma of the mean" or "the Higgs boson has been detected with 5-sigma confidence", such comments relate to the standard deviation. ```python From e1b6bba30aa72c3f8f63ea27912bab3934ad397e Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:15:53 -0600 Subject: [PATCH 11/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 8cf1f2395e..d3ed7ed22c 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -168,7 +168,8 @@ By convention, this is done with the [`standard deviation`][standard-deviation]: Mathematicians love Greek letters, so we use `μ` ('mu') to represent the mean and `σ` ('sigma') to represent the standard deviation. -Thus, if you read that "95% of values are within 2-sigma of the mean" or "the Higgs boson has been detected with 5-sigma confidence", such comments relate to the standard deviation. +Thus, if you read that "95% of values are within 2σ of μ" or "the Higgs boson has been detected with 5-sigma confidence", such comments relate to the standard deviation. + ```python >>> mu = 4.731 From f4093769184ba292bc1c36cb64afede54e87690d Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:16:22 -0600 Subject: [PATCH 12/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index d3ed7ed22c..63509c44e0 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -180,5 +180,9 @@ Thus, if you read that "95% of values are within 2σ of μ" or "the Higgs boson [random]: https://docs.python.org/3/library/random.html [secrets]: https://docs.python.org/3/library/secrets.html -[gaussian-distribution]: https://ned.ipac.caltech.edu/level5/Leo/Stats2_3.html -[standard-deviation]: https://www.nlm.nih.gov/oet/ed/stats/02-900.html +[sequence-types]: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range +[gaussian-distribution]: https://simple.wikipedia.org/wiki/Normal_distribution +[probability-distribution]: https://simple.wikipedia.org/wiki/Probability_distribution +[sampling-with-replacement]: https://www.youtube.com/watch?v=LnGFL_A6A6A +[standard-deviation]: https://simple.wikipedia.org/wiki/Standard_deviation +[uniform-distribution]: https://www.investopedia.com/terms/u/uniform-distribution.asp#:~:text=In%20statistics%2C%20uniform%20distribution%20refers,a%20spade%20is%20equally%20likely. From 4a87cdc2a03f0dcc1b0211172a80c719103485fd Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:17:02 -0600 Subject: [PATCH 13/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 63509c44e0..ecdc7adf94 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -67,9 +67,9 @@ At its simplest, this might be a coin-flip example: ```python +# This will pick one of the two values in the list at random 5 separate times >>> [random.choice(['H', 'T']) for _ in range(5)] ['T', 'H', 'H', 'T', 'H'] -``` We could do essentially the same with the `choices()` function, supplying a keyword argument with the list length: From 4756c7fe8708feee588a969b4afe14cbf00c1f53 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:17:18 -0600 Subject: [PATCH 14/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index ecdc7adf94..bd1ce81d1e 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -71,7 +71,8 @@ At its simplest, this might be a coin-flip example: >>> [random.choice(['H', 'T']) for _ in range(5)] ['T', 'H', 'H', 'T', 'H'] -We could do essentially the same with the `choices()` function, supplying a keyword argument with the list length: +We could accomplish essentially the same thing using the `choices()` function, supplying a keyword argument with the list length: + ```python >>> random.choices(['H', 'T'], k=5) From 07bf0a88cf2490ae499186f82d6343efedfb0306 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:17:38 -0600 Subject: [PATCH 15/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index bd1ce81d1e..0203c15f51 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -79,7 +79,8 @@ We could accomplish essentially the same thing using the `choices()` function, s ['T', 'H', 'T', 'H', 'H'] ``` -We assumed a fair coin with equal probability of heads or tails. +In the examples above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified. + Weights can also be specified. For example, if a bag contains 10 red balls and 15 green balls, and we pull one out at random: From d188e10301671e233bf6aac107c371f1a6a6fd25 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:17:53 -0600 Subject: [PATCH 16/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 1 - 1 file changed, 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 0203c15f51..b6ad2c662d 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -81,7 +81,6 @@ We could accomplish essentially the same thing using the `choices()` function, s In the examples above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified. -Weights can also be specified. For example, if a bag contains 10 red balls and 15 green balls, and we pull one out at random: From 648565379b00b21bf40e70b450173588da3c7983 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:18:11 -0600 Subject: [PATCH 17/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index b6ad2c662d..2333b09b8d 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -82,7 +82,8 @@ We could accomplish essentially the same thing using the `choices()` function, s In the examples above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified. -For example, if a bag contains 10 red balls and 15 green balls, and we pull one out at random: +For example, if a bag contains 10 red balls and 15 green balls, and we would like to pull one out at random: + ```python >>> random.choices(['red', 'green'], [10, 15]) From 3b7c53c7ff15ba0a59c05f187b7eba57d05fecb6 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:18:36 -0600 Subject: [PATCH 18/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 2333b09b8d..255f36daa0 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -92,7 +92,9 @@ For example, if a bag contains 10 red balls and 15 green balls, and we would lik ### `sample()` -The `choices()` example above assumes what statisticians call "sampling with replacement". Each choice has no effect on the probability of future choices. +The `choices()` example above assumes what statisticians call ["sampling with replacement"][sampling-with-replacement]. +Each pick or choice has **no effect** on the probability of future choices, and the distribution of potential choices remains the same from pick to pick. + For example, in the example with red and green balls: after each choice, we return the ball to the bag and shake well before the next choice. From 2e38e7809247475cfaddc036f3fb2f46f3c84866 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:18:55 -0600 Subject: [PATCH 19/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 255f36daa0..82ca4929e1 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -96,7 +96,8 @@ The `choices()` example above assumes what statisticians call ["sampling with re Each pick or choice has **no effect** on the probability of future choices, and the distribution of potential choices remains the same from pick to pick. -For example, in the example with red and green balls: after each choice, we return the ball to the bag and shake well before the next choice. +In the example with red and green balls: after each choice, we _return_ the ball to the bag and shake well before the next pick. + In a situation where we pull out a red ball and _it stays out_, there are now fewer red balls in the bag and the next choice is less likely to be red. From d355185037a6c11297aa0f5c899596ba2d8fac08 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:19:17 -0600 Subject: [PATCH 20/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 82ca4929e1..9967d77b0d 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -99,7 +99,8 @@ Each pick or choice has **no effect** on the probability of future choices, and In the example with red and green balls: after each choice, we _return_ the ball to the bag and shake well before the next pick. -In a situation where we pull out a red ball and _it stays out_, there are now fewer red balls in the bag and the next choice is less likely to be red. +This is in contrast to a situation where we pull out a red ball and _it stays out_. +Not returning the ball means there are now fewer red balls in the bag, and the next choice is now _less likely_ to be red. To simulate this "sampling without replacement", we have the `sample()` function. From 2aaa71822e817b780a5e1c9a93b2eee136a0ee20 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:19:34 -0600 Subject: [PATCH 21/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 9967d77b0d..4d68861b87 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -102,7 +102,8 @@ In the example with red and green balls: after each choice, we _return_ the ball This is in contrast to a situation where we pull out a red ball and _it stays out_. Not returning the ball means there are now fewer red balls in the bag, and the next choice is now _less likely_ to be red. -To simulate this "sampling without replacement", we have the `sample()` function. +To simulate this "sampling without replacement", the random module provides the `sample()` function. + The syntax of `sample()` is similar to choices, except with `counts` as a keyword parameter: From 5cf1dff46cd38d6cdc5d46f99804d0816288b71f Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:19:56 -0600 Subject: [PATCH 22/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 4d68861b87..fe2dec26e1 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -105,7 +105,8 @@ Not returning the ball means there are now fewer red balls in the bag, and the n To simulate this "sampling without replacement", the random module provides the `sample()` function. -The syntax of `sample()` is similar to choices, except with `counts` as a keyword parameter: +The syntax of `sample()` is similar to `choices()`, except it adds a `counts` keyword parameter: + ```python >>> random.sample(['red', 'green'], counts=[10, 15], k=10) From b801b1018a4f81687b1cd1d5e68858b153c0403b Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:20:12 -0600 Subject: [PATCH 23/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index fe2dec26e1..4b6061277d 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -113,7 +113,8 @@ The syntax of `sample()` is similar to `choices()`, except it adds a `counts` ke ['green', 'green', 'green', 'green', 'green', 'red', 'red', 'red', 'red', 'green'] ``` -Samples are listed in the order they were chosen. +The samples are returned in the order they were chosen. + ### `shuffle()` From df91e31a1426c9ccdccd600dbec2917693cbbf71 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:20:35 -0600 Subject: [PATCH 24/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 4b6061277d..78a51a15dc 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -120,7 +120,8 @@ The samples are returned in the order they were chosen. Both `choices()` and `sample()` return new lists when `k > 1`. -In contrast, `shuffle()` randomizes the order of a list _in place_. +In contrast, `shuffle()` randomizes the order of a list _**in place**_, and the original ordering is lost. + ```python >>> my_list = [1, 2, 3, 4, 5] From 7ccdf3640bb2dfdd7a150743d15e965fb805ee07 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:20:46 -0600 Subject: [PATCH 25/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 1 - 1 file changed, 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 78a51a15dc..4088ac7249 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -130,7 +130,6 @@ In contrast, `shuffle()` randomizes the order of a list _**in place**_, and the [4, 1, 5, 2, 3] ``` -The original ordering is lost. ## Working with distributiions From 72e2d7fb032408d6ff594b6aeee6905f50a45ec3 Mon Sep 17 00:00:00 2001 From: colinleach Date: Tue, 5 Dec 2023 19:21:11 -0600 Subject: [PATCH 26/29] Update concepts/random/about.md Co-authored-by: BethanyG --- concepts/random/about.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 4088ac7249..90857d336e 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -137,7 +137,9 @@ Until now, we have concentrated on cases where all outcomes are equally likely. For example, `random.randrange(100)` is equally likely to give any integer from 0 to 99. -Many real-world situations are less simple than this. Statisticians have created a wide variety of `distributions` to describe the results mathematically. +Many real-world situations are far less simple than this. +As a result, statisticians have created a wide variety of [`distributions`][probability-distribution] to describe "real world" results mathematically. + ### Uniform distributions From fed3a66a4d3199012128b294def51e3ff1910c72 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Wed, 6 Dec 2023 13:56:05 -0800 Subject: [PATCH 27/29] Added Introduction.md and Links --- concepts/random/.meta/config.json | 2 +- concepts/random/about.md | 83 ++++++++++++++++++----- concepts/random/introduction.md | 106 +++++++++++++++++++++++++++++- concepts/random/links.json | 8 +++ 4 files changed, 180 insertions(+), 19 deletions(-) diff --git a/concepts/random/.meta/config.json b/concepts/random/.meta/config.json index a37ac47160..7319e329ba 100644 --- a/concepts/random/.meta/config.json +++ b/concepts/random/.meta/config.json @@ -1,5 +1,5 @@ { "blurb": "The random module contains functionality to generate random values for modelling, simulations and games. It should not be used for security or cryptographic applications.", - "authors": ["bethanyg", "colinleach"], + "authors": ["BethanyG", "colinleach"], "contributors": [] } diff --git a/concepts/random/about.md b/concepts/random/about.md index 90857d336e..bc76b2e4ef 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -13,7 +13,7 @@ In practice, a well-designed library like the [`random`][random] module in the P The rest of this page will list a few of the most common functions in `random`. -We encourage you to explore the full [`random`][random] documentation, as there are many more options. +We encourage you to explore the full [`random`][random] documentation, as there are many more options than what we cover here. ~~~~exercism/caution @@ -25,31 +25,84 @@ Some of the prior issues and reasons for creating the secrets module can be foun [secrets]: https://docs.python.org/3.11/library/secrets.html#module-secrets [PEP 506]: https://peps.python.org/pep-0506/ -~~~~ +~~~~ -## Create random integers + +## Importing + +Before you can utilize the tools in the `random` module, you must first import it: + +```python +>>> import random + +# Choose random integer from a range +>>> random.randrange(1000) +360 + +>>> random.randrange(-1, 500) +228 + +>>> random.randrange(-10, 11, 2) +-8 + +# Choose random integer between two values (inclusive) +>>> random.randint(5, 25) +22 + +``` + +To avoid typing the name of the module, you can import specific functions by name: + +```python +>>> from random import choice, choices + +# Using choice() to pick Heads or Tails 10 times +>>> tosses = [] +>>> for side in range(10): +>>> tosses.append(choice(['H', 'T'])) + +>>> print(tosses) +['H', 'H', 'H', 'H', 'H', 'H', 'H', 'T', 'T', 'H'] + + +# Using choices() to pick Heads or Tails 8 times +>>> picks = [] +>>> picks.extend(choices(['H', 'T'], k=8)) +>>> print(picks) +['T', 'H', 'H', 'T', 'H', 'H', 'T', 'T'] +``` + + +## Creating random integers The `randrange()` function has three forms, to select a random value from `range(start, stop, step)`: -- `randrange(stop)` gives an integer `n` such that `0 <= n < stop` -- `randrange(start, stop)` gives an integer `n` such that `start <= n < stop` -- `randrange(start, stop, step)` gives an integer `n` such that `start <= n < stop` and `n` is in the sequence `start, start + step, start + 2*step...` + 1. `randrange(stop)` gives an integer `n` such that `0 <= n < stop` + 2. `randrange(start, stop)` gives an integer `n` such that `start <= n < stop` + 3. `randrange(start, stop, step)` gives an integer `n` such that `start <= n < stop` and `n` is in the sequence `start, start + step, start + 2*step...` For the common case where `step == 1`, the `randint(a, b)` function may be more convenient and readable. - -Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` is the same as `randrange(a, b+1)`. +Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` is the same as using `randrange(a, b+1)`: ```python >>> import random +# Slect one number at random from the range 0, 499 >>> random.randrange(500) 219 ->>> [random.randrange(0, 10, 2) for _ in range(10)] + +# Select 10 numbers at random between 0 and 9 two steps apart. +>>> numbers = [] +>>> for integer in range(10): +>>> numbers.append(random.randrange(0, 10, 2)) +>>> print(numbers) [2, 8, 4, 0, 4, 2, 6, 6, 8, 8] ->>> random.randint(1, 6) # roll a die +# roll a die +>>> random.randint(1, 6) 4 ``` + ## Working with sequences The functions in this section assume that you are starting from some [sequence][sequence-types], or other container. @@ -62,9 +115,7 @@ This will typically be a `list`, or with some limitations a `tuple` or a `set` ( The `choice()` function will return one entry chosen at random from a given sequence. - -At its simplest, this might be a coin-flip example: - +At its simplest, this might be a coin-flip: ```python # This will pick one of the two values in the list at random 5 separate times @@ -84,7 +135,6 @@ In the examples above, we assumed a fair coin with equal probability of heads or For example, if a bag contains 10 red balls and 15 green balls, and we would like to pull one out at random: - ```python >>> random.choices(['red', 'green'], [10, 15]) ['red'] @@ -189,11 +239,10 @@ Thus, if you read that "95% of values are within 2σ of μ" or "the Higgs boson [4.72, 4.957, 4.64, 4.556, 4.968] ``` -[random]: https://docs.python.org/3/library/random.html -[secrets]: https://docs.python.org/3/library/secrets.html -[sequence-types]: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range [gaussian-distribution]: https://simple.wikipedia.org/wiki/Normal_distribution [probability-distribution]: https://simple.wikipedia.org/wiki/Probability_distribution +[random]: https://docs.python.org/3/library/random.html [sampling-with-replacement]: https://www.youtube.com/watch?v=LnGFL_A6A6A +[sequence-types]: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range [standard-deviation]: https://simple.wikipedia.org/wiki/Standard_deviation [uniform-distribution]: https://www.investopedia.com/terms/u/uniform-distribution.asp#:~:text=In%20statistics%2C%20uniform%20distribution%20refers,a%20spade%20is%20equally%20likely. diff --git a/concepts/random/introduction.md b/concepts/random/introduction.md index 54ff7637ac..0e1eddc5b8 100644 --- a/concepts/random/introduction.md +++ b/concepts/random/introduction.md @@ -1 +1,105 @@ -#TODO: Add introduction for this concept. +# Introduction + +Many programs need (apparently) random values to simulate real-world events. + +Common, familiar examples include: +- A coin toss: a random value from `('H', 'T')`. +- The roll of a die: a random integer from 1 to 6. +- Shuffling a deck of cards: a random ordering of a card list. +- The creation of trees and bushes in a 3-D graphics simulation. + +Generating _truly_ random values with a computer is a [surprisingly difficult technical challenge][truly-random], so you may see these results referred to as "pseudorandom". + +In practice, a well-designed library like the [`random`][random] module in the Python standard library is fast, flexible, and gives results that are amply good enough for most applications in modelling, simulation and games. + +For this brief introduction, we show the four most commonly used functions from the module. +We encourage you to explore the full [`random`][random] documentation, as there are many tools and options. + + +~~~~exercism/caution + +The `random` module should __NOT__ be used for security and cryptographic applications!! + +Instead, Python provides the [`secrets`][secrets] module. +This is specially optimized for cryptographic security. +Some of the prior issues and reasons for creating the secrets module can be found in [PEP 506][PEP 506]. + +[secrets]: https://docs.python.org/3.11/library/secrets.html#module-secrets +[PEP 506]: https://peps.python.org/pep-0506/ +~~~~ + + +Before you can utilize the tools in the `random` module, you must first import it: + +```python +>>> import random + +# Choose random integer from a range +>>> random.randrange(1000) +360 + +>>> random.randrange(-1, 500) +228 + +>>> random.randrange(-10, 11, 2) +-8 + +# Choose random integer between two values (inclusive) +>>> random.randint(5, 25) +22 + +``` + +To avoid typing the name of the module, you can import specific functions by name: + +```python +>>> from random import choice, choices + +# Using choice() to pick Heads or Tails 10 times +>>> tosses = [] +>>> for side in range(10): +>>> tosses.append(choice(['H', 'T'])) + +>>> print(tosses) +['H', 'H', 'H', 'H', 'H', 'H', 'H', 'T', 'T', 'H'] + + +# Using choices() to pick Heads or Tails 8 times +>>> picks = [] +>>> picks.extend(choices(['H', 'T'], k=8)) +>>> print(picks) +['T', 'H', 'H', 'T', 'H', 'H', 'T', 'T'] +``` + + +## `randrange()` and `randint()` + +Shown in the first example above, the `randrange()` function has three forms: + +1. `randrange(stop)` gives an integer `n` such that `0 <= n < stop` +2. `randrange(start, stop)` gives an integer `n` such that `start <= n < stop` +3. `randrange(start, stop, step)` gives an integer `n` such that `start <= n < stop` + and `n` is in the sequence `start, start + step, start + 2*step...` + +For the most common case where `step == 1`, `randint(a, b)` may be more convenient and readable. +Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` is the same as using `randrange(a, b+1)`. + + +## `choice()` and `choices()` + +These two functions assume that you are starting from some [sequence][sequence-types], or other container. +This will typically be a `list`, or with some limitations a `tuple` or a `set` (_a `tuple` is immutable, and `set` is unordered_). + +The `choice()` function will return one entry chosen at random from a given sequence, and `choices()` will return `k` number of entries chose at random from a given sequence. +In the examples shown above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified. + +For example, if a bag contains 10 red balls and 15 green balls, and we would like to pull one out at random: + + +```python +>>> random.choices(['red', 'green'], [10, 15]) +['red'] +``` + +[random]: https://docs.python.org/3/library/random.html +[sequence-types]: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range diff --git a/concepts/random/links.json b/concepts/random/links.json index 9cf4b2874f..22f60dbfb4 100644 --- a/concepts/random/links.json +++ b/concepts/random/links.json @@ -2,5 +2,13 @@ { "url": "https://docs.python.org/3/library/random.html/", "description": "Official documentation for the random module." + }, + { + "url": "https://engineering.mit.edu/engage/ask-an-engineer/can-a-computer-generate-a-truly-random-number/", + "description": "MIT Engineering: Can a computer generate a truly random number?" + }, + { + "url": "https://www.malwarebytes.com/blog/news/2013/09/in-computers-are-random-numbers-really-random", + "description": "Are Random Numbers Really Random?" } ] From 666435bde720ae31d7d46ac4c19c9847fdcd9fcd Mon Sep 17 00:00:00 2001 From: BethanyG Date: Wed, 6 Dec 2023 17:24:47 -0800 Subject: [PATCH 28/29] Small touchups and link fixes --- concepts/random/about.md | 19 ++++++------------- concepts/random/introduction.md | 1 + 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index bc76b2e4ef..51ce5aea65 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -7,13 +7,13 @@ Common, familiar examples include: - The roll of a die: a random integer from 1 to 6. - Shuffling a deck of cards: a random ordering of a card list. -Generating truly random values with a computer is a surprisingly difficult technical challenge, so you may see these results referred to as "pseudorandom". +Generating truly random values with a computer is a [surprisingly difficult technical challenge][truly-random], so you may see these results referred to as "pseudorandom". In practice, a well-designed library like the [`random`][random] module in the Python standard library is fast, flexible, and gives results that are amply good enough for most applications in modelling, simulation and games. The rest of this page will list a few of the most common functions in `random`. +We encourage you to explore the full `random` documentation, as there are many more options than what we cover here. -We encourage you to explore the full [`random`][random] documentation, as there are many more options than what we cover here. ~~~~exercism/caution @@ -114,7 +114,6 @@ This will typically be a `list`, or with some limitations a `tuple` or a `set` ( ### `choice()` and `choices()` The `choice()` function will return one entry chosen at random from a given sequence. - At its simplest, this might be a coin-flip: ```python @@ -131,8 +130,6 @@ We could accomplish essentially the same thing using the `choices()` function, s ``` In the examples above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified. - - For example, if a bag contains 10 red balls and 15 green balls, and we would like to pull one out at random: ```python @@ -140,6 +137,7 @@ For example, if a bag contains 10 red balls and 15 green balls, and we would lik ['red'] ``` + ### `sample()` The `choices()` example above assumes what statisticians call ["sampling with replacement"][sampling-with-replacement]. @@ -147,14 +145,10 @@ Each pick or choice has **no effect** on the probability of future choices, and In the example with red and green balls: after each choice, we _return_ the ball to the bag and shake well before the next pick. - - This is in contrast to a situation where we pull out a red ball and _it stays out_. Not returning the ball means there are now fewer red balls in the bag, and the next choice is now _less likely_ to be red. To simulate this "sampling without replacement", the random module provides the `sample()` function. - - The syntax of `sample()` is similar to `choices()`, except it adds a `counts` keyword parameter: @@ -170,8 +164,7 @@ The samples are returned in the order they were chosen. Both `choices()` and `sample()` return new lists when `k > 1`. -In contrast, `shuffle()` randomizes the order of a list _**in place**_, and the original ordering is lost. - +In contrast, `shuffle()` randomizes the order of a list _**in place**_, and the original ordering is lost: ```python >>> my_list = [1, 2, 3, 4, 5] @@ -181,10 +174,9 @@ In contrast, `shuffle()` randomizes the order of a list _**in place**_, and the ``` -## Working with distributiions +## Working with Distributions Until now, we have concentrated on cases where all outcomes are equally likely. - For example, `random.randrange(100)` is equally likely to give any integer from 0 to 99. Many real-world situations are far less simple than this. @@ -245,4 +237,5 @@ Thus, if you read that "95% of values are within 2σ of μ" or "the Higgs boson [sampling-with-replacement]: https://www.youtube.com/watch?v=LnGFL_A6A6A [sequence-types]: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range [standard-deviation]: https://simple.wikipedia.org/wiki/Standard_deviation +[truly-random]: https://www.malwarebytes.com/blog/news/2013/09/in-computers-are-random-numbers-really-random [uniform-distribution]: https://www.investopedia.com/terms/u/uniform-distribution.asp#:~:text=In%20statistics%2C%20uniform%20distribution%20refers,a%20spade%20is%20equally%20likely. diff --git a/concepts/random/introduction.md b/concepts/random/introduction.md index 0e1eddc5b8..230c891117 100644 --- a/concepts/random/introduction.md +++ b/concepts/random/introduction.md @@ -103,3 +103,4 @@ For example, if a bag contains 10 red balls and 15 green balls, and we would lik [random]: https://docs.python.org/3/library/random.html [sequence-types]: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range +[truly-random]: https://www.malwarebytes.com/blog/news/2013/09/in-computers-are-random-numbers-really-random From 15a9211f2785d2c9681b83efe9c421821087c06d Mon Sep 17 00:00:00 2001 From: BethanyG Date: Wed, 6 Dec 2023 17:45:34 -0800 Subject: [PATCH 29/29] More Typo Fixes --- concepts/random/about.md | 30 +++++++++++++++++------------- concepts/random/introduction.md | 4 +++- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/concepts/random/about.md b/concepts/random/about.md index 51ce5aea65..9ed984179d 100644 --- a/concepts/random/about.md +++ b/concepts/random/about.md @@ -15,6 +15,7 @@ The rest of this page will list a few of the most common functions in `random`. We encourage you to explore the full `random` documentation, as there are many more options than what we cover here. + ~~~~exercism/caution The `random` module should __NOT__ be used for security and cryptographic applications. @@ -28,6 +29,7 @@ Some of the prior issues and reasons for creating the secrets module can be foun ~~~~ + ## Importing Before you can utilize the tools in the `random` module, you must first import it: @@ -86,7 +88,7 @@ Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` ```python >>> import random -# Slect one number at random from the range 0, 499 +# Select one number at random from the range 0, 499 >>> random.randrange(500) 219 @@ -103,6 +105,7 @@ Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` ``` + ## Working with sequences The functions in this section assume that you are starting from some [sequence][sequence-types], or other container. @@ -111,6 +114,7 @@ The functions in this section assume that you are starting from some [sequence][ This will typically be a `list`, or with some limitations a `tuple` or a `set` (_a `tuple` is immutable, and `set` is unordered_). + ### `choice()` and `choices()` The `choice()` function will return one entry chosen at random from a given sequence. @@ -129,6 +133,7 @@ We could accomplish essentially the same thing using the `choices()` function, s ['T', 'H', 'T', 'H', 'H'] ``` + In the examples above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified. For example, if a bag contains 10 red balls and 15 green balls, and we would like to pull one out at random: @@ -138,9 +143,10 @@ For example, if a bag contains 10 red balls and 15 green balls, and we would lik ``` + ### `sample()` -The `choices()` example above assumes what statisticians call ["sampling with replacement"][sampling-with-replacement]. +The `choices()` example above assumes what statisticians call ["sampling with replacement"][sampling-with-replacement]. Each pick or choice has **no effect** on the probability of future choices, and the distribution of potential choices remains the same from pick to pick. @@ -157,13 +163,13 @@ The syntax of `sample()` is similar to `choices()`, except it adds a `counts` ke ['green', 'green', 'green', 'green', 'green', 'red', 'red', 'red', 'red', 'green'] ``` -The samples are returned in the order they were chosen. +Samples are returned in the order they were chosen. + ### `shuffle()` Both `choices()` and `sample()` return new lists when `k > 1`. - In contrast, `shuffle()` randomizes the order of a list _**in place**_, and the original ordering is lost: ```python @@ -179,13 +185,15 @@ In contrast, `shuffle()` randomizes the order of a list _**in place**_, and the Until now, we have concentrated on cases where all outcomes are equally likely. For example, `random.randrange(100)` is equally likely to give any integer from 0 to 99. -Many real-world situations are far less simple than this. +Many real-world situations are far less simple than this. As a result, statisticians have created a wide variety of [`distributions`][probability-distribution] to describe "real world" results mathematically. + ### Uniform distributions -For integers, `randrange()` and `randint()` are used when all probabilities are equal. This is called a [`uniform`][uniform-distribution] distribution. +For integers, `randrange()` and `randint()` are used when all probabilities are equal. +This is called a [`uniform`][uniform-distribution] distribution. There are floating-point equivalents to `randrange()` and `randint()`. @@ -202,28 +210,24 @@ __`uniform(a, b)`__ gives `x` such that `a <= x <= b`. [2.798, 2.539, 3.779, 3.363, 4.33] ``` + + ### Gaussian distribution Also called the "normal" distribution or the "bell-shaped" curve, this is a very common way to describe imprecision in measured values. - For example, suppose the factory where you work has just bought 10,000 bolts which should be identical. You want to set up the factory robot to handle them, so you weigh a sample of 100 and find that they have an average (or `mean`) weight of 4.731g. - This is extremely unlikely to mean that they all weigh exactly 4.731g. Perhaps you find that values range from 4.627 to 4.794g but cluster around 4.731g. This is the [`Gaussian distribution`][gaussian-distribution], for which probabilities peak at the mean and tails off symmetrically on both sides (hence "bell-shaped"). - -To simulate this in software, we need some way to specify the width of the curve (typically, expensive bolts will cluster more tightly around the mean than cheap bolts!) +To simulate this in software, we need some way to specify the width of the curve (_typically, expensive bolts will cluster more tightly around the mean than cheap bolts!_). By convention, this is done with the [`standard deviation`][standard-deviation]: small values for a sharp, narrow curve, large for a low, broad curve. - Mathematicians love Greek letters, so we use `μ` ('mu') to represent the mean and `σ` ('sigma') to represent the standard deviation. - Thus, if you read that "95% of values are within 2σ of μ" or "the Higgs boson has been detected with 5-sigma confidence", such comments relate to the standard deviation. - ```python >>> mu = 4.731 >>> sigma = 0.316 diff --git a/concepts/random/introduction.md b/concepts/random/introduction.md index 230c891117..6bf880be57 100644 --- a/concepts/random/introduction.md +++ b/concepts/random/introduction.md @@ -72,6 +72,7 @@ To avoid typing the name of the module, you can import specific functions by nam ``` + ## `randrange()` and `randint()` Shown in the first example above, the `randrange()` function has three forms: @@ -85,12 +86,13 @@ For the most common case where `step == 1`, `randint(a, b)` may be more convenie Possible results from `randint()` _include_ the upper bound, so `randint(a, b)` is the same as using `randrange(a, b+1)`. + ## `choice()` and `choices()` These two functions assume that you are starting from some [sequence][sequence-types], or other container. This will typically be a `list`, or with some limitations a `tuple` or a `set` (_a `tuple` is immutable, and `set` is unordered_). -The `choice()` function will return one entry chosen at random from a given sequence, and `choices()` will return `k` number of entries chose at random from a given sequence. +The `choice()` function will return one entry chosen at random from a given sequence, and `choices()` will return `k` number of entries chosen at random from a given sequence. In the examples shown above, we assumed a fair coin with equal probability of heads or tails, but weights can also be specified. For example, if a bag contains 10 red balls and 15 green balls, and we would like to pull one out at random: