Merge minor updates.

Author: frobnitzem

episodes/01-xrays.md

@@ -86,8 +86,8 @@ import os
 # If your dataset is compressed, unzip with:
 # !unzip chest_xrays.zip
 
-# Define folders containing images
-data_path = os.path.join("chest_xrays")
+# Define folders containing images (assume we are in Desktop/src/ml-xray)
+data_path = "chest_xrays"
 effusion_path = os.path.join(data_path, "effusion", "*.png")
 normal_path = os.path.join(data_path, "normal", "*.png")
 
@@ -104,6 +104,10 @@ Number of cases with pleural effusion:  350
 Number of normal cases:  350
 ```
 
+Note that `glob()` makes a list of the directory contents in
+an unspecified order.  If you want consistent results, you should
+use `sort(effusion_list)`.  This is less important
+for our case, since we are going to shuffle these later.
 
 
 :::::::::::::::::::::::::::::::::::::::: keypoints

episodes/02-visualisation.md

@@ -116,7 +116,7 @@ print(image.shape)
 ```
 
 Here we see that the image has 3 dimensions. The first dimension is height (512 pixels) and the second is width (also 512 pixels).
-The presence of a third dimension indicates that we are looking at a color image ("RGB", or Red, Green, Blue).
+The presence of a third dimension indicates that we are looking at a color image. The last "RGB" index holds separate Red, Green, and Blue channels.  For these images, however, R=G=B, so it doesn't appear to have color.
 
 For more detail on image representation in Python, take a look at the [Data Carpentry course on Image Processing with Python](https://datacarpentry.org/image-processing/). The following image is reproduced from the [section on Image Representation](https://datacarpentry.org/image-processing/03-skimage-images/index.html).
 
@@ -171,6 +171,15 @@ dataset = dataset_effusion + dataset_normal
 labels = np.concatenate([label_effusion, label_normal])
 ```
 
+:::::::::::::::::::::::::::::::::::::::: Performance Optimization
+
+Pro Tip: the code above loads all 700 images at once.  In real-world
+deep learning, we use Data Loaders (like torch.util.data.DataLoader) to
+load images from disk on-the-fly during training.  This avoids the memory
+bottleneck of loading the entire dataset into RAM.
+
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
 ### Downsampling
 
 X-ray images are often high resolution, which can be useful for detailed clinical interpretation. However, for training a machine learning model, especially in an educational or prototype setting, using smaller images can reduce:
@@ -204,6 +213,10 @@ for i in range(len(dataset)):
   dataset[i] = (dataset[i] - np.mean(dataset[i])) / np.std(dataset[i])
 ```
 
+Note that this standardizes each image individually, so that
+the image mean is now zero for *every* image.  If we had standardized the entire
+dataset, there would still be variations in `dataset[i].mean()`.
+
 ### Reshaping
 
 Finally, we'll convert our dataset from a list to an array. We are expecting it to be (700, 256, 256), representing 700 images (350 effusion and 350 normal), each with dimensions 256×256.
@@ -247,6 +260,9 @@ plt.imshow(dataset[idx], cmap='gray', vmin=min(vals), vmax=max(vals))
 
 ![](fig/final_example_image.png){alt='Example greyscale image' width="400px"}
 
+Note that vmin and vmax are used because our images are no longer on a 0-255 scale,
+but have values centered around zero.  Without specifying these, matplotlib
+auto-scales.
 
 
 :::::::::::::::::::::::::::::::::::::::: keypoints

episodes/05-train_eval.md

@@ -121,7 +121,7 @@ for epoch in range(epochs):
     val_losses.append(val_loss)
     val_accs.append(val_acc)
 
-    if val_loss << best best_val_loss:
+    if val_loss < best_val_loss:
         best_val_loss = val_loss
         torch.save(model.state_dict(), 'best_model.pt')
 

learners/setup.md

@@ -33,7 +33,7 @@ in Linux, or [Git Bash][gitbash] on Windows, execute the following command:
 cd ~/Desktop
 mkdir src
 cd src
-uv init ml-xray
+uv init --native-tls ml-xray
 cd ~/Desktop/src/ml-xray
 ```
 
@@ -52,12 +52,14 @@ create your project:
 cd /D %userprofile%\Desktop
 mkdir src
 cd src
-uv init ml-xray
+uv init --native-tls ml-xray
 cd /D %userprofile%\Desktop\src\ml-xray
 ```
 
 :::::::::::::::::::::::::
 
+Note the `--native-tls` option may be necessary in some environments.
+
 ## Download Project Package Dependencies
 
 The major strength of Python is the number of libraries available.