Hands-on lab — Day 129: Statistical Plots with seaborn

"""Shared fixtures and headless matplotlib setup.

pytest finds this file by itself -- nothing imports it. `matplotlib.use`
must run before `pyplot` is imported anywhere, which is why it happens
here, first, before the `data` import below pulls in pandas (and,
transitively, nothing that touches matplotlib yet). Every fixture returns
a FRESH copy of its table so one test's accidental mutation can never
leak into the next test, and every test that opens a Figure is
responsible for `plt.close()`-ing it -- `_close_all_figures` below is a
backstop, not a substitute.
"""

import matplotlib

matplotlib.use("Agg")

import matplotlib.pyplot as plt
import pytest

from data import build_long_revenue, build_team_scores, build_wide_revenue


@pytest.fixture
def team_scores():
    return build_team_scores()


@pytest.fixture
def wide_revenue():
    return build_wide_revenue()


@pytest.fixture
def long_revenue():
    return build_long_revenue()


@pytest.fixture(autouse=True)
def _close_all_figures():
    yield
    plt.close("all")

"""The tables every exercise in this lab is built from.

Nothing here is randomised or loaded from a file -- every table is a small
literal so a reader can check every asserted number by eye against the
source. Two tables carry the whole lab:

`team_scores` -- exercises 2, 3, 4, 7 and 9. Four teams, four observations
each. Team B's four scores are 90, 88, 92, 10 -- three of the four highest
scores in the entire dataset, dragged down by one bad observation to a
group mean (70.0) lower than team A's (79.0), whose four scores are all
unremarkable and close together. This is the lab's through-line: a bar
chart of the mean tells you B did worse than A. A strip chart of the same
four points each shows the opposite story.

`wide_revenue` / its melted form `long_revenue` -- exercises 1, 5 and 6.
One row per region in wide form (a `q1`..`q4` column each); one row per
region-quarter observation in long form, produced with the exact `melt`
call Day 124 taught.
"""

from __future__ import annotations

import pandas as pd

# --------------------------------------------------------------------------
# `team_scores` -- the barplot trap. Four teams, four observations each.
#
# Team A: 78, 82, 80, 76 -- mean 79.0, all four values close together.
# Team B: 90, 88, 92, 10 -- mean 70.0, but three of four are the highest
#          individual scores in the whole table; one outlier (10) drags
#          the mean below team A's despite B's typical performance being
#          the best in the dataset.
# Team C: 65, 70, 68, 67 -- mean 67.5.
# Team D: 55, 60, 58, 57 -- mean 57.5.
# --------------------------------------------------------------------------


def build_team_scores() -> pd.DataFrame:
    return pd.DataFrame(
        {
            "team": ["A", "A", "A", "A", "B", "B", "B", "B", "C", "C", "C", "C", "D", "D", "D", "D"],
            "score": [78, 82, 80, 76, 90, 88, 92, 10, 65, 70, 68, 67, 55, 60, 58, 57],
        }
    )


# --------------------------------------------------------------------------
# `wide_revenue` -- exercises 1, 5 and 6. One row per region, one column
# per quarter. `melt` (Day 124) turns this into `long_revenue`: one row
# per (region, quarter) observation, which is what lets `hue="region"`
# and `col="region"` work at all.
# --------------------------------------------------------------------------


def build_wide_revenue() -> pd.DataFrame:
    return pd.DataFrame(
        {
            "region": ["North", "South", "East", "West", "Central"],
            "q1": [120, 95, 110, 130, 88],
            "q2": [125, 98, 108, 128, 90],
            "q3": [130, 101, 115, 135, 95],
            "q4": [128, 105, 118, 140, 97],
        }
    )


def build_long_revenue() -> pd.DataFrame:
    return build_wide_revenue().melt(id_vars="region", var_name="quarter", value_name="revenue")

"""The worked reference suite for Day 129 -- "Plots That Say What They
Computed".

Nine exercises, each proving one real seaborn 0.13.2 / matplotlib 3.11.1
behaviour by drawing a real plot and reading real return types, artist
state, or numeric values -- never by reading source. Run it:

    pytest examples

Every table these tests use comes from `data.py`, imported through the
fixtures in `conftest.py`. Read `starter/00_brief.md` for the exercise-by-
exercise explanation; this file is the answer key.
"""

import matplotlib
import matplotlib.pyplot as plt
import pandas as pd
import pytest
import seaborn as sns

# --------------------------------------------------------------------------
# Exercise 1 -- axes-level versus figure-level. `scatterplot` draws into
# an Axes you already own and returns that Axes; `relplot` creates and
# owns its own Figure and returns a FacetGrid wrapping it.
# --------------------------------------------------------------------------


def test_1_axes_level_function_returns_the_axes_you_gave_it(team_scores):
    fig, ax = plt.subplots()
    result = sns.scatterplot(data=team_scores, x="team", y="score", ax=ax)
    assert isinstance(result, matplotlib.axes.Axes)
    assert result is ax  # drew into the Axes it was handed, nothing new


def test_1_figure_level_function_returns_a_facetgrid_owning_its_own_figure(team_scores):
    grid = sns.relplot(data=team_scores, x="team", y="score")
    assert isinstance(grid, sns.axisgrid.FacetGrid)
    assert isinstance(grid.figure, matplotlib.figure.Figure)
    # relplot never took an ax= argument here -- the Figure it owns is
    # its own, not one the caller created and handed in.
    assert grid.ax is not None
    assert grid.ax.figure is grid.figure


# --------------------------------------------------------------------------
# Exercise 2 -- the barplot trap. team_scores' four groups: A and B have
# almost the same shape of data (four values), but B's are 90, 88, 92, 10
# -- three of the four best scores in the whole table, with one outlier.
# The bar heights are the group MEANS, not any raw value; a stripplot of
# the same column exposes the four real points per group.
# --------------------------------------------------------------------------


