Machine Learning Foundations - Reproducible ML Notebook Checklist

Status: Draft standard Applies to: worked notebooks, practice notebooks, reference solutions, and downloadable fallback notebooks

Purpose

A learner should be able to open a notebook, restart the kernel, run all cells in order, and get the same kind of result without guessing what happened earlier.

Required notebook header

Every notebook should begin with a short markdown cell that states:

• course and module;
• notebook purpose;
• expected active time;
• dataset file used;
• whether the notebook is worked, practice, or reference;
• required packages; and
• privacy note that only supplied fictional or synthetic data is used.

Required setup cell

Every notebook should define:

from pathlib import Path

RANDOM_SEED = 42
DATA_DIR = Path("data")

Add package imports in the same setup section. Do not import packages inside later cells unless the lesson is specifically about imports.

Data loading

Data loading must:

• use relative paths;
• read from the supplied course data folder;
• fail clearly if the file is missing;
• keep source data unchanged; and
• show the first few rows and shape after loading.

Randomness

Use RANDOM_SEED for:

• train/test split;
• shuffled cross-validation;
• stochastic models;
• synthetic-data generation; and
• sampled examples.

If randomness is intentionally not fixed, explain why.

Splits and leakage

For supervised learning notebooks:

• define the target column before the split;
• create X and y explicitly;
• split before fitting preprocessing or models;
• keep test rows unseen until evaluation;
• check that target and future-information columns are not in X; and
• state whether the split is random, stratified, grouped, or time-based.

Outputs

Each notebook must include:

• one small result table for key metrics or summaries;
• one written interpretation;
• one limitation note;
• visible self-checks where useful; and
• no hidden dependency on previous manual edits.

Clean rerun checklist

Before a notebook is accepted, run:

1. Restart kernel.
2. Clear outputs if needed.
3. Run all cells from top to bottom.
4. Confirm no cell requires manual state from an earlier failed run.
5. Confirm expected files are present.
6. Confirm plots and tables render.
7. Confirm final self-checks pass.
8. Confirm the notebook can be downloaded and reopened.

Version record

Each module or notebook pack should record:

• Python version;
• NumPy version;
• pandas version;
• scikit-learn version;
• Matplotlib version;
• notebook runtime name; and
• date of the last clean rerun.

Use the course runtime lock as the authority for publication.

File-writing rule

Learner notebooks may write only to an outputs/ folder inside the course workspace. They must not overwrite raw data files.

Acceptance rule

A notebook is reproducible enough for draft acceptance when it can be cleanly rerun in the browser runtime and in the downloadable fallback environment, with the same conclusions and no manual repair steps.