Jupyter Notebooks
Turn an analysis into a reproducible narrative with code cells, markdown explanations, labeled charts, and a clean run order.
By the end, you’ll be able to…
- Create and run notebook cells with a chosen kernel.
- Use markdown to state assumptions and findings.
- Label charts so a reader can interpret them without the code.
- Make a notebook reproducible before sharing it.
01A notebook is a reproducible narrative
A Jupyter notebook combines code cells, markdown cells, and stored outputs. It is useful for exploration because you can run a step, inspect the result, and adjust. The execution order is not necessarily the top-to-bottom order, which is why a notebook can produce results that cannot be reproduced by running all cells.
Choose a kernel that matches the project environment and record the dependency set outside the notebook. A notebook stores outputs, but outputs are evidence of one run, not a guarantee. Before sharing, restart the kernel and run all cells from top to bottom.
py -m pip install jupyterlabpy -m jupyter lab# Create a notebook, select the project kernel, and run cells with Shift+Enter.02Markdown carries the argument
Use headings to separate question, data, method, results, and limitations. State the source of the data and the cleaning rule in prose, not only in code. A reader should be able to follow the reasoning without reverse-engineering every cell.
Markdown supports tables, links, images, and LaTeX mathematics. Put the formula next to the calculation it explains. Avoid a wall of code cells with no commentary; the narrative is what turns a scratchpad into a report another person can review.
# Regional sales review## QuestionWhich region grew fastest between Q1 and Q2?## MethodRevenue is summed from cleaned invoices. Refunds are excluded.The growth rate is (Q2 - Q1) / Q1 for each region.## LimitationRegions with fewer than 20 invoices are marked as low confidence.03Visualize with honest labels
A chart is an argument, not decoration. Label both axes, include units, and choose a baseline that does not exaggerate a difference. A bar chart should normally start at zero; a line chart may use a non-zero baseline when the change is the point, but the decision should be stated.
Remove chart junk that does not help comparison. Use color to encode one variable, not to make the chart busy. Save the figure generation in a cell that can be rerun, and write the output path explicitly. A screenshot pasted into a slide is not a reproducible result.
import matplotlib.pyplot as pltregions = ["North", "South", "East"]revenue = [120, 90, 150]fig, ax = plt.subplots()ax.bar(regions, revenue)ax.set_title("Q2 revenue by region")ax.set_ylabel("Revenue (thousands)")ax.set_ylim(0, 180)fig.savefig("q2_revenue.png", dpi=150, bbox_inches="tight")04Make the notebook reproducible
A reproducible notebook has a clean kernel, a deterministic run order, no hidden local paths, and a recorded dependency set. Use relative paths from the notebook's directory or a project root, and create output directories explicitly. Avoid relying on a cell that was run hours ago and is no longer in the file.
For a shared report, export to HTML or PDF, or convert the stable logic into a module with tests. Use parameterized notebooks for repeated reports and store the parameters with the output. Version control is easier when outputs are cleared and the diff shows only source changes. Run a path check before executing: a fresh directory should report the missing notebook rather than silently producing a report that cannot be reproduced.
The ideas worth keeping.
- A notebook is a narrative, not a guarantee of reproducibility.
- Markdown should state the question, method, result, and limitation.
- Charts need labels, units, and an honest baseline.
Make it yours.
Type and test your code right here in the interactive workspace. Run your solution, check the output, and compare with the worked guide when ready.
Outline an analysis notebook
Write the markdown headings and one sentence for each section of a sales analysis notebook: question, data, method, results, limitations.
Explore a worked solution
# Sales analysis## QuestionWhich region grew fastest from Q1 to Q2?## DataMonthly invoices exported on 2026-10-22; refunds excluded.## MethodSum revenue by region and quarter, then compute (Q2 - Q1) / Q1.## ResultsNorth grew 18%, South 4%, East 22%.## LimitationsSmall regions have fewer than 20 invoices and are marked low confidence.The outline separates the question from the method and the result. Stating limitations next to the result prevents a reader from treating a small sample as a general conclusion.
Label a chart honestly
Create a bar chart for three regions with a zero baseline, a title, and a y-axis label with units. Save it to a file instead of displaying only inline.
Explore a worked solution
import matplotlib.pyplot as pltregions = ["North", "South", "East"]revenue = [120, 90, 150]fig, ax = plt.subplots()ax.bar(regions, revenue)ax.set_title("Q2 revenue by region")ax.set_ylabel("Revenue (thousands)")ax.set_ylim(0, 180)fig.savefig("q2_revenue.png", dpi=150, bbox_inches="tight")The zero baseline makes the bar lengths proportional to the values. The title names the period and metric, and the axis label states the units, so the chart is interpretable without the code.
What stayed with you?
Check the ideas while they’re fresh. Your answers stay in this page and feedback appears as you go.
Outline an analysis notebook
Write the markdown headings and one sentence for each section of a sales analysis notebook: question, data, method, results, limitations.
[Process exited with code 0 - No output]
Keep exploring.
The official references behind this lesson, when you want a second angle or the full details.
One lesson closer.
Reading is a start. Trying it yourself makes the connection.