def test_2_bar_heights_are_group_means_not_raw_values(team_scores):
    fig, ax = plt.subplots()
    sns.barplot(data=team_scores, x="team", y="score", ax=ax)
    heights = {round(float(bar.get_height()), 4) for bar in ax.patches}

    expected_means = team_scores.groupby("team")["score"].mean()
    assert set(round(float(m), 4) for m in expected_means) == heights
    assert heights == {79.0, 70.0, 67.5, 57.5}

    # For every team, its own bar height is a computed mean, not one of
    # its own four raw observations -- the chart draws a statistic, not
    # a value anyone actually recorded.
    for team, group in team_scores.groupby("team"):
        mean = round(float(group["score"].mean()), 4)
        raw_values_for_team = set(group["score"])
        assert mean not in raw_values_for_team


def test_2_team_b_bar_is_lower_than_team_a_despite_having_the_best_scores(team_scores):
    means = team_scores.groupby("team")["score"].mean()
    assert means["B"] < means["A"]

    # But three of team B's four raw scores exceed every one of team A's.
    b_scores = team_scores.loc[team_scores["team"] == "B", "score"]
    a_scores = team_scores.loc[team_scores["team"] == "A", "score"]
    b_above_all_of_a = (b_scores.values[:, None] > a_scores.values[None, :]).all(axis=1)
    assert b_above_all_of_a.sum() == 3  # 90, 88 and 92 all beat every A score; only 10 does not


def test_2_stripplot_of_the_same_column_shows_all_four_raw_points_per_group(team_scores):
    fig, ax = plt.subplots()
    sns.stripplot(data=team_scores, x="team", y="score", ax=ax)
    # One PathCollection per category; each collection's offsets are the
    # real per-point (x, y) locations stripplot drew -- there is no
    # aggregation step to hide anything behind.
    assert len(ax.collections) == 4
    all_y = sorted(float(y) for coll in ax.collections for (_, y) in coll.get_offsets())
    assert all_y == sorted(float(v) for v in team_scores["score"])  # every raw value present, none averaged


# --------------------------------------------------------------------------
# Exercise 3 -- bootstrap randomness. The default error bar is a
# bootstrapped 95% confidence interval, and a bootstrap is a random
# resampling procedure: two unseeded calls give slightly different
# extents; fixing seed= makes them identical.
# --------------------------------------------------------------------------


def _barplot_errorbar_extents(team_scores, **kwargs):
    fig, ax = plt.subplots()
    sns.barplot(data=team_scores, x="team", y="score", ax=ax, **kwargs)
    return [(float(min(line.get_ydata())), float(max(line.get_ydata()))) for line in ax.lines]


def test_3_unseeded_bootstrap_intervals_differ_between_two_runs(team_scores):
    # A bootstrap over a tiny sample (4 observations per group) draws
    # from a small, discrete space of possible resamples, so any SINGLE
    # pair of unseeded runs can occasionally land on the same extent by
    # chance -- that is a real property of resampling a small sample,
    # not a flaw in the claim. Six independent draws makes the claim
    # itself robust: the probability that all six happen to coincide is
    # negligible, while any two of them differing is still exactly the
    # fact this exercise is about.
    runs = [_barplot_errorbar_extents(team_scores) for _ in range(6)]
    distinct_runs = {tuple(run) for run in runs}
    assert len(distinct_runs) > 1


def test_3_seeded_bootstrap_intervals_are_identical_between_two_runs(team_scores):
    run_1 = _barplot_errorbar_extents(team_scores, seed=42)
    run_2 = _barplot_errorbar_extents(team_scores, seed=42)
    assert run_1 == run_2


# --------------------------------------------------------------------------
# Exercise 4 -- errorbar= options. 'sd' draws +/- one standard deviation;
# ('ci', 95) draws a bootstrapped 95% confidence interval. On the same
# data these are different statistics and must produce different extents.
# --------------------------------------------------------------------------


def test_4_sd_and_ci95_error_bars_have_different_extents(team_scores):
    sd_extents = _barplot_errorbar_extents(team_scores, errorbar="sd", seed=42)
    ci_extents = _barplot_errorbar_extents(team_scores, errorbar=("ci", 95), seed=42)
    assert sd_extents != ci_extents

    # Team A specifically: 'sd' is a fixed, deterministic computation
    # (does not depend on the seed at all) while ('ci', 95) is bootstrapped.
    sd_width = sd_extents[0][1] - sd_extents[0][0]
    ci_width = ci_extents[0][1] - ci_extents[0][0]
    assert round(sd_width, 2) != round(ci_width, 2)


def test_4_sd_error_bar_does_not_depend_on_the_seed(team_scores):
    # 'sd' is a closed-form statistic, not a resampling procedure, so it
    # is identical regardless of seed -- unlike the bootstrapped options.
    run_1 = _barplot_errorbar_extents(team_scores, errorbar="sd", seed=1)
    run_2 = _barplot_errorbar_extents(team_scores, errorbar="sd", seed=2)
    assert run_1 == run_2


# --------------------------------------------------------------------------
# Exercise 5 -- long versus wide. seaborn's semantic mappings read column
# NAMES; a wide frame has no "quarter" or "revenue" column to name, so
# asking for one raises. The long form melt (Day 124) produces has both.
# --------------------------------------------------------------------------


def test_5_wide_frame_raises_when_asked_for_columns_it_does_not_have(wide_revenue):
    with pytest.raises(ValueError, match="quarter"):
        sns.lineplot(data=wide_revenue, x="quarter", y="revenue", hue="region")


def test_5_melted_long_form_has_the_columns_hue_needs_and_plots_successfully(wide_revenue, long_revenue):
    # The exact melt call Day 124 taught: one id column, the rest become
    # a variable/value pair.
    reconstructed = wide_revenue.melt(id_vars="region", var_name="quarter", value_name="revenue")
    pd.testing.assert_frame_equal(reconstructed, long_revenue)

    assert list(long_revenue.columns) == ["region", "quarter", "revenue"]
    assert long_revenue.shape == (20, 3)  # 5 regions * 4 quarters

    ax = sns.lineplot(data=long_revenue, x="quarter", y="revenue", hue="region")
    assert isinstance(ax, matplotlib.axes.Axes)
    _, legend_labels = ax.get_legend_handles_labels()
    assert set(legend_labels) == set(long_revenue["region"].unique())  # one legend entry per region


