BMS5010 Chap.7 Building a Notebook You Can Defend
Building a Notebook You Can Defend
The artefact has to survive a conversation
Thirty of the hundred marks are given for standing in front of an assessor and explaining work you are not permitted to edit while you do it, which is more than the mid-term carries. That changes what counts as finishing a task. The working test is not whether a cell produced output; it is whether you can say in one sentence, without scrolling, why that cell is there.
Everything in this chapter follows from that, from how the environment is created to how the markdown sections are written, and none of it is presentation advice.
The environment is the first thing that fails
The course tutorial builds a named environment with a lightweight environment manager, installs packages into it with the package installer, and advises against mixing the two installation routes in one environment.
The package set it names is the one the whole course uses: numerical arrays, dataframes, plotting, scientific computing, the general machine learning library, and the two deep learning frameworks the group project requires. Create the environment once in the first laboratory week, write down its name, and do every piece of coursework inside it.
Most notebooks that fail in front of an assessor fail because they were written in one environment and run in another.
A notebook is three kinds of cell and the marks name all three
The submission instruction is explicit: for each task, a markdown section explaining what the task requires, code cells demonstrating the solution, and results sections showing the analysis and the visualisation.
That is the structure an assessor reads down while you talk, so a notebook that is one wall of code forces them to find your answer for you inside a hard time limit.
The markdown sections do double duty, because the sentences you write there are the sentences you say aloud, which makes writing them the cheapest preparation available for the demonstration.
The criteria are a checklist, and every item is checkable in advance
Twenty-five marks split fifteen for the code and ten for the demonstration. Submission after the deadline on the course site scores nothing.
The code must cover every specified task, with a mark lost for each one missing. The notebook must run during the demonstration, and an error while it executes costs two marks. Attendance in person with a student card is a condition of scoring at all. The version used is the one downloaded in advance and no changes to it are permitted.
The work must be presented in English, every task explained, and two questions chosen on the spot each earn a mark.
Five minutes, then two for questions, and anything past the limit is cut off.
Three failures that only appear on someone else's machine
A path that exists only on your computer is the commonest, and it is repaired by loading data from the library that ships it or by placing the file beside the notebook and using a relative path.
A package installed in your environment and not in theirs is the second, repaired by keeping to the packages the course names. Hidden state is the third and the most insidious: a cell depending on a name created in a cell you later deleted or moved, so the notebook has never actually run in the order it is now saved in.
None of the three can be repaired in the room, and all three are prevented by restarting and running everything from a clean state before you submit.
The group project asks the same question of five people
Projects apply models to a real health science problem, either from the published topic list or from your own research, in groups of five, implemented in one of the two named deep learning frameworks.
The published topics each come paired with a named open dataset, which is the practical reason to prefer one: the data access problem is already solved. Fifty marks split twenty for the demonstration and five for the peer assessment, both individual, and fifteen for the code and ten for the report, both shared.
The archive submitted for the code mark has to contain everything needed to reproduce the results in the report, including the input data, and the assessors check that it runs.
What this chapter covers
- 01
Why the demonstration changes what counts as finishing a task
- 02
A named environment, one package set, and the reason not to mix installers
- 03
Markdown, code and results sections as the structure the marks name
- 04
The four published ways to lose marks, none of them about analysis quality
- 05
Paths, packages and hidden state, and the one habit that prevents all three
- 06
The group project topics, their paired open datasets, and the mark split
- 07
The reproducible archive, the report limits and the contribution statement
Diagnose a notebook that runs for you and fails for the assessor
- 3Name the three causes in order of likelihood.
- 3Give the repair for each one.
- 2Say which can be fixed in the room, and why.
Key terms
- Virtual Environment
- An isolated Python installation with its own package set, created once for the course so that code written in it runs the same way wherever it is opened.
- Markdown Cell
- A notebook cell holding formatted text rather than code, used here to state what each task requires before the code that answers it.
- Hidden State
- A notebook that only runs because of names created by cells since deleted or moved, so it has never executed in the order it is saved in.
- Reproducible Archive
- A submitted bundle containing the data, notebooks and scripts needed to regenerate every result a report claims, checked by running it.
- Contribution Statement
- A written record of which group member did which subtask, submitted individually alongside peer marks and a short justification for each.
Building a Notebook You Can Defend FAQ
What should I actually say in the first thirty seconds of a demonstration?
Name the task, the data and the decision, then say what your result is. Something like: this task predicts a continuous outcome from six routine measurements, I compared four linear estimators on one split, and the penalised fit generalised best by this margin. That sentence orients the assessor immediately and buys you the remaining four minutes to show rather than explain.
Starting instead by scrolling through imports spends the most valuable part of a five-minute slot on the least valuable part of the notebook.
How should a group divide the project so the individual marks are fair?
Divide by stage rather than by document, and record it as you go. The demonstration and the peer assessment are marked individually while the code and report are shared, so a member who writes no code can still present strongly and a member who writes all of it can still present badly.
The contribution statement asks for every subtask and who did it, and your own peer mark is the average of what your group mates submit, so a running list kept from the first week turns that document into an hour's work instead of an argument.
What has to be true of the archive we submit for the code mark?
It has to contain the input data, the notebooks and any scripts, and running them has to reproduce every result the report claims without errors. The cheapest way to find out whether it does is to have the member who wrote least of the code unpack it on a clean machine and run it, because they will hit every assumption the authors cannot see.
Do this about a week before the deadline; the repairs are usually paths and missing files rather than analysis, but they reliably take longer than one evening.
Assessment move
Once a week, restart your notebook and run it end to end while timing yourself explaining it aloud. The run finds the paths, the packages and the hidden state; the talking finds the cells you cannot justify. Both failures are cheap to repair in week four and impossible to repair in week eleven, which is the whole argument for doing it early.
Working through Building a Notebook You Can Defend in BMS5010? Sia is AskSia’s AI Artificial Intelligence tutor — ask any BMS5010 Building a Notebook You Can Defend question and get a clear, step-by-step explanation grounded in how BMS5010 is taught and assessed. Read this chapter free, then take your hardest questions to Sia.
