Merge branch 'gh-pages' into remove-dictionaries-from-errors

Author: noatgnu

.github/workflows/template.yml

@@ -127,13 +127,14 @@ jobs:
         id: check-rmd
         working-directory: lesson
         run: |
-          echo "::set-output name=count::$(shopt -s nullglob; files=($(find . -iname '*.Rmd')); echo ${#files[@]})"
+          echo "count=$(shopt -s nullglob; files=($(find . -iname '*.Rmd')); echo ${#files[@]})" >> $GITHUB_OUTPUT
 
       - name: Set up R
         if: steps.check-rmd.outputs.count != 0
-        uses: r-lib/actions/setup-r@master
+        uses: r-lib/actions/setup-r@v2
         with:
-          r-version: 'release'
+          use-public-rspm: true
+          install-r: false
 
       - name: Install needed packages
         if: steps.check-rmd.outputs.count != 0

.github/workflows/website.yml

@@ -44,13 +44,14 @@ jobs:
       - name: Look for R-markdown files
         id: check-rmd
         run: |
-          echo "::set-output name=count::$(shopt -s nullglob; files=($(find . -iname '*.Rmd')); echo ${#files[@]})"
+          echo "count=$(shopt -s nullglob; files=($(find . -iname '*.Rmd')); echo ${#files[@]})" >> $GITHUB_OUTPUT
 
       - name: Set up R
         if: steps.check-rmd.outputs.count != 0
-        uses: r-lib/actions/setup-r@master
+        uses: r-lib/actions/setup-r@v2
         with:
-          r-version: 'release'
+          use-public-rspm: true
+          install-r: false
 
       - name: Restore R Cache
         if: steps.check-rmd.outputs.count != 0

_episodes/01-intro.md

@@ -14,7 +14,9 @@ keypoints:
 - "Use `variable = value` to assign a value to a variable in order to record it in memory."
 - "Variables are created on demand whenever a value is assigned to them."
 - "Use `print(something)` to display the value of `something`."
+- "Use `# some kind of explanation` to add comments to programs."
 - "Built-in functions are always available to use."
+
 ---
 
 ## Variables
@@ -42,7 +44,7 @@ weight_kg = 60
 {: .language-python}
 
 From now on, whenever we use `weight_kg`, Python will substitute the value we assigned to
-it. In layman's terms, **a variable is a name for a value**.
+it. In layperson's terms, **a variable is a name for a value**.
 
 In Python, variable names:
 
@@ -209,8 +211,12 @@ weight in kilograms is now: 65.0
 > ~~~
 > {: .output}
 >
