Follow the transformation
Restart/run the analysis from a clean state.
Identify the decision question and strongest supporting evidence.
Move reusable data preparation/calculation into functions or scripts where appropriate.
Reporting & Reproducibility · Lesson 82
From Notebook to Report
A notebook records exploratory code and intermediate output; a report is a curated argument for a reader.
From Notebook to Report
A notebook records exploratory code and intermediate output; a report is a curated argument for a reader. Moving from one to the other means selecting only evidence that answers the question, verifying calculations in a reproducible run, ordering results logically and separating findings from methods/diagnostics that do not belong in the main narrative.
Learning goal: explain why From Notebook to Report behaves this way, apply it to a small example, and verify the result independently. Begin by being able to justify this first step: Restart/run the analysis from a clean state.
Deeper walkthrough
Read From Notebook to Report as a mechanism, not a recipe
Treat this as a sequence of observable decisions rather than one opaque command. Stage 1: Restart/run the analysis from a clean state. Stage 2: Identify the decision question and strongest supporting evidence. Stage 3: Move reusable data preparation/calculation into functions or scripts where appropriate. Final checkpoint: Write interpretation, uncertainty and limitations in reader-oriented language.
Know what would convince you
- Recompute one result from a handful of source rows or an independent formula.
- Check row counts, group totals and units before interpreting differences.
Useful distinctionDefinition: The exact metric/selection/comparison being computed.
Click a stage to inspect what happens, what changes, and what should be checked before moving on.
Stage 1
Restart/run the analysis from a clean…
Restart/run the analysis from a clean state. For From Notebook to Report, identify the exact state before this stage, the operation or rule applied here, and the observable state afterwards so the mechanism remains inspectable.
State focus: identify exactly what changed at this stage and what observable evidence confirms that change.
Trace the mechanism step by step
- Restart/run the analysis from a clean state.
- Identify the decision question and strongest supporting evidence.
- Move reusable data preparation/calculation into functions or scripts where appropriate.
- Choose final tables/plots with consistent definitions.
- Write interpretation, uncertainty and limitations in reader-oriented language.
Curation step
Notebook: 25 exploratory cells and 12 plots
Report: 1 method summary + 3 validated findings + 2 decision-relevant figuresExpected / illustrative result
The report is not a screenshot of exploration; it is a reproducible selection of evidence.
Interpret the result.
For From Notebook to Report, identify exactly what each reported quantity represents, including its units/denominator, and independently recompute one part of the result.
Place the concept correctly
DefinitionThe exact metric/selection/comparison being computed.EvidenceTable, formula or visual that answers the question.AuditIndependent count/total/rule check that can reveal an error.When it is appropriate
Use From Notebook to Report when it answers a defined question in Reporting & Reproducibility and its inputs/assumptions match the current data or program state.
When to stop or reconsider
Reconsider From Notebook to Report when the required information is unavailable, the operation would violate a validation/data boundary, or a simpler operation answers the question more transparently.
Failure modes to recognise
- Changing the population/grain without noticing it.
- Using an undefined denominator, time window, unit or category rule.
- Presenting a number/plot without reconciling it to source counts or totals.
How to check the result
- Recompute one result from a handful of source rows or an independent formula.
- Check row counts, group totals and units before interpreting differences.
- Change one source value and predict which reported value/mark should change.
Demonstrate understanding
Try this:
Construct a tiny example of From Notebook to Report. First restart/run the analysis from a clean state. Then identify the decision question and strongest supporting evidence. Predict the result before execution and explain one boundary or failure case.
Use a very small example and calculate one quantity manually. Separate sample evidence from population/causal claims.
Check reasoning, not memorisation
Which approach best demonstrates understanding of From Notebook to Report?
Remember the logic
Step 1Restart/run the analysis from a clean state.Step 2Identify the decision question and strongest supporting evidence.Step 3Move reusable data preparation/calculation into functions or scripts where appropriate.Step 4Choose final tables/plots with consistent definitions.What to remember
- A notebook records exploratory code and intermediate output; a report is a curated argument for a reader. Moving from one to the other means selecting only evidence that answers the question, verifying calculations in a reproducible run, ordering results logically and separating findings from methods/diagnostics that do not belong in the main narrative.
- Restart/run the analysis from a clean state.
- Changing the population/grain without noticing it.
- Recompute one result from a handful of source rows or an independent formula.