Update setup: control python version, explicit data folder, instructions for colab, and more

episodes/3-monitor-the-model.md

@@ -72,7 +72,7 @@ into a local folder and load the data using the code below.
 ```python
 import pandas as pd
 
-filename_data = "weather_prediction_dataset_light.csv"
+filename_data = "data/weather_prediction_dataset_light.csv"
 data = pd.read_csv(filename_data)
 data.head()
 ```

episodes/4-advanced-layer-types.md

@@ -35,7 +35,7 @@
 import pathlib
 import numpy as np
 
-DATA_FOLDER = pathlib.Path('data/dataset_dollarstreet/') # change to location where you stored the data
+DATA_FOLDER = pathlib.Path('data/') # change to location where you stored the data
 train_images = np.load(DATA_FOLDER / 'train_images.npy')
 val_images = np.load(DATA_FOLDER / 'test_images.npy')
 train_labels = np.load(DATA_FOLDER / 'train_labels.npy')
@@ -267,7 +267,7 @@
 
 ::: challenge
 ## Number of model parameters
 Suppose we apply a convolutional layer with 100 kernels of size 3 * 3 * 3 (the last dimension applies to the rgb channels) to our images of 32 * 32 * 3 pixels. How many parameters do we have? Assume, for simplicity, that the kernels do not use bias terms. Compare this to the answer of the earlier exercise, ["Number of Parameters"](#parameters-exercise-1).
 
 :::: solution
 ## Solution

episodes/5-transfer-learning.md

@@ -17,7 +17,7 @@
 
 An example: Let's say that you want to train a model to classify images of different dog breeds. You could make use of a pre-trained network that learned how to classify images of dogs and cats. The pre-trained network will not know anything about different dog breeds, but it will have captured some general knowledge of, on a high-level, what dogs look like, and on a low-level all the different features (eyes, ears, paws, fur) that make up an image of a dog. Further training this model on your dog breed dataset is a much easier task than training from scratch, because the model can use the general knowledge captured in the pre-trained network.
 
 ![](episodes/fig/05-transfer_learning.png)
 <!-- 
 Edit this plot using the Mermaid live editor:
 1. Open this link that includes the source code of the chart to open the live editor web interface:
@@ -41,7 +41,7 @@
 import pathlib
 import numpy as np
 
-DATA_FOLDER = pathlib.Path('data/dataset_dollarstreet/') # change to location where you stored the data
+DATA_FOLDER = pathlib.Path('data/') # change to location where you stored the data
 train_images = np.load(DATA_FOLDER / 'train_images.npy')
 val_images = np.load(DATA_FOLDER / 'test_images.npy')
 train_labels = np.load(DATA_FOLDER / 'train_labels.npy')

learners/setup.md

@@ -1,50 +1,96 @@
 ---
 title: Setup
 ---
-## Software Setup
+## Setup
+Please complete the setup at least a day in advance of the workshop. If you run into issues, contact the workshop organizers by email so you're ready to begin on time. The setup steps include: 
 
-::::::::::::::::::::::::::::::::::::::: discussion
+1. Setup workshop folder
+2. Install Python 3.11.9
+3. Setup virtual environment with required packages
+4. Download the data
 
-### Installing Python
+## 1. Setup workshop folder
 
-[Python][python] is a popular language for scientific computing, and a frequent choice
-for machine learning as well.
-To install Python, follow the [Beginner's Guide](https://wiki.python.org/moin/BeginnersGuide/Download) or head straight to the [download page](https://www.python.org/downloads/).
+Create a folder on your desktop called `dl_workshop` for storing the workshop data and required packages.
 
-Please set up your python environment at least a day in advance of the workshop.
-If you encounter problems with the installation procedure, ask your workshop organizers via e-mail for assistance so
-you are ready to go as soon as the workshop begins.
+```shell
+cd ~/Desktop
+mkdir dl_workshop
+cd dl_workshop
+pwd 
+```
 
-:::::::::::::::::::::::::::::::::::::::::::::::::::
+```output
+~/Desktop/dl_workshop
+```
 
-## Installing the required packages{#packages}
+## 2. Installing Python
 
-[Pip](https://pip.pypa.io/en/stable/) is the package management system built into Python.
-Pip should be available in your system once you installed Python successfully.
+[Python][python] is a popular language for scientific computing and a frequent choice for machine learning.
 
-Open a terminal (Mac/Linux) or Command Prompt (Windows) and run the following commands.
+Python version requirement: This workshop requires Python 3.11.9. Newer versions like 3.12 or 3.13 are not yet fully compatible with TensorFlow and may cause issues. Even Python 3.11.9 may have some edge cases, but it works well enough to be the default in Google Colab and is stable for the purposes of this workshop.
 
-1. Create a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments) called `dl_workshop`:
+To install Python 3.11.9, go to the [official 3.11.9 downloads page](https://www.python.org/downloads/release/python-3119//). Choose the installer that matches your operating system (Windows, macOS, or Linux).
 
-::: spoiler
+Please set up your Python environment at least a day in advance of the workshop. If you run into issues with installation, contact the workshop organizers by email so you're ready to begin on time.
 
-### On Linux/macOs
+
+### Determine which `python` command to use for downstream setup steps
+
+Different systems and Python installations (e.g., Anaconda, Git Bash, system Python, Windows Store, etc.) may register different command names. This quick check helps identify which one points to Python 3.11.9 on your machine.
+
+Run the following in your terminal ([Git Bash recommended for Windows users](https://git-scm.com/downloads), Anaconda Prompt, or macOS/Linux shell):
 
 ```shell
-python3 -m venv dl_workshop
+python --version
+py --version
+python3 --version
 ```
 
-:::
+Use whichever one returns Python 3.11.9 for the rest of the setup steps.
 
-::: spoiler
+Example output:
 
-### On Windows
+```output
+$ python --version
+Python 3.11.9
+
+$ py --version
+Python 3.13.2
+
+$ python3 --version
+Python was not found...
+```
+In this case, use python throughout the remainder of the instructions.
+
+If none of the commands return Python 3.11.9:
+
+- Download and install Python 3.11.9. On Windows, be sure to check "Add Python to PATH" during installation
+- If you're on Windows using Anaconda Prompt, try using [Git Bash](https://git-scm.com/downloads) instead.  
+- Then re-run the checks above in a new terminal window
+
+If you're still stuck, ask the workshop organizers for help before proceeding.
+
+## 3. Configure virtual environment
+
+Open a terminal and run the following commands.
+
+1. Create a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments) called `venv` using the "venv" command:
 
 ```shell
-py -m venv dl_workshop
+# Use python3 or py instead if one of them points to 3.11.9.
+python -m venv venv # 1st "venv" is commmand, 2nd venv is name of the virtual environment / folder
 ```
 
-:::
+If you run the `ls` command from `~/Desktop/dl_workshop`, you should see a new `venv` folder inside it
+
+```shell
+ls
+```
+
+```output
+venv/
+```
 
 2. Activate the newly created virtual environment:
 
@@ -53,7 +99,7 @@ py -m venv dl_workshop
 ### On Linux/macOs
 
 ```shell
-source dl_workshop/bin/activate
+source venv/bin/activate
 ```
 
 :::
@@ -63,20 +109,35 @@ source dl_workshop/bin/activate
 ### On Windows
 
 ```shell
-dl_workshop\Scripts\activate
+venv\Scripts\activate
 ```
 
+If you're using Git Bash on Windows, you need to add the source command first.
+
+```shell
+source venv/Scripts/activate
+```
 :::
 
-Remember that you need to activate your environment every time you restart your terminal!
+**Note**: Remember that you need to activate your environment every time you restart your terminal, and before you launch Jupyter Lab!
+
+3. After activating the enviornment, upgrade pip. This is a good practice to follow when you first initialize your virtual environment (beforing installing additional packages). [Pip](https://pip.pypa.io/en/stable/) is the package management system built into Python.Pip should be available in your system once you installed Python successfully.
 
-3. Install the required packages:
+```shell
+ # remember: use python3 or py instead if it points to 3.11.9
+python -m pip install --upgrade pip
+```
+
+4. Install the required packages:
+
+Follow the OS-specific instructions below. NOte that It may take 10-20 minutes to install everything.
 
 ::: spoiler
 
 ### On Linux/macOs
 
 ```shell
+ # Use python or py instead if one of them points to 3.11.9.
 python3 -m pip install jupyter seaborn scikit-learn pandas tensorflow pydot
 ```
 
@@ -90,7 +151,8 @@ However, the installation is currently broken in the most recent version (as of
 ### On Windows
 
 ```shell
-py -m pip install jupyter seaborn scikit-learn pandas tensorflow pydot
+# Use py or python3 instead if one of them points to 3.11.9.
+python -m pip install jupyter seaborn scikit-learn pandas tensorflow pydot 
 ```
 
 :::
@@ -101,51 +163,87 @@ An [optional challenge in episode 2](episodes/2-keras.md) requires installation
 and instructions for doing that can be found
 [by following this link](https://graphviz.org/download/).
 
-## Starting Jupyter Lab
+### Starting Jupyter Lab
 
 We will teach using Python in [Jupyter Lab][jupyter], a programming environment that runs in a web browser.
 Jupyter Lab is compatible with Firefox, Chrome, Safari and Chromium-based browsers.
 Note that Internet Explorer and Edge are *not* supported.
 See the [Jupyter Lab documentation](https://jupyterlab.readthedocs.io/en/latest/getting_started/accessibility.html#compatibility-with-browsers-and-assistive-technology) for an up-to-date list of supported browsers.
 
 To start Jupyter Lab, open a terminal (Mac/Linux) or Command Prompt (Windows), 
-make sure that you activated the virtual environment you created for this course,
+**make sure that you activated the virtual environment you created for this course**,
 and type the command:
 
 ```shell
 jupyter lab
 ```
 
-## Check your setup
+### Check your virtual software setup
 To check whether all packages installed correctly, start a jupyter notebook in jupyter lab as
-explained above. Run the following lines of code:
+explained above (**with virtual environment activated**). Run the following check to verify you have the right version of Python configured.
+```python
+!python --version
+```
+
+If you don't see 3.11.9, make sure your virtual environment was activated prior to launching Jupyter Lab.
+```output
+Python 3.11.9 
+```
+
+Then, run the following lines of code:
 ```python
+import tensorflow
+print('Tensorflow version: ', tensorflow.__version__) # >= 2.12.0
+
 import sklearn
-print('sklearn version: ', sklearn.__version__)
+print('sklearn version: ', sklearn.__version__) # >= 1.2.2
 
 import seaborn
-print('seaborn version: ', seaborn.__version__)
-
+print('seaborn version: ', seaborn.__version__) # any version
+ 
 import pandas
-print('pandas version: ', pandas.__version__)
-
-import tensorflow
-print('Tensorflow version: ', tensorflow.__version__)
+print('pandas version: ', pandas.__version__) # any version 
 ```
 
 This should output the versions of all required packages without giving errors.
 Most versions will work fine with this lesson, but:
+
 - For Keras and Tensorflow, the minimum version is 2.12.0
 - For sklearn, the minimum version is 1.2.2
 
-## Fallback option: cloud environment
+### Fallback option: cloud environment
 If a local installation does not work for you, it is also possible to run this lesson in [Binder Hub](https://mybinder.org/v2/gh/carpentries-incubator/deep-learning-intro/scaffolds). This should give you an environment with all the required software and data to run this lesson, nothing which is saved will be stored, please copy any files you want to keep. Note that if you are the first person to launch this in the last few days it can take several minutes to startup. The second person who loads it should find it loads in under a minute. Instructors who intend to use this option should start it themselves shortly before the workshop begins.
 
 Alternatively you can use [Google colab](https://colab.research.google.com/). If you open a jupyter notebook here, the required packages are already pre-installed. Note that google colab uses jupyter notebook instead of Jupyter Lab.
 
-## Downloading the required datasets
+## 4. Downloading the required datasets
+
+Download the [weather dataset prediction csv][weatherdata] and [Dollar street dataset (4 files in total)][dollar-street]. Create a subfolder in your workshop folder called data, `~/Desktop/dl_workshop/data`, and move all 5 files to the data subfolder:
+
+- `dl_workshop/data/weather_prediction_dataset_light.csv`
+- `dl_workshop/data/train_labels.npy`
+- `dl_workshop/data/test_labels.npy`
+- `dl_workshop/data/train_images.npy`
+- `dl_workshop/data/test_images.npy`
+
+**Note**: If you end up using Google Colab for the workshop, you'll want to create a folder called `dl_workshop` within your Google drive, and then create the same `data` subfolder as above with all 5 files uploaded. **Avoid uploading the `venv` folder to your google drive**; you'll be using Colab's pre-built environment instead, and the `venv` folder contains MANY files from the libraries you installed. 
+
+You can access files from Google drive using Colab and the following code:
+
+```python
+from google.colab import drive
+drive.mount('/content/drive')
+```
+
+A prompt will appear asking you to authorize access to your Google Drive. After authorization, your Drive will be accessible under `/content/drive/My Drive/`. You can use standard Python I/O or libraries like pandas, os, glob, etc. to interact with files. Example below:
+
+```python
+import pandas as pd
+# Load a CSV file from Drive
+df = pd.read_csv('/content/drive/My Drive/dl_workshop/data/weather_prediction_dataset_light.csv')
+```
 
-Download the [weather dataset prediction csv][weatherdata] and [Dollar street dataset (4 files in total)][dollar-street]
+You can use the file navigator (folder icon) within Colab to help navigate your Google drive files.
 
 [dollar-street]: https://zenodo.org/api/records/10970014/files-archive
 [jupyter]: http://jupyter.org/