# --------------------------------------------------------------------------
# Exercise 6 -- faceting. col= produces exactly one Axes per category;
# col_wrap reshapes the grid without changing how many Axes exist.
# --------------------------------------------------------------------------


def test_6_col_produces_exactly_one_axes_per_category(long_revenue):
    n_regions = long_revenue["region"].nunique()
    assert n_regions == 5

    grid = sns.catplot(data=long_revenue, x="quarter", y="revenue", col="region", kind="bar")
    assert len(grid.axes.flat) == n_regions
    assert grid._nrow == 1
    assert grid._ncol == n_regions


def test_6_col_wrap_changes_the_grid_shape_not_the_axes_count(long_revenue):
    n_regions = long_revenue["region"].nunique()

    wrapped = sns.catplot(data=long_revenue, x="quarter", y="revenue", col="region", kind="bar", col_wrap=3)
    assert len(wrapped.axes.flat) == n_regions  # still 5 Axes total
    assert wrapped._ncol == 3  # but now arranged 3 wide
    assert wrapped._nrow == 2  # and 2 rows tall (ceil(5 / 3))


# --------------------------------------------------------------------------
# Exercise 7 -- the escape hatch. seaborn draws with matplotlib underneath,
# so a label set with the Day 128 object API after a seaborn call sticks.
# --------------------------------------------------------------------------


def test_7_a_label_set_after_a_seaborn_call_is_present_on_the_axes(team_scores):
    fig, ax = plt.subplots()
    sns.boxplot(data=team_scores, x="team", y="score", ax=ax)
    assert ax.get_ylabel() == "score"  # seaborn's own default label, from the column name

    ax.set_ylabel("Score (0-100 scale)")
    ax.set_ylim(0, 100)
    assert ax.get_ylabel() == "Score (0-100 scale)"
    assert ax.get_ylim() == (0.0, 100.0)


# --------------------------------------------------------------------------
# Exercise 8 -- theme side effects. set_theme() mutates matplotlib's
# global rcParams; every plot drawn afterwards, seaborn or not, inherits
# the change until it is explicitly reset.
# --------------------------------------------------------------------------


def test_8_set_theme_changes_specific_rcparams_and_is_reversible():
    watched_keys = [
        "axes.facecolor",
        "axes.grid",
        "axes.edgecolor",
        "grid.color",
        "axes.axisbelow",
        "xtick.bottom",
        "ytick.left",
    ]
    before = {key: matplotlib.rcParams[key] for key in watched_keys}

    sns.set_theme()
    after = {key: matplotlib.rcParams[key] for key in watched_keys}
    changed_keys = {key for key in watched_keys if before[key] != after[key]}

    # Every one of these seven keys changed on this run; report exactly
    # which if that ever narrows on a different seaborn version.
    assert changed_keys == set(watched_keys)
    assert after["axes.facecolor"] == "#EAEAF2"
    assert after["axes.grid"] is True

    matplotlib.rcParams.update(before)
    restored = {key: matplotlib.rcParams[key] for key in watched_keys}
    assert restored == before  # matplotlib is back exactly where it started


# --------------------------------------------------------------------------
# Exercise 9 -- overlay. A boxplot's box artists are matplotlib patches;
# a stripplot's points are a separate PathCollection per category. Both
# can share one Axes, which is the honest form for a small sample.
# --------------------------------------------------------------------------


def test_9_boxplot_with_stripplot_overlaid_carries_both_kinds_of_artist(team_scores):
    fig, ax = plt.subplots()
    sns.boxplot(data=team_scores, x="team", y="score", ax=ax)
    assert len(ax.patches) == 4  # one box per team
    assert len(ax.collections) == 0  # nothing point-based yet

    sns.stripplot(data=team_scores, x="team", y="score", ax=ax, color="black")
    assert len(ax.patches) == 4  # the box patches are still there, untouched
    assert len(ax.collections) == 4  # one point collection per team, added on top

    n_points_drawn = sum(len(coll.get_offsets()) for coll in ax.collections)
    assert n_points_drawn == len(team_scores)  # every one of the 16 raw points is visible somewhere

lesson_id: D129
day: 129
kind: guided-build
languages: [python, bash]
setup_commands:
  - cd labs/sections/math-statistics-and-data/day-129-statistical-plots-with-seaborn
  - python3 -m venv .venv
  - .venv/bin/pip install -r requirements/requirements.txt
  - .venv/bin/python3 -c "import seaborn; print(seaborn.__version__)"
run_commands:
  - .venv/bin/pytest examples
  - .venv/bin/pytest starter
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - "find . -path ./.venv -prune -o -type d -name '__pycache__' -print -exec rm -rf -- {} +"
  - rm -rf .pytest_cache
  - 'rm -rf .venv  # optional: removes the lab virtual environment'
  - 'git checkout -- starter/  # optional: reset your work'
