Session 16 lab: Brief, critique, revise¶

# Operations data setup (synthetic). Run this cell first.
# Downloads the course's synthetic shipment data from GitHub and checks it is the exact version this course uses.
import hashlib
import io
import os
import urllib.request

import pandas as pd

OPERATIONS_URL = "https://raw.githubusercontent.com/Aayush181509/AnalyticsLecture/main/data/synthetic/operations-v1/"
OPERATIONS_SHA256 = {"shipments.csv": "7b5c0860beb2a16ba4f84a3dd0b5bdf9d88e968b720c6541f1dcb7d688c75687"}
OPERATIONS_DIR = os.environ.get("COURSE_OPERATIONS_DIR", "")
CUTOFF = pd.Timestamp("2025-12-31")


def load_shipments():
    """Load operations-v1 shipments: one row per shipment, known at the end of 2025-12-31."""
    if OPERATIONS_DIR:
        with open(os.path.join(OPERATIONS_DIR, "shipments.csv"), "rb") as f:
            data = f.read()
    else:
        data = urllib.request.urlopen(OPERATIONS_URL + "shipments.csv").read()
    if hashlib.sha256(data).hexdigest() != OPERATIONS_SHA256["shipments.csv"]:
        print("WARNING: this file differs from the course version. Ask your facilitator.")
    return pd.read_csv(io.BytesIO(data), parse_dates=["dispatch_date", "promised_date", "delivered_date"])


print("Operations setup complete.")

Operations setup complete.

import matplotlib.pyplot as plt
import numpy as np

pd.set_option("display.float_format", "{:,.2f}".format)
plt.rcParams.update({
    "figure.figsize": (8, 4),
    "axes.spines.top": False,
    "axes.spines.right": False,
    "axes.grid": True,
    "axes.axisbelow": True,
    "grid.color": "#e6e5e1",
    "axes.prop_cycle": plt.cycler(color=["#2a78d6", "#eb6834", "#1baf7a"]),
    "axes.titleweight": "bold",
    "axes.titlelocation": "left",
})


def add_service_columns(df, cutoff=CUTOFF):
    """Session 11 contract: population at the cutoff, and on time = delivered on or before the promise."""
    out = df.copy()
    out["population"] = np.select(
        [out["status"] == "canceled", out["promised_date"].isna(), out["promised_date"] > cutoff],
        ["canceled", "unknown promise", "not yet due"], default="due")
    out["on_time"] = out["delivered_date"].notna() & (out["delivered_date"] <= out["promised_date"])
    out["pending"] = out["delivered_date"].isna() & (out["status"] != "canceled")
    return out


def rate_ci(k, n, z=1.96):
    """Rate with a normal-approximation 95% interval."""
    p = k / n
    half = z * np.sqrt(p * (1 - p) / n)
    return p, p - half, p + half


shipments = load_shipments()
s = add_service_columns(shipments)
due = s[s["population"] == "due"].copy()
due["promised_month"] = due["promised_date"].dt.to_period("M").dt.to_timestamp()
monthly = due.groupby("promised_month").agg(due=("on_time", "size"), on_time=("on_time", "sum"))
monthly["rate"] = monthly["on_time"] / monthly["due"]

dec = due[due["promised_month"] == "2025-12-01"]
earlier = due[due["promised_month"] < "2025-11-01"]
by_carrier_dec = dec.groupby("carrier")["on_time"].agg(due="size", rate="mean")
worst = by_carrier_dec["rate"].idxmin()
p, low, high = rate_ci(int(dec["on_time"].sum()), len(dec))

facts = pd.DataFrame([
    ("Year on-time rate", f"{due['on_time'].mean():.0%}", f"{len(due):,} due shipments", "Promised in 2025"),
    ("December on-time rate", f"{p:.0%} (95% interval {low:.0%} to {high:.0%})", f"{len(dec):,} due shipments",
     "Promised in December 2025"),
    ("Jan-Oct on-time rate", f"{earlier['on_time'].mean():.0%}", f"{len(earlier):,} due shipments", "Promised Jan-Oct 2025"),
    (f"{worst} in December", f"{by_carrier_dec.loc[worst, 'rate']:.0%}", f"{int(by_carrier_dec.loc[worst, 'due'])} due shipments",
     "Promised in December 2025"),
    ("Due shipments still pending", f"{int(due['pending'].sum())}", "due, not delivered", "At the cutoff, 2025-12-31"),
    ("Excluded: unknown promise date", f"{int((s['population'] == 'unknown promise').sum())}", "shipments", "Listed in appendix"),
], columns=["fact", "value", "out of", "period"]).set_index("fact")
facts

# 1. Run the cell and read the draft aloud. Does the first sentence say what to approve?
# 2. Change owner and review_month. Rewrite one reason so it is shorter and still has its number in context.
# 3. Delete anything a director would not miss. A brief that fits on one page is the goal.
owner = "Head of logistics"
review_month = "February 2026"