-> ![Value of 65.0 with weight_kg label stuck on it, and value of 143.0 with weight_lb label
-stuck on it](../fig/python-sticky-note-variables-02.svg)
+> Everything in a line of code following the '#' symbol is a
+> [comment]({{ page.root }}/reference/#comment) that is ignored by Python.
+> Comments allow programmers to leave explanatory notes for other
+> programmers or their future selves.
+> 
+> ![Value of 65.0 with weight_kg label stuck on it, and value of 143.0 with weight_lb label stuck on it](../fig/python-sticky-note-variables-02.svg)
 >
 > Similar to above, the expression `2.2 * weight_kg` is evaluated to `143.0`,
 > and then this value is assigned to the variable `weight_lb` (i.e. the sticky

_episodes/02-numpy.md

@@ -17,7 +17,6 @@ keypoints:
 - "Use `array[x, y]` to select a single element from a 2D array."
 - "Array indices start at 0, not 1."
 - "Use `low:high` to specify a `slice` that includes the indices from `low` to `high-1`."
-- "Use `# some kind of explanation` to add comments to programs."
 - "Use `numpy.mean(array)`, `numpy.max(array)`, and `numpy.min(array)` to calculate simple statistics."
 - "Use `numpy.mean(array, axis=0)` or `numpy.mean(array, axis=1)` to calculate statistics across the specified axis."
 ---
@@ -32,7 +31,7 @@ that can be called upon when needed.
 
 To begin processing the clinical trial inflammation data, we need to load it into Python.
 We can do that using a library called
-[NumPy](http://docs.scipy.org/doc/numpy/ "NumPy Documentation"), which stands for Numerical Python.
+[NumPy](https://numpy.org/doc/stable "NumPy Documentation"), which stands for Numerical Python.
 In general, you should use this library when you want to do fancy things with lots of numbers,
 especially if you have matrices or arrays. To tell Python that we'd like to start using NumPy,
 we need to [import]({{ page.root }}/reference.html#import) it:
@@ -70,9 +69,8 @@ The expression `numpy.loadtxt(...)` is a
 [function call]({{ page.root }}/reference.html#function-call)
 that asks Python to run the [function]({{ page.root }}/reference.html#function) `loadtxt` which
 belongs to the `numpy` library.
-This [dotted notation]({{ page.root }}/reference.html#dotted-notation)
-is used everywhere in Python: the thing that appears before the dot contains the thing that
-appears after.
+The dot notation in Python is used most of all as an object attribute/property specifier or for invoking its method. `object.property` will give you the object.property value,
+`object_name.method()` will invoke on object_name method.
 
 As an example, John Smith is the John that belongs to the Smith family.
 We could use the dot notation to write his name `smith.john`,
@@ -205,16 +203,16 @@ first value in data: 0.0
 {: .output}
 
 ~~~
-print('middle value in data:', data[30, 20])
+print('middle value in data:', data[29, 19])
 ~~~
 {: .language-python}
 
 ~~~
-middle value in data: 13.0
+middle value in data: 16.0
 ~~~
 {: .output}
 
-The expression `data[30, 20]` accesses the element at row 30, column 20. While this expression may
+The expression `data[29, 19]` accesses the element at row 30, column 20. While this expression may
 not surprise you,
  `data[0, 0]` might.
 Programming languages like Fortran, MATLAB and R start counting at 1
@@ -411,11 +409,6 @@ maximum inflammation for patient 0: 18.0
 ~~~
 {: .output}
 
-Everything in a line of code following the '#' symbol is a
-[comment]({{ page.root }}/reference.html#comment) that is ignored by Python.
-Comments allow programmers to leave explanatory notes for other
-programmers or their future selves.
-
 We don't actually need to store the row in a variable of its own.
 Instead, we can combine the selection and the function call:
 

_episodes/04-lists.md

@@ -166,57 +166,80 @@ does not.
 > ## Nested Lists
 > Since a list can contain any Python variables, it can even contain other lists.
 >
-> For example, we could represent the products in the shelves of a small grocery shop:
+> For example, you could represent the products on the shelves of a small grocery shop
+> as a nested list called `veg`:
+>
+> ![`veg` is represented as a shelf full of produce. There are three rows of vegetables
+> on the shelf, and each row contains three baskets of vegetables. We can label
+> each basket according to the type of vegetable it contains, so the top row
+> contains (from left to right) lettuce, lettuce, and peppers.](../fig/04_groceries_veg.png)
+>
+> To store the contents of the shelf in a nested list, you write it this way:
 >
 > ~~~
-> x = [['pepper', 'zucchini', 'onion'],
->      ['cabbage', 'lettuce', 'garlic'],
->      ['apple', 'pear', 'banana']]
+> veg = [['lettuce', 'lettuce', 'peppers', 'zucchini'],
+>      ['lettuce', 'lettuce', 'peppers', 'zucchini'],
+>      ['lettuce', 'cilantro', 'peppers', 'zucchini']]
 > ~~~
 > {: .language-python}
 >
-> Here is a visual example of how indexing a list of lists `x` works:
+> Here are some visual examples of how indexing a list of lists `veg` works. First,
+> you can reference each row on the shelf as a separate list. For example, `veg[2]`
+> represents the bottom row, which is a list of the baskets in that row.
 >
-> [![x is represented as a pepper shaker containing several packets of pepper. [x[0]] is represented
-> as a pepper shaker containing a single packet of pepper. x[0] is represented as a single packet of
-> pepper. x[0][0] is represented as single grain of pepper.  Adapted
-> from @hadleywickham.](../fig/indexing_lists_python.png)][hadleywickham-tweet]
+> ![`veg` is now shown as a list of three rows, with `veg[0]` representing the top row of
+> three baskets, `veg[1]` representing the second row, and `veg[2]` representing the bottom row.](../fig/04_groceries_veg0.png)
 >
-> Using the previously declared list `x`, these would be the results of the
-> index operations shown in the image:
+> Index operations using the image would work like this:
 >
 > ~~~
-> print([x[0]])
+> print(veg[2])
 > ~~~
 > {: .language-python}
 >
 > ~~~
-> [['pepper', 'zucchini', 'onion']]
+> ['lettuce', 'cilantro', 'peppers', 'zucchini']
 > ~~~
 > {: .output}
 >
 > ~~~
-> print(x[0])
+> print(veg[0])
+> ~~~
+> {: .language-python}
+>
+> ~~~
+> ['lettuce', 'lettuce', 'peppers', 'zucchini']
+> ~~~
+> {: .output}
+>
+> To reference a specific basket on a specific shelf, you use two indexes. The first
+> index represents the row (from top to bottom) and the second index represents
+> the specific basket (from left to right).
+> ![`veg` is now shown as a two-dimensional grid, with each basket labeled according to
+> its index in the nested list. The first index is the row number and the second
+> index is the basket number, so `veg[1][3]` represents the basket on the far right
+> side of the second row (basket 4 on row 2): zucchini](../fig/04_groceries_veg00.png)
+>
+> ~~~
+> print(veg[0][0])
 > ~~~
 > {: .language-python}
 >
 > ~~~
-> ['pepper', 'zucchini', 'onion']
+> 'lettuce'
 > ~~~
 > {: .output}
 >
 > ~~~
-> print(x[0][0])
+> print(veg[1][2])
 > ~~~
 > {: .language-python}
 >
 > ~~~
-> 'pepper'
+> 'peppers'
 > ~~~
 > {: .output}
 >
-> Thanks to [Hadley Wickham][hadleywickham-tweet]
-> for the image above.
 {: .callout}
 
 > ## Heterogeneous Lists

_episodes/05-loop.md

@@ -307,8 +307,8 @@ so we should always use it when we can.
 > Given the following loop:
 > ~~~
 > word = 'oxygen'
-> for char in word:
->     print(char)
+> for letter in word:
+>     print(letter)
 > ~~~
 > {: .language-python}
 >

_episodes/08-func.md

@@ -50,7 +50,17 @@ Let's start by defining a function `fahr_to_celsius` that converts temperatures
 from Fahrenheit to Celsius:
 
 ~~~
+def explicit_fahr_to_celsius(temp):
+    # Assign the converted value to a variable
+    converted = ((temp - 32) * (5/9))
+    # Return the value of the new variable
+    return converted
+    
 def fahr_to_celsius(temp):
+    # Return converted value more efficiently using the return
+    # function without creating a new variable. This code does
+    # the same thing as the previous function but it is more explicit
+    # in explaining how the return command works.
     return ((temp - 32) * (5/9))
 ~~~
 {: .language-python}

_episodes/09-errors.md

@@ -195,6 +195,12 @@ hopefully the custom error message is informative enough to help you figure out
 > > `7` is not the right index to use with `messages`.
 > {: .solution}
 {: .challenge}
+=======
+> ## Better errors on newer Pythons
+>
+> Newer versions of Python have improved error printouts.  If you are debugging errors, it is often
+> helpful to use the latest Python version, even if you support older versions of Python.
+{: .callout}
 
 ## Syntax Errors
 
@@ -442,7 +448,9 @@ you will receive a `FileNotFoundError` telling you so.
 If you attempt to write to a file that was opened read-only, Python 3
 returns an `UnsupportedOperationError`.
 More generally, problems with input and output manifest as
-`IOError`s or `OSError`s, depending on the version of Python you use.
+`OSError`s, which may show up as a more specific subclass; you can see
+[the list in the Python docs](https://docs.python.org/3/library/exceptions.html#os-exceptions).
+They all have a unique UNIX `errno`, which is you can see in the error message.
 
 ~~~
 file_handle = open('myfile.txt', 'r')

_episodes/10-defensive.md

@@ -130,10 +130,10 @@ def normalize_rectangle(rect):
     dx = x1 - x0
     dy = y1 - y0
     if dx > dy:
-        scaled = float(dx) / dy
+        scaled = dx / dy
         upper_x, upper_y = 1.0, scaled
     else:
-        scaled = float(dx) / dy
+        scaled = dx / dy
         upper_x, upper_y = scaled, 1.0
 
     assert 0 < upper_x <= 1.0, 'Calculated upper X coordinate invalid'
@@ -304,7 +304,15 @@ Its advocates believe it produces better code faster because:
     rather than to find errors.
 2.  Writing tests helps programmers figure out what the function is actually supposed to do.
 
-Here are three test functions for `range_overlap`:
+We start by defining an empty function `range_overlap`:
+
+~~~
+def range_overlap(ranges):
+    pass
+~~~
+{: .language-python}
+
+Here are three test statements for `range_overlap`:
 
 ~~~
 assert range_overlap([ (0.0, 1.0) ]) == (0.0, 1.0)
@@ -326,10 +334,9 @@ AssertionError:
 {: .error}
 
 The error is actually reassuring:
-we haven't written `range_overlap` yet,
-so if the tests passed,
-it would be a sign that someone else had
-and that we were accidentally using their function.
+we haven't implemented any logic into `range_overlap` yet,
+so if the tests passed, it would indicate that we've written
+an entirely ineffective test.
 
 And as a bonus of writing these tests,
 we've implicitly defined what our input and output look like:
@@ -534,7 +541,7 @@ This violates another important rule of programming:
 > > *   The first assertion checks that the input sequence `values` is not empty.
 > >     An empty sequence such as `[]` will make it fail.
 > > *   The second assertion checks that each value in the list can be turned into an integer.
-> >     Input such as `[1, 2,'c', 3]` will make it fail.
+> >     Input such as `[1, 2, 'c', 3]` will make it fail.
 > > *   The third assertion checks that the total of the list is greater than 0.
 > >     Input such as `[-10, 2, 3]` will make it fail.
 > {: .solution}

_episodes/11-debugging.md

@@ -268,7 +268,7 @@ not more.
 > for patient in patients:
 >     weight, height = patients[0]
 >     bmi = calculate_bmi(height, weight)
->     print("Patient's BMI is: %f" % bmi)
+>     print("Patient's BMI is:", bmi)
 > ~~~
 > {: .language-python}
 >