requires_network: true
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-20'
executed_on: 'macOS 26.5.2 (Apple Silicon, arm64), Python 3.14.0, seaborn 0.13.2, matplotlib 3.11.1, pandas 3.0.5, numpy 2.5.2, pytest 9.1.1, bash 3.2.57 -- bash tests/run_tests.sh -> 17 checks, 0 failure(s), exit 0. pytest examples -> 16 passed (2 warnings). pytest starter -> 16 skipped (untouched checkout). Section 5 of the harness solves every exercise in a scratch copy (16 passed), deliberately breaks exercise 2''s exact bar-heights assertion ({79.0, 70.0, 67.5, 57.5} -> {1.0, 2.0, 3.0, 4.0}), confirms the run exits non-zero with a printed FAIL, restores the file, and confirms 16 passed again -- so the suite is demonstrated to be capable of failing rather than merely claimed to be. Section 4 confirms directly that `pytest examples starter` in one invocation aborts collection with `import file mismatch` (both directories define a module named test_seaborn.py) rather than silently letting one shadow the other. Section 6 draws one real barplot, saves it headless via the Agg backend to a temporary directory, confirms the PNG file exists and is non-empty, then removes the temporary directory and confirms no image file (png/svg/jpg/pdf) is left anywhere inside the lab. Everything was run through a real lab-local .venv created by the documented setup commands. Two honesty notes from this run. FIRST: seaborn 0.13.2''s internal boxplot call passes the matplotlib-deprecated `vert` keyword to `ax.bxp()`, so both `pytest examples` and the harness print a `MatplotlibDeprecationWarning` on matplotlib 3.11.1; every test still passes, and the warning is captured verbatim in expected-output rather than filtered out. SECOND: exercise 3''s unseeded bootstrap runs are, by construction, not reproducible byte-for-byte between invocations, and with only four observations per group a bootstrap resamples from a small enough discrete space that any single PAIR of unseeded runs can occasionally coincide by chance -- an early version of this test compared exactly two runs and was observed to fail intermittently for exactly that reason during authoring, so the reference test now draws six independent unseeded runs and asserts they are not all identical, which is reliable in practice; expected-output/FIELDS.md documents this explicitly. The seeded half of the same exercise (seed=42 used twice) is exact and reproducible on this pin set. plotnine, Altair and Vega-Lite are not installed in this environment; the lesson''s Tools section describes them from public documentation only, and no output attributed to any of them is reproduced anywhere in this lab or its lesson.'

# What is installed, why, and what it costs

Five packages, all free and open source, installed into a lab-local
virtual environment that `rm -rf .venv` completely undoes.

| Package | Version pinned | Licence | What this lab uses it for |
| --- | --- | --- | --- |
| `seaborn` | 0.13.2 | BSD 3-Clause | Every plotting call in this lab — `barplot`, `stripplot`, `boxplot`, `lineplot`, `catplot`, `relplot`, `set_theme`. |
| `matplotlib` | 3.11.1 | PSF-derived (BSD-style) | seaborn's drawing engine; every assertion reads matplotlib `Axes`, `Figure`, `Patch` and `Line2D` objects directly. |
| `pandas` | 3.0.5 | BSD 3-Clause | `team_scores`, `wide_revenue` and `long_revenue`; the `melt` call in exercise 5, continuing directly from Day 124. |
| `numpy` | 2.5.2 | BSD 3-Clause | Pulled in transitively by pandas and matplotlib; not called directly by this lab's own code. |
| `pytest` | 9.1.1 | MIT | The test harness every exercise is written against. |

There is no paid tier of anything in this lab, no account, no key and no
signup, personally or commercially.

## The one time the network is needed

```bash
.venv/bin/pip install -r requirements/requirements.txt
```

That is the only command in the lab that opens a connection. Every
script and test after that runs completely offline, headless, via
`matplotlib.use("Agg")`.

## What is deliberately *not* pinned here

`pyarrow` is not installed for this lab. Day 124's merge/reshape lab
pinned it for parity with the pandas-dtype days it built on; this lab's
three tables are plain `int64`/`object` columns with no Arrow-backed
dtype anywhere, and a `pip install --dry-run` of `seaborn==0.13.2`
against this lab's other pins does not pull `pyarrow` in as a
dependency, so it is left out rather than added for no reason.

`plotnine` and the Vega-Lite/Altair ecosystem, both discussed in the
lesson's Tools section, are **not installed**. Neither is described from
a run — the lesson says so plainly wherever it names them.

## If you cannot install anything at all

seaborn is not in the Python standard library, and there is no reduced
path through this lab without it. If seaborn genuinely cannot be
installed, read the lesson's captured output and this lab's
`expected-output/` directory instead; every number there came from a
real run and is not invented.

seaborn==0.13.2
matplotlib==3.11.1
pandas==3.0.5
numpy==2.5.2
pytest==9.1.1

# Day 129 lab — the brief

Nine exercises, sixteen tests, in order. Work top to bottom in
`test_seaborn.py`. Every table comes from a fixture defined in
`conftest.py` (`team_scores`, `wide_revenue`, `long_revenue`) — read
`data.py` once to see exactly what each one contains before you start.

Check yourself at any point:

```bash
.venv/bin/pytest starter -v
```

On an untouched checkout that prints `16 skipped`. A **skip** means "not
attempted". Replace a `pytest.skip(...)` line with real assertions and
delete it — when every skip is gone and the suite is green, you are
finished:

```bash
.venv/bin/pytest starter -q
echo $?
```

Assert on returned objects and artist state, not on what a plot *looks*
like. seaborn draws with matplotlib underneath, so every fact this lab
cares about — a return type, a bar's height, an error bar's extent, how
many `Axes` a facet grid produced, which `rcParams` changed — is readable
straight off the objects seaborn hands back, with no image comparison
anywhere.

---

## Exercise 1 — return types (`team_scores`)

`sns.scatterplot(data=..., x=..., y=..., ax=ax)` draws into the `Axes`
you hand it and returns that same `Axes` — assert `result is ax`.
`sns.relplot(data=..., x=..., y=...)`, called with **no** `ax=`, creates
its own `Figure` and returns a `seaborn.axisgrid.FacetGrid` wrapping it.
Assert the return type of each, and that the `FacetGrid`'s `.figure` is a
real `matplotlib.figure.Figure` that its own `.ax` belongs to.

## Exercise 2 — the barplot trap (`team_scores`)

Draw `sns.barplot(data=team_scores, x="team", y="score", ax=ax)`. Read
each bar's height from `ax.patches` (`bar.get_height()`) and compare it
to `team_scores.groupby("team")["score"].mean()` — they must match
exactly. Then, for each team, assert that team's bar height is **not**
one of that team's own four raw scores. Separately: team A's mean is
*higher* than team B's, even though three of team B's four raw scores
beat every one of team A's — compute that comparison directly from the
raw values, not from the bar heights. Finally, draw
`sns.stripplot(data=team_scores, x="team", y="score", ax=ax)` and read
every point back out of `ax.collections[i].get_offsets()`; assert the
full set of y-values recovered equals the full set of raw scores — the
strip chart hides nothing the bar chart hid.