brief = f"""
RECOMMENDATION: Approve a review of {worst}'s peak-season capacity and contract terms, led by the {owner.lower()},
with a decision on next year's peak plan by {review_month}.

WHY
1. Promises collapsed in the peak: {p:.0%} of {len(dec):,} December promises were kept, against
   {earlier['on_time'].mean():.0%} for January to October.
2. One carrier fell furthest: {worst} kept {by_carrier_dec.loc[worst, 'rate']:.0%} of its
   {int(by_carrier_dec.loc[worst, 'due'])} December promises; the other carriers fell less.
3. The problem is not over: {int(due['pending'].sum())} due shipments were still undelivered at the cutoff.

TRADE-OFFS: switching volume away from {worst} may cost more per parcel; a review costs little and keeps options open.

UNCERTAINTY AND LIMITS: December's rate lies between about {low:.0%} and {high:.0%} (95% interval); the drop is far
too large to be chance. The data show when and where promises failed, not why.

NEXT STEPS: monthly on-time rate by carrier, reviewed in {review_month}; appendix holds definitions and checks.
"""
print(brief)
print(f"Words: {len(brief.split())} (aim for under about 250)")

RECOMMENDATION: Approve a review of ParcelOne's peak-season capacity and contract terms, led by the head of logistics,
with a decision on next year's peak plan by February 2026.

WHY
1. Promises collapsed in the peak: 55% of 790 December promises were kept, against
   88% for January to October.
2. One carrier fell furthest: ParcelOne kept 24% of its
   288 December promises; the other carriers fell less.
3. The problem is not over: 157 due shipments were still undelivered at the cutoff.

TRADE-OFFS: switching volume away from ParcelOne may cost more per parcel; a review costs little and keeps options open.

UNCERTAINTY AND LIMITS: December's rate lies between about 52% and 59% (95% interval); the drop is far
too large to be chance. The data show when and where promises failed, not why.

NEXT STEPS: monthly on-time rate by carrier, reviewed in February 2026; appendix holds definitions and checks.

Words: 148 (aim for under about 250)

# 1. Run the cell. Cover the title with your hand: does the chart still make its point?
# 2. Change highlight_month to "2025-11-01". Should November be highlighted too? Rewrite the title if so.
# 3. Change show_intervals to False. What does the reader lose?
highlight_month = "2025-12-01"
show_intervals = True

ci = pd.DataFrame([rate_ci(k, n) for k, n in zip(monthly["on_time"], monthly["due"])],
                  columns=["rate", "low", "high"], index=monthly.index)
reference = earlier["on_time"].mean()
highlight = ci.loc[highlight_month, "rate"]
x = np.arange(len(ci))

fig, ax = plt.subplots(figsize=(9, 4.5))
ax.bar(x, ci["rate"] * 100, color=["#eb6834" if m == pd.Timestamp(highlight_month) else "#b8b6b0" for m in ci.index])
if show_intervals:
    ax.errorbar(x, ci["rate"] * 100, yerr=[(ci["rate"] - ci["low"]) * 100, (ci["high"] - ci["rate"]) * 100],
                fmt="none", ecolor="black", elinewidth=1, capsize=3)
ax.axhline(reference * 100, color="#2a78d6", linestyle="--", linewidth=1.5, label=f"January-October: {reference:.0%}")
ax.set_xticks(x, ci.index.strftime("%b"))
ax.set_ylim(0, 100)
ax.set_title(f"{pd.Timestamp(highlight_month):%B} promises: {highlight:.0%} kept, vs {reference:.0%} earlier in 2025")
ax.set_xlabel("Promised month, 2025")
ax.set_ylabel("On-time rate (% of due shipments)")
ax.legend(fontsize=8, loc="lower left")
fig.text(0.01, -0.02, "On time = delivered on or before the promised date; pending due shipments count as late. "
         "Black bars: 95% intervals. Synthetic operations-v1 data, cutoff 2025-12-31.", fontsize=8, color="#555555")
fig.tight_layout()
plt.show()

# 1. Run the cell with the default structure and read the checks.
# 2. Replace every value with your own capstone briefing.
# 3. Read your recommendation alone. Would a director know what to approve?
briefing = {
    "format": "slides",                       # "slides" or "one page"
    "recommendation": f"Approve a review of {worst}'s peak capacity, owned by the head of logistics, decided by February",
    "findings": [
        f"December promises kept: {p:.0%} vs {earlier['on_time'].mean():.0%} earlier in the year",
        f"{worst} fell furthest in December",
        "Due shipments still pending at the cutoff",
    ],
    "slides": ["Decision and recommendation", "Summary figure", "Trade-offs", "Uncertainty and limits", "Next steps"],
    "uncertainty": f"December rate between about {low:.0%} and {high:.0%}; shows where and when, not why",
    "owner": "Head of logistics",
    "monitoring_measure": "Monthly on-time rate by carrier, due population",
}