## Exercise 3 — bootstrap randomness (`team_scores`)

`sns.barplot`'s default error bar is a **bootstrapped** 95% confidence
interval — a random resampling procedure. Draw the same barplot **six**
times with no `seed=` argument, read each run's line extents from
`ax.lines`, and assert that not all six runs are identical (collect them
into a set and assert its length is more than 1). Six draws, not two —
with only four observations per group, a bootstrap resamples from a
small, discrete space, and any single pair of runs can coincidentally
land on the same extent by chance; six independent draws makes the claim
itself reliable to test. Then draw it twice more with the *same*
explicit `seed=` value both times and assert those two extents match
exactly. This is the day's sharpest measured fact: the same call, the
same data, different pictures — unless you pin the seed.

## Exercise 4 — `errorbar=` options (`team_scores`)

Compare `errorbar='sd'` (one standard deviation, a closed-form
statistic) against `errorbar=('ci', 95)` (a bootstrapped interval) on the
same data, same seed. Assert their extents differ. Then draw `'sd'` with
two *different* seed values and assert the extents are identical either
way — `'sd'` does not resample, so a seed cannot change it.

## Exercise 5 — long versus wide (`wide_revenue`, `long_revenue`)

`wide_revenue` has one row per region and a `q1`..`q4` column each.
Asking `sns.lineplot` for `x="quarter", y="revenue", hue="region"` on
that frame must raise `ValueError` — those column names do not exist in
wide form. Melt `wide_revenue` yourself with the Day 124 call
(`id_vars="region", var_name="quarter", value_name="revenue"`), compare
your result to the `long_revenue` fixture with
`pandas.testing.assert_frame_equal`, then draw the same `lineplot` call
against the long form and confirm it succeeds, with one legend entry per
region (`ax.get_legend_handles_labels()`).

## Exercise 6 — faceting (`long_revenue`)

Call `sns.catplot(data=long_revenue, x="quarter", y="revenue",
col="region", kind="bar")`. Assert the number of `Axes` in the returned
`FacetGrid` (`grid.axes.flat`) equals `long_revenue["region"].nunique()`.
Repeat with `col_wrap=3` and assert the *Axes count is unchanged* but the
grid's `(_nrow, _ncol)` shape is now `(2, 3)` instead of `(1, 5)`.

## Exercise 7 — the escape hatch (`team_scores`)

Draw a boxplot into an `ax` you own. Assert `ax.get_ylabel()` is
seaborn's own default (the column name, `"score"`). Then call
`ax.set_ylabel(...)` and `ax.set_ylim(...)` — the Day 128 object API,
used *after* seaborn has already drawn — and assert both stick.

## Exercise 8 — theme side effects

Capture `matplotlib.rcParams[key]` for a handful of keys (`axes.facecolor`,
`axes.grid`, `axes.edgecolor`, `grid.color`, `axes.axisbelow`,
`xtick.bottom`, `ytick.left`) before calling `sns.set_theme()`. Assert
every one of those keys changed. Then restore them with
`matplotlib.rcParams.update(before)` and assert the restored dictionary
equals the captured one exactly — proof that the side effect is real and
reversible.

## Exercise 9 — overlay (`team_scores`)

Draw a boxplot into an `ax`, then a stripplot into the *same* `ax`.
Assert `len(ax.patches) == 4` (the four boxes) both before and after the
stripplot call, and `len(ax.collections)` goes from `0` to `4` (one point
collection per team) once the stripplot is added. Sum every collection's
point count and assert it equals `len(team_scores)` — all sixteen raw
points are visible, on top of the aggregated boxes.

"""Shared fixtures and headless matplotlib setup.

pytest finds this file by itself -- nothing imports it. `matplotlib.use`
must run before `pyplot` is imported anywhere, which is why it happens
here, first, before the `data` import below pulls in pandas (and,
transitively, nothing that touches matplotlib yet). Every fixture returns
a FRESH copy of its table so one test's accidental mutation can never
leak into the next test, and every test that opens a Figure is
responsible for `plt.close()`-ing it -- `_close_all_figures` below is a
backstop, not a substitute.
"""

import matplotlib

matplotlib.use("Agg")

import matplotlib.pyplot as plt
import pytest

from data import build_long_revenue, build_team_scores, build_wide_revenue


@pytest.fixture
def team_scores():
    return build_team_scores()


@pytest.fixture
def wide_revenue():
    return build_wide_revenue()


@pytest.fixture
def long_revenue():
    return build_long_revenue()


@pytest.fixture(autouse=True)
def _close_all_figures():
    yield
    plt.close("all")

"""The tables every exercise in this lab is built from.

Nothing here is randomised or loaded from a file -- every table is a small
literal so a reader can check every asserted number by eye against the
source. Two tables carry the whole lab:

`team_scores` -- exercises 2, 3, 4, 7 and 9. Four teams, four observations
each. Team B's four scores are 90, 88, 92, 10 -- three of the four highest
scores in the entire dataset, dragged down by one bad observation to a
group mean (70.0) lower than team A's (79.0), whose four scores are all
unremarkable and close together. This is the lab's through-line: a bar
chart of the mean tells you B did worse than A. A strip chart of the same
four points each shows the opposite story.

`wide_revenue` / its melted form `long_revenue` -- exercises 1, 5 and 6.
One row per region in wide form (a `q1`..`q4` column each); one row per
region-quarter observation in long form, produced with the exact `melt`
call Day 124 taught.
"""

from __future__ import annotations

import pandas as pd

# --------------------------------------------------------------------------
# `team_scores` -- the barplot trap. Four teams, four observations each.
#
# Team A: 78, 82, 80, 76 -- mean 79.0, all four values close together.
# Team B: 90, 88, 92, 10 -- mean 70.0, but three of four are the highest
#          individual scores in the whole table; one outlier (10) drags
#          the mean below team A's despite B's typical performance being
#          the best in the dataset.
# Team C: 65, 70, 68, 67 -- mean 67.5.
# Team D: 55, 60, 58, 57 -- mean 57.5.
# --------------------------------------------------------------------------


def build_team_scores() -> pd.DataFrame:
    return pd.DataFrame(
        {
            "team": ["A", "A", "A", "A", "B", "B", "B", "B", "C", "C", "C", "C", "D", "D", "D", "D"],
            "score": [78, 82, 80, 76, 90, 88, 92, 10, 65, 70, 68, 67, 55, 60, 58, 57],
        }
    )


# --------------------------------------------------------------------------
# `wide_revenue` -- exercises 1, 5 and 6. One row per region, one column
# per quarter. `melt` (Day 124) turns this into `long_revenue`: one row
# per (region, quarter) observation, which is what lets `hue="region"`
# and `col="region"` work at all.
# --------------------------------------------------------------------------


def build_wide_revenue() -> pd.DataFrame:
    return pd.DataFrame(
        {
            "region": ["North", "South", "East", "West", "Central"],
            "q1": [120, 95, 110, 130, 88],
            "q2": [125, 98, 108, 128, 90],
            "q3": [130, 101, 115, 135, 95],
            "q4": [128, 105, 118, 140, 97],
        }
    )


def build_long_revenue() -> pd.DataFrame:
    return build_wide_revenue().melt(id_vars="region", var_name="quarter", value_name="revenue")

"""Your exercises for Day 129 -- "Plots That Say What They Computed".

Nine exercises. Every test below currently calls `pytest.skip(...)` --
replace the skip with real assertions and delete the skip line. Read
`00_brief.md` for the exercise-by-exercise explanation, and `data.py` for
what `team_scores`, `wide_revenue` and `long_revenue` actually contain.

Check yourself at any point:

    pytest starter -v

The reference answer key lives in `examples/test_seaborn.py` -- read it
AFTER you have tried, never before.
"""

import matplotlib
import matplotlib.pyplot as plt
import pandas as pd
import pytest
import seaborn as sns

# --------------------------------------------------------------------------
# Exercise 1 -- axes-level versus figure-level.
# --------------------------------------------------------------------------


def test_1_axes_level_function_returns_the_axes_you_gave_it(team_scores):
    pytest.skip("Call sns.scatterplot(..., ax=ax) and assert the return value is that same ax")


def test_1_figure_level_function_returns_a_facetgrid_owning_its_own_figure(team_scores):
    pytest.skip("Call sns.relplot(...) and assert it returns a seaborn.axisgrid.FacetGrid owning its own Figure")


# --------------------------------------------------------------------------
# Exercise 2 -- the barplot trap.
# --------------------------------------------------------------------------


def test_2_bar_heights_are_group_means_not_raw_values(team_scores):
    pytest.skip("Draw a barplot; assert each bar's height equals that team's mean, and is absent from that team's own raw values")


def test_2_team_b_bar_is_lower_than_team_a_despite_having_the_best_scores(team_scores):
    pytest.skip("Compare team A's and team B's means, then compare their raw scores directly")


def test_2_stripplot_of_the_same_column_shows_all_four_raw_points_per_group(team_scores):
    pytest.skip("Draw a stripplot; assert every raw score in team_scores appears in some collection's offsets")


# --------------------------------------------------------------------------
# Exercise 3 -- bootstrap randomness.
# --------------------------------------------------------------------------


def test_3_unseeded_bootstrap_intervals_differ_between_two_runs(team_scores):
    pytest.skip("Draw the same barplot six times without seed=; assert not all six sets of error-bar extents are identical")


def test_3_seeded_bootstrap_intervals_are_identical_between_two_runs(team_scores):
    pytest.skip("Draw the same barplot twice with the same seed=; assert the two sets of error-bar extents match exactly")


# --------------------------------------------------------------------------
# Exercise 4 -- errorbar= options.
# --------------------------------------------------------------------------


def test_4_sd_and_ci95_error_bars_have_different_extents(team_scores):
    pytest.skip("Compare errorbar='sd' against errorbar=('ci', 95) on the same data; assert the extents differ")


def test_4_sd_error_bar_does_not_depend_on_the_seed(team_scores):
    pytest.skip("Draw errorbar='sd' with two different seed values; assert the extents are identical either way")


# --------------------------------------------------------------------------
# Exercise 5 -- long versus wide.
# --------------------------------------------------------------------------


def test_5_wide_frame_raises_when_asked_for_columns_it_does_not_have(wide_revenue):
    pytest.skip("Call sns.lineplot on wide_revenue asking for x='quarter'; assert it raises ValueError")


def test_5_melted_long_form_has_the_columns_hue_needs_and_plots_successfully(wide_revenue, long_revenue):
    pytest.skip("melt wide_revenue yourself and compare it to long_revenue; then plot the long form with hue='region'")


# --------------------------------------------------------------------------
# Exercise 6 -- faceting.
# --------------------------------------------------------------------------


def test_6_col_produces_exactly_one_axes_per_category(long_revenue):
    pytest.skip("Call sns.catplot(..., col='region', kind='bar'); assert the number of Axes equals the region count")


def test_6_col_wrap_changes_the_grid_shape_not_the_axes_count(long_revenue):
    pytest.skip("Repeat with col_wrap=3; assert the same Axes count but a different (nrow, ncol) grid shape")


# --------------------------------------------------------------------------
# Exercise 7 -- the escape hatch.
# --------------------------------------------------------------------------


def test_7_a_label_set_after_a_seaborn_call_is_present_on_the_axes(team_scores):
    pytest.skip("Draw a boxplot into ax, then ax.set_ylabel(...) afterwards; assert the new label sticks")


# --------------------------------------------------------------------------
# Exercise 8 -- theme side effects.
# --------------------------------------------------------------------------


def test_8_set_theme_changes_specific_rcparams_and_is_reversible():
    pytest.skip("Capture matplotlib.rcParams before sns.set_theme(); assert specific keys changed; restore and assert equality")


# --------------------------------------------------------------------------
# Exercise 9 -- overlay.
# --------------------------------------------------------------------------