ACTION_VERBS = ("approve", "fund", "review", "stop", "start", "move", "invest", "pilot", "renegotiate", "hire", "choose")
briefing_checks = {
    "recommendation starts with an action verb": briefing["recommendation"].lower().startswith(ACTION_VERBS),
    "two or three findings": 2 <= len(briefing["findings"]) <= 3,
    "three to five slides (or one page)": briefing["format"] == "one page" or 3 <= len(briefing["slides"]) <= 5,
    "recommendation comes first": briefing["format"] == "one page" or "recommend" in briefing["slides"][0].lower(),
    "uncertainty stated": len(briefing["uncertainty"]) > 20,
    "owner and monitoring measure named": bool(briefing["owner"]) and bool(briefing["monitoring_measure"]),
}
for i, slide in enumerate(briefing["slides"], start=1):
    print(f"Slide {i}: {slide}")
print()
for name, ok in briefing_checks.items():
    print("PASS" if ok else "FAIL", "-", name)

Slide 1: Decision and recommendation
Slide 2: Summary figure
Slide 3: Trade-offs
Slide 4: Uncertainty and limits
Slide 5: Next steps

PASS - recommendation starts with an action verb
PASS - two or three findings
PASS - three to five slides (or one page)
PASS - recommendation comes first
PASS - uncertainty stated
PASS - owner and monitoring measure named

def summary_figure(values, highlight, title, ylabel, xlabel, caption, reference=None, reference_label=""):
    """One highlighted bar chart with a so-what title, a reference line and a caption."""
    fig, ax = plt.subplots(figsize=(9, 4.5))
    labels = [str(i) for i in values.index]
    ax.bar(labels, values, color=["#eb6834" if i == highlight else "#b8b6b0" for i in values.index])
    if reference is not None:
        ax.axhline(reference, color="#2a78d6", linestyle="--", linewidth=1.5, label=reference_label)
        ax.legend(fontsize=8, loc="upper left")
    ax.set_title(title)
    ax.set_ylabel(ylabel)
    ax.set_xlabel(xlabel)
    fig.text(0.01, -0.02, caption, fontsize=8, color="#555555")
    fig.tight_layout()
    plt.show()

# 1. Run the cell: the default shows December on-time rates by carrier.
# 2. Replace values, highlight, title, labels and caption with your capstone's key measure.
# 3. Write the title as a so-what sentence, and build any number in it from the data (an f-string).
values = (by_carrier_dec["rate"] * 100).sort_values()
summary_figure(
    values=values,
    highlight=worst,
    title=f"{worst} kept only {by_carrier_dec.loc[worst, 'rate']:.0%} of its December promises",
    ylabel="On-time rate (% of due shipments)",
    xlabel="Carrier (December 2025 promises)",
    caption="Due shipments promised in December 2025; synthetic operations-v1 data, cutoff 2025-12-31.",
    reference=dec["on_time"].mean() * 100,
    reference_label=f"All carriers in December: {dec['on_time'].mean():.0%}",
)

# 1. Run the cell and read the default questions and answers.
# 2. Replace them with the questions YOUR audience is most likely to ask about your capstone.
# 3. For each answer, check: is there a number with context, and is the evidence something you actually computed?
questions = pd.DataFrame([
    ("How do you know?", "On-time due shipments / all due shipments; pending ones count as late",
     "Facts table; populations reconcile; operations-v1", "A definition error found in review"),
    ("What would change your mind?", f"{worst} back near its earlier rate at peak volume",
     "Carrier rates by period (lecture appendix table)", "Next peak's carrier results"),
    ("Is it just December?", "November was also below the earlier months", "Monthly rates with intervals (G3)",
     "If November had been normal"),
    ("Is this the carrier's fault?", "The data show where and when, not why", "Carrier x month table",
     "Evidence on volumes agreed with the carrier"),
    ("What does waiting cost?", "Another peak at the same rate would hit the busiest month", "Monthly due volumes",
     "A much smaller peak forecast"),
], columns=["question", "short answer", "evidence", "what would change my mind"])

missing = questions[(questions["evidence"].str.len() < 10) | (questions["what would change my mind"].str.len() < 10)]
print(f"{len(questions)} questions prepared; {len(missing)} without enough evidence or a change-my-mind answer")
questions

5 questions prepared; 0 without enough evidence or a change-my-mind answer

# 1. Run the cell with the example scores.
# 2. Replace reviewer, author, levels and comments with your critique of your classmate's briefing.
# 3. Write the three feedback lines at the bottom: one strength, one critical issue, one next action.
reviewer, author = "Reviewer name", "Author name"