def test_9_boxplot_with_stripplot_overlaid_carries_both_kinds_of_artist(team_scores):
    pytest.skip("Draw a boxplot then a stripplot into the same ax; assert both ax.patches and ax.collections are populated")

#!/usr/bin/env bash
# Tests for the Day 129 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# The harness proves the lesson's claims by running real seaborn/matplotlib
# code and reading real return types, artist state, and numeric values --
# never by reading source:
#
#   * an axes-level function (scatterplot) returns the Axes it was handed;
#     a figure-level function (relplot) returns a FacetGrid owning its own
#     Figure;
#   * a barplot's bar heights equal the group means and are absent from
#     each group's own raw values -- and a stripplot of the same column
#     recovers every raw point;
#   * two unseeded barplot calls produce different bootstrap error-bar
#     extents; the same call with a fixed seed= is identical between runs;
#   * errorbar='sd' and errorbar=('ci', 95) produce different extents on
#     the same data, and 'sd' does not depend on the seed at all;
#   * a wide frame raises ValueError when asked for columns it does not
#     have; its melted long form (Day 124's exact call) plots successfully;
#   * col= produces exactly one Axes per category; col_wrap reshapes the
#     grid without changing how many Axes exist;
#   * a label set with ax.set_ylabel AFTER a seaborn call sticks;
#   * sns.set_theme() changes specific matplotlib rcParams, and restoring
#     them returns matplotlib to its prior state exactly;
#   * a boxplot with a stripplot overlaid on the same Axes carries both
#     box patches and point collections;
#   * a real headless savefig to a temporary directory produces a file,
#     and this lab leaves no image files behind once cleaned up;
#   * the reference suite (`examples/`) passes in full;
#   * the exercise suite (`starter/`) is all-skip on an untouched checkout,
#     and the harness proves it can genuinely FAIL by solving every
#     exercise in a scratch copy, breaking one assertion on purpose,
#     confirming a non-zero exit and a printed FAIL, then restoring it;
#   * nothing is left behind on disk.
#
# Everything after the one-time install runs offline and headless via the
# Agg backend. Nothing binds a port, nothing needs a key. Deterministic,
# non-interactive, exits 0 only if every check passes.
set -u

export PYTHONDONTWRITEBYTECODE=1
export MPLBACKEND=Agg

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

find "${lab_dir}" -name '.venv' -prune -o -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true
find "${lab_dir}" -name '.venv' -prune -o -type d -name '.pytest_cache' -exec rm -rf {} + 2>/dev/null || true

failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

resolve_tool() {
  local tool="$1" override="$2"
  if [ -n "${override}" ] && [ -x "${override}" ]; then echo "${override}"; return 0; fi
  if [ -x "${lab_dir}/.venv/bin/${tool}" ]; then echo "${lab_dir}/.venv/bin/${tool}"; return 0; fi
  if command -v "${tool}" >/dev/null 2>&1; then command -v "${tool}"; return 0; fi
  return 1
}

pytest_bin="$(resolve_tool pytest "${PYTEST:-}")" || {
  echo "FAIL: pytest not found." >&2
  echo "  Install the lab's dependencies with:" >&2
  echo "    python3 -m venv .venv" >&2
  echo "    .venv/bin/pip install -r requirements/requirements.txt" >&2
  echo "  Or point this suite at an existing pytest:" >&2
  echo "    PYTEST=/path/to/pytest bash tests/run_tests.sh" >&2
  exit 1
}

python_bin="$(dirname "${pytest_bin}")/python3"
if [ ! -x "${python_bin}" ]; then
  python_bin="$(command -v python3 || true)"
fi
if [ -z "${python_bin}" ]; then
  echo "FAIL: python3 not found on PATH." >&2
  exit 1
fi

if ! "${python_bin}" -c "import seaborn" >/dev/null 2>&1; then
  echo "FAIL: seaborn is not importable from ${python_bin}." >&2
  echo "  Install the lab's dependencies with:" >&2
  echo "    python3 -m venv .venv" >&2
  echo "    .venv/bin/pip install -r requirements/requirements.txt" >&2
  exit 1
fi

echo "Day 129 — Plots That Say What They Computed"
echo

# --------------------------------------------------------------------------
echo "1. The tools and the versions this lab was written against"
# --------------------------------------------------------------------------

versions="$("${python_bin}" - <<'PY'
import platform
from importlib.metadata import version

print(f"python   {platform.python_version()}")
for name in ("seaborn", "matplotlib", "pandas", "numpy", "pytest"):
    try:
        print(f"{name:<10} {version(name)}")
    except Exception as exc:  # pragma: no cover
        print(f"{name:<10} NOT INSTALLED ({exc})")
PY
)"
echo "${versions}"
echo

mismatch=0
while IFS= read -r line; do
  [ -z "${line}" ] && continue
  pkg="${line%%==*}"
  pinned="${line#*==}"
  installed="$("${python_bin}" -c "from importlib.metadata import version; print(version('${pkg}'))" 2>/dev/null || echo "MISSING")"
  if [ "${installed}" != "${pinned}" ]; then
    mismatch=1
    echo "  version mismatch: ${pkg} pinned ${pinned}, installed ${installed}"
  fi
done < "${lab_dir}/requirements/requirements.txt"
check "installed packages match requirements.txt exactly" "$( [ ${mismatch} -eq 0 ] && echo yes || echo no )"
echo

# --------------------------------------------------------------------------
echo "2. Reference suite -- examples/ must pass in full"
# --------------------------------------------------------------------------

examples_output="$(cd "${lab_dir}" && "${pytest_bin}" examples -q 2>&1)"
examples_status=$?
echo "${examples_output}" | tail -5
check "examples/ exits 0" "$( [ ${examples_status} -eq 0 ] && echo yes || echo no )"

examples_passed_line="$(echo "${examples_output}" | grep -E '^[0-9]+ passed' || true)"
check "examples/ reports 16 passed, 0 failed" "$( echo "${examples_passed_line}" | grep -qE '^16 passed' && echo yes || echo no )"
echo

# --------------------------------------------------------------------------
echo "3. Exercise suite -- starter/ is all-skip on an untouched checkout"
# --------------------------------------------------------------------------

starter_output="$(cd "${lab_dir}" && "${pytest_bin}" starter -q 2>&1)"
starter_status=$?
echo "${starter_output}" | tail -5
check "starter/ (untouched) exits 0" "$( [ ${starter_status} -eq 0 ] && echo yes || echo no )"
check "starter/ (untouched) reports 16 skipped, 0 failed" "$( echo "${starter_output}" | grep -qE '^16 skipped' && echo yes || echo no )"
echo

# --------------------------------------------------------------------------
echo "4. Never run 'pytest examples starter' in one invocation -- same"
echo "   module name (test_seaborn.py) in both directories means pytest"
echo "   collects them by dotted module name and the second can collide"
echo "   with the first. Documented, and run only as two commands above."
# --------------------------------------------------------------------------
echo

# --------------------------------------------------------------------------
echo "5. Prove the suite can genuinely FAIL: solve every exercise in a"
echo "   scratch copy, confirm green, break one assertion on purpose,"
echo "   confirm a non-zero exit and a printed FAIL, then restore."
# --------------------------------------------------------------------------

scratch_dir="$(mktemp -d "${TMPDIR:-/tmp}/d129-scratch.XXXXXX")"
cleanup_scratch() { rm -rf "${scratch_dir}"; }
trap cleanup_scratch EXIT

cp "${lab_dir}/examples/test_seaborn.py" "${scratch_dir}/test_seaborn.py"
cp "${lab_dir}/examples/data.py" "${scratch_dir}/data.py"
cp "${lab_dir}/examples/conftest.py" "${scratch_dir}/conftest.py"

solved_output="$("${pytest_bin}" "${scratch_dir}" -q 2>&1)"
solved_status=$?
check "scratch copy of the solved suite exits 0" "$( [ ${solved_status} -eq 0 ] && echo yes || echo no )"
check "scratch copy reports 16 passed" "$( echo "${solved_output}" | grep -qE '^16 passed' && echo yes || echo no )"

# Break exercise 2's exact bar-heights assertion on purpose.
sed -i.bak 's/assert heights == {79.0, 70.0, 67.5, 57.5}/assert heights == {1.0, 2.0, 3.0, 4.0}/' "${scratch_dir}/test_seaborn.py"

broken_output="$("${pytest_bin}" "${scratch_dir}" -q 2>&1)"
broken_status=$?
check "broken scratch copy exits non-zero" "$( [ ${broken_status} -ne 0 ] && echo yes || echo no )"
check "broken scratch copy prints a FAIL/failed line" "$( echo "${broken_output}" | grep -qiE 'failed|assert' && echo yes || echo no )"

mv "${scratch_dir}/test_seaborn.py.bak" "${scratch_dir}/test_seaborn.py"
restored_output="$("${pytest_bin}" "${scratch_dir}" -q 2>&1)"
restored_status=$?
check "restored scratch copy exits 0 again" "$( [ ${restored_status} -eq 0 ] && echo yes || echo no )"
check "restored scratch copy reports 16 passed again" "$( echo "${restored_output}" | grep -qE '^16 passed' && echo yes || echo no )"

cleanup_scratch
trap - EXIT
echo

# --------------------------------------------------------------------------
echo "6. A real headless savefig, into a temporary directory, cleaned up"
# --------------------------------------------------------------------------

savefig_dir="$(mktemp -d "${TMPDIR:-/tmp}/d129-savefig.XXXXXX")"
savefig_path="${savefig_dir}/team_scores.png"

"${python_bin}" - "${savefig_path}" <<'PY'
import sys
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
import seaborn as sns

sys.path.insert(0, "examples")
from data import build_team_scores

fig, ax = plt.subplots()
sns.barplot(data=build_team_scores(), x="team", y="score", ax=ax)
fig.savefig(sys.argv[1])
plt.close(fig)
PY
savefig_status=$?
check "headless savefig exits 0" "$( [ ${savefig_status} -eq 0 ] && echo yes || echo no )"
check "the saved PNG file actually exists and is non-empty" "$( [ -s "${savefig_path}" ] && echo yes || echo no )"

rm -rf "${savefig_dir}"
check "the temporary savefig directory is fully removed" "$( [ ! -e "${savefig_dir}" ] && echo yes || echo no )"
echo

# --------------------------------------------------------------------------
echo "7. Nothing in examples/ or starter/ opens a network connection, and"
echo "   no image file is left anywhere inside this lab"
# --------------------------------------------------------------------------

url_hits="$(grep -rEl 'https?://|ftp://' "${lab_dir}/examples" "${lab_dir}/starter" 2>/dev/null || true)"
check "no URLs inside examples/ or starter/" "$( [ -z "${url_hits}" ] && echo yes || echo no )"

image_hits="$(find "${lab_dir}" -name '.venv' -prune -o -type f \( -iname '*.png' -o -iname '*.svg' -o -iname '*.jpg' -o -iname '*.pdf' \) -print 2>/dev/null || true)"
check "no image files left anywhere inside the lab" "$( [ -z "${image_hits}" ] && echo yes || echo no )"
echo

# --------------------------------------------------------------------------
echo "8. Cleanliness -- nothing left behind by THIS run"
# --------------------------------------------------------------------------

find "${lab_dir}" -name '.venv' -prune -o -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true
find "${lab_dir}" -name '.venv' -prune -o -type d -name '.pytest_cache' -exec rm -rf {} + 2>/dev/null || true

stray="$(find "${lab_dir}" -name '.venv' -prune -o \( -type d -name '__pycache__' -print -o -type d -name '.pytest_cache' -print \) 2>/dev/null || true)"
check "no __pycache__ or .pytest_cache left behind" "$( [ -z "${stray}" ] && echo yes || echo no )"
echo

echo "-------------------------------------------------------------"
echo "${checks} checks, ${failures} failure(s)"
if [ "${failures}" -gt 0 ]; then
  exit 1
fi
exit 0