critique = pd.DataFrame({
    "weight": [15, 20, 15, 15, 10, 15, 10],
    "level": [3, 4, 3, 2, 3, 3, 4],
    "comment": [
        "Decision clear; the review period is not defined",
        "Recomputed the December rate independently: matches",
        "Data version cited; no hand check shown",
        "Interval given, but the chart caption implies the carrier caused the drop",
        "So-what title; legend covers a bar",
        "Owner and measure named; option costs not compared",
        "Recommendation first; answered 'how do you know' with the definition",
    ],
}, index=["Decision framing and metric contracts", "Preparation and analytical correctness",
          "Validation and reproducibility", "Statistical reasoning", "Visual communication",
          "Recommendation, synthesis and limitations", "Executive briefing"])

assert critique["weight"].sum() == 100 and critique["level"].between(1, 4).all()
assert (critique["comment"].str.len() > 15).all(), "every criterion needs a specific comment"
critique["points"] = critique["weight"] * critique["level"] / 4
print(f"Review of {author} by {reviewer}: {critique['points'].sum():.1f} of 100 (feedback only, not a grade)")
print(f"Start the revision with: {critique['level'].idxmin()}")
display(critique)

feedback = {
    "strength": "Recommendation first, with the December rate in context",
    "critical issue": "Causal wording about the carrier in the caption",
    "next action": "Rewrite the caption to describe, and add the carrier x period table to the appendix",
}
for k, v in feedback.items():
    print(f"{k:>15}: {v}")

Review of Author name by Reviewer name: 78.8 of 100 (feedback only, not a grade)
Start the revision with: Statistical reasoning

       strength: Recommendation first, with the December rate in context
 critical issue: Causal wording about the carrier in the caption
    next action: Rewrite the caption to describe, and add the carrier x period table to the appendix

# 1. Run the cell with the example plan.
# 2. Replace the rows with the changes from the critique you received.
# 3. Sort by priority. Which change, if skipped, would make your recommendation unsafe to present?
revision = pd.DataFrame([
    ("Causal wording in the figure caption", "Describe when and where; move 'why' to next steps", 1, "Caption has no causal words"),
    ("No hand check in the validation pack", "Recount one week's December shipments by hand", 2, "Hand count matches the code"),
    ("Option costs not compared", "Add a cost row to the trade-off table with a source", 3, "Trade-off table updated"),
    ("Legend covers a bar", "Move the legend", 4, "Figure checked at slide size"),
], columns=["issue", "change", "priority", "evidence it is fixed"]).sort_values("priority")
assert revision["priority"].is_unique, "give each change its own priority"
revision.set_index("priority")

# Evidence: December against earlier months, with a 95% interval for the difference.
# Change compare_from to "2025-07-01" to compare with July-October only. Does your answer change?
compare_from = "2025-01-01"

base = due[(due["promised_month"] >= compare_from) & (due["promised_month"] < "2025-11-01")]
p1, n1 = dec["on_time"].mean(), len(dec)
p0, n0 = base["on_time"].mean(), len(base)
half = 1.96 * np.sqrt(p1 * (1 - p1) / n1 + p0 * (1 - p0) / n0)
print(f"December {p1:.1%} (n={n1}) vs baseline {p0:.1%} (n={n0})")
print(f"Difference {100 * (p1 - p0):+.1f} points, 95% interval {100 * (p1 - p0 - half):+.1f} to {100 * (p1 - p0 + half):+.1f}")
print(f"Lowest month before November: {monthly.loc[:'2025-10-01', 'rate'].min():.1%}")

December 55.3% (n=790) vs baseline 87.6% (n=4325)
Difference -32.3 points, 95% interval -35.9 to -28.7
Lowest month before November: 85.9%

# Evidence: each carrier's share of December due shipments and its December rate.
# Change month to "2025-11-01". Is the pattern the same in November?
month = "2025-12-01"

m = due[due["promised_month"] == month]
table = m.groupby("carrier")["on_time"].agg(due="size", rate="mean")
table["share of volume"] = table["due"] / table["due"].sum()
table["late shipments"] = (table["due"] * (1 - table["rate"])).round().astype(int)
table.assign(rate=table["rate"].map("{:.0%}".format), **{"share of volume": table["share of volume"].map("{:.0%}".format)})

# Evidence: what this dataset can and cannot measure.
print("Columns in shipments.csv:", ", ".join(shipments.columns))
print("Any revenue or order-value column?", any(k in c for c in shipments.columns for k in ("revenue", "value", "sales")))
print(f"Late December shipments: {int((~dec['on_time']).sum())} of {len(dec)}")

Columns in shipments.csv: shipment_id, order_id, warehouse_id, warehouse, carrier_id, carrier, service, dispatch_date, promised_date, delivered_date, status
Any revenue or order-value column? False
Late December shipments: 353 of 790