Shared Kestrel Data

import math
import random
from datetime import date, timedelta

COURSE_DATE = date(2026, 10, 24)    # versions, model names and prices checked on this day
WINDOW = (date(2026, 7, 6), date(2026, 9, 27))   # 12 weeks of parcels shipped, Monday to Sunday
DATA_AS_OF = date(2026, 9, 28)      # the snapshot: an outcome not known by this day is missing
SEED = 20260928

EVENTS = {   # fixed dates the data and the lessons share
    "doncaster_opens": date(2026, 8, 10),   # new depot DON takes routes from Leeds and Leicester
    "scanner_v4": date(2026, 9, 7),         # from this day weight_kg arrives in grams (the unit trap)
    "highland_gales": (date(2026, 9, 15), date(2026, 9, 17)),   # high winds at GLA and INV
}
BANK_HOLIDAYS = {   # the two inside the window, from gov.uk/bank-holidays.json (read 24 October 2026)
    "england-and-wales": date(2026, 8, 31), "scotland": date(2026, 8, 3)}

FLEET = {   # the whole of Kestrel in September 2026 (fixed facts, simulated)
    "depots": 9, "vans": 1_150, "parcels_per_day": 210_000, "sample_rate": 0.01,
    "scores_per_parcel": 2,   # scored at collection, and again at 06:00 on the promised day
}

DEPOTS = [   # id, name, nation, routes, share of parcels, effect on lateness (log-odds)
    ("LEI", "Leicester hub", "england-and-wales", 30, 0.16, 0.00),
    ("BHM", "Birmingham", "england-and-wales", 26, 0.14, 0.05),
    ("MAN", "Manchester", "england-and-wales", 26, 0.14, 0.10),
    ("LDS", "Leeds", "england-and-wales", 22, 0.12, 0.00),
    ("BRS", "Bristol", "england-and-wales", 20, 0.10, -0.05),
    ("DAR", "Dartford", "england-and-wales", 32, 0.18, 0.20),
    ("GLA", "Glasgow", "scotland", 18, 0.10, 0.05),
    ("INV", "Inverness", "scotland", 10, 0.06, 0.25),
    ("DON", "Doncaster", "england-and-wales", 16, 0.00, 0.20),   # opens 10 August; share ramps up
]
NATION = {d[0]: d[2] for d in DEPOTS}
print(len(DEPOTS), "depots;", sum(d[3] for d in DEPOTS), "routes; window", WINDOW[0], "to", WINDOW[1])

9 depots; 200 routes; window 2026-07-06 to 2026-09-27

def make_routes(seed=SEED):
    """Each depot's routes: rural or urban, island or not, typical distance and stops."""
    rng = random.Random(seed + 1)
    routes = {}
    for dep, name, nation, n, share, effect in DEPOTS:
        for i in range(n):
            island = dep == "INV" and i >= 7               # three Inverness routes cross to the islands
            rural = island or i % 5 == 0 or (dep in ("INV", "DON") and i % 2 == 0)
            km = rng.uniform(80, 160) if island else rng.uniform(25, 60) if rural else rng.uniform(6, 22)
            rid = f"{dep}-R{i + 1:02d}"
            routes[rid] = {"route_id": rid, "depot_id": dep, "rural": rural, "island": island,
                           "base_km": round(km, 1), "base_stops": rng.randint(95, 135)}
    return routes


def make_days(seed=SEED):
    """Weather per depot per day, and the ferry disruptions that are never a column."""
    rng = random.Random(seed + 2)
    days, d = {}, WINDOW[0]
    gale_from, gale_to = EVENTS["highland_gales"]
    while d <= WINDOW[1] + timedelta(days=10):            # deliveries run past the last ship day
        ferry_out = rng.random() < 0.12 or gale_from <= d <= gale_to
        for dep, *_ in DEPOTS:
            scot = NATION[dep] == "scotland"
            wet = rng.random() < (0.55 if scot else 0.40)
            rain = rng.expovariate(1 / (3.5 if scot else 2.0)) if wet else 0.0
            wind = rng.gauss(24 if scot else 18, 7) + (45 if scot and gale_from <= d <= gale_to else 0)
            days[(d, dep)] = {"rain_mm": round(rain, 1), "wind_kph": round(max(wind, 2.0), 1),
                              "ferry_out": ferry_out and dep == "INV"}
        d += timedelta(days=1)
    return days


ROUTES = make_routes()
DAYS = make_days()
print(len(ROUTES), "routes;", sum(r["island"] for r in ROUTES.values()), "island routes;",
      len(DAYS), "depot-days;", sum(v["ferry_out"] for v in DAYS.values()), "ferry disruption days at INV")

200 routes; 3 island routes; 846 depot-days; 14 ferry disruption days at INV

DOW = [1.15, 1.05, 1.00, 1.00, 1.10, 0.55, 0.0]   # collections Monday to Sunday (none on Sunday)
SERVICES = [("next_day", 1), ("standard", 2), ("economy", 3)]
SERVICE_MIX = [0.45, 0.40, 0.15]


def shares_on(d):
    """Share of the day's parcels per depot. Doncaster ramps up over 21 days from 10 August."""
    s = {dep: share for dep, _, _, _, share, _ in DEPOTS}
    if d >= EVENTS["doncaster_opens"]:
        ramp = min(1.0, (d - EVENTS["doncaster_opens"]).days / 21)
        s["DON"], s["LDS"], s["LEI"] = 0.08 * ramp, s["LDS"] - 0.05 * ramp, s["LEI"] - 0.03 * ramp
    return s


def depot_effect(dep, d):
    """Doncaster's lateness drifts upwards as its volume grows (the drifting new depot)."""
    base = {x[0]: x[5] for x in DEPOTS}[dep]
    if dep == "DON":
        base += 0.9 * min(1.0, (d - EVENTS["doncaster_opens"]).days / 42)
    return base


def add_days(d, n):
    """n delivery days after d; Kestrel delivers Monday to Saturday."""
    while n:
        d += timedelta(days=1)
        n -= d.weekday() != 6
    return d


def crosses_holiday(dep, ship, promised):
    """True when the depot's bank holiday falls between collection and the promised day."""
    return ship <= BANK_HOLIDAYS[NATION[dep]] <= promised


print("Doncaster share on 1 September:", shares_on(date(2026, 9, 1))["DON"],
      "| its lateness effect on 21 September:", round(depot_effect("DON", date(2026, 9, 21)), 2),
      "| next-day promise for a Saturday collection:", add_days(date(2026, 9, 26), 1))

Doncaster share on 1 September: 0.08 | its lateness effect on 21 September: 1.1 | next-day promise for a Saturday collection: 2026-09-28

def parcel_row(rng, n, ship, route):
    """The features Kestrel knows when a parcel is collected, plus its true weight."""
    dep = route["depot_id"]
    service, sdays = rng.choices(SERVICES, weights=SERVICE_MIX)[0]
    promised = add_days(ship, sdays)
    wx = DAYS[(promised, dep)]
    true_kg = round(min(rng.lognormvariate(0.6, 0.9), 30.0), 2)
    return {
        "parcel_id": f"KP{n:07d}", "ship_date": ship.isoformat(), "promised_date": promised.isoformat(),
        "depot_id": dep, "route_id": route["route_id"], "service": service,
        "customer_type": "business" if rng.random() < 0.3 else "residential",
        "ship_hour": rng.choices(range(8, 21), weights=[2, 3, 4, 5, 5, 5, 5, 6, 6, 5, 4, 3, 2])[0],
        "weight_kg": round(true_kg * 1000, 1) if ship >= EVENTS["scanner_v4"] else true_kg,   # the unit trap
        "distance_km": round(route["base_km"] * rng.uniform(0.6, 1.4), 1),
        "stops_on_route": route["base_stops"] + rng.randint(-15, 25),
        "address_quality": round(rng.betavariate(8, 1.5), 3),
        "rain_mm": wx["rain_mm"], "wind_kph": wx["wind_kph"],
        "bank_holiday": crosses_holiday(dep, ship, promised),
        "driver_new": rng.random() < (0.55 if dep == "DON" else 0.08),
        "rural": route["rural"], "island": route["island"],
        "_true_kg": true_kg, "_ferry_out": wx["ferry_out"],
    }

def late_logit(p, ship):
    """Log-odds that a parcel misses its promised day. Weight counts in kilograms, whatever the column says."""
    dep, kg, km, nd = p["depot_id"], p["_true_kg"], p["distance_km"], p["service"] == "next_day"
    z = -4.24 + depot_effect(dep, ship) + 0.45 * p["driver_new"] + 0.3 * nd
    z += 0.2 * (p["ship_hour"] >= 17) + (1.3 if nd and p["ship_hour"] >= 18 else 0.0)   # the 18:00 trunk cut-off
    z += 1.5 * (p["address_quality"] < 0.72)                                       # an address a driver cannot find
    z += 0.9 * (kg > 15) + (0.7 if p["rural"] and km > 45 else 0.0)                # two-person parcels, long rural legs
    z += (1.6 if p["rural"] else 0.5) * (1 - math.exp(-p["rain_mm"] / 3))          # rain: quick to hurt, then levels off
    z += 0.08 * max(0, p["stops_on_route"] - 125)                                  # only an overloaded route slows
    z += 0.06 * max(0.0, p["wind_kph"] - 35) * (2.5 if p["island"] else 1.0)       # wind matters most at sea
    z += 0.8 * (ship.weekday() == 0 and dep in ("DAR", "MAN", "LEI", "LDS"))       # Monday backlog at four hubs
    z += p["bank_holiday"] * (0.3 + 0.025 * min(km, 60))                           # a holiday hurts long routes most
    return z + (2.2 if p["_ferry_out"] and p["island"] else 0.0)                   # ferries: a cause with no column


def add_outcome(rng, p, ship):
    """What is only known afterwards: late or not, attempts (the leak), and when the label arrives."""
    late = rng.random() < 1 / (1 + math.exp(-late_logit(p, ship)))
    promised = date.fromisoformat(p["promised_date"])
    delivered = add_days(promised, (1 + (rng.random() < 0.3)) if late else 0)
    label_ready = delivered + timedelta(days=1)            # delivery scans are reconciled overnight
    known = label_ready <= DATA_AS_OF
    p["attempts"] = (1 + (rng.random() < (0.55 if late else 0.04)) + (late and rng.random() < 0.2)) if known else None
    p["delivered_date"] = delivered.isoformat() if known else None
    p["late"] = int(late) if known else None
    p["label_ready_date"] = label_ready.isoformat()
    for k in ("_true_kg", "_ferry_out"):
        del p[k]
    return p

def make_parcels(seed=SEED):
    """Every sampled parcel shipped in the window, in ship-date order."""
    rng = random.Random(seed + 3)
    by_depot = {}
    for r in ROUTES.values():
        by_depot.setdefault(r["depot_id"], []).append(r)
    rows, n, d = [], 1, WINDOW[0]
    while d <= WINDOW[1]:
        per_day = round(FLEET["parcels_per_day"] * FLEET["sample_rate"] * DOW[d.weekday()])
        shares = shares_on(d)
        for dep, share in shares.items():
            for _ in range(round(per_day * share)):
                p = parcel_row(rng, n, d, rng.choice(by_depot[dep]))
                rows.append(add_outcome(rng, p, d))
                n += 1
        d += timedelta(days=1)
    return rows


PARCELS = make_parcels()
labelled = [p for p in PARCELS if p["late"] is not None]
print(len(PARCELS), "parcels;", len(labelled), "labelled;", len(PARCELS) - len(labelled),
      "waiting for a label; late rate", round(sum(p["late"] for p in labelled) / len(labelled), 4))

147444 parcels; 144450 labelled; 2994 waiting for a label; late rate 0.0866

SAY = {   # intent: ways customers put it ({p} parcel id, {d} a day, {t} a town)
    "where_is_my_parcel": ["where is {p}", "any update on {p}", "tracking for {p} hasn't moved since {d}", "is {p} still coming {d}",
                           "no tracking info for {p}", "has {p} left the {t} depot yet", "when will {p} arrive",
                           "the app just says in transit for {p}", "can you tell me where {p} is", "what time is {p} coming {d}"],
    "delivery_late": ["{p} was due {d} and still nothing", "{p} is late again", "third day waiting for {p}",
                      "{p} missed its delivery day", "promised {d}, still not here", "why is {p} always late",
                      "{p} should have come {d}", "still waiting for {p}, it's overdue", "you said {d} for {p}. it is now late"],
    "change_delivery": ["can {p} be left with a neighbour", "please redeliver {p} to my work in {t}", "can you hold {p} at {t}",
                        "change the address for {p}", "can I collect {p} from the depot", "leave {p} in the porch please",
                        "can {p} come {d} instead", "I'm away, please don't deliver {p} {d}", "send {p} to my mum's in {t}"],
    "damaged": ["{p} arrived crushed", "the item in {p} is broken", "{p} came open and something is missing",
                "{p} looks like it was dropped", "{p} was soaked through", "the contents of {p} are smashed",
                "box for {p} was ripped and taped up", "got {p} {d} but the screen is cracked"],
    "compliment": ["the driver for {p} was lovely", "{p} came early, great service", "thanks for getting {p} to {t} so fast",
                   "really helpful driver {d}", "brilliant service as always", "the driver carried {p} upstairs, thank you"],
}
VAGUE = ["what is going on with {p}", "{p}??", "still nothing {d}", "can someone call me about {p}", "not impressed with {p}",
         "about {p}", "this is the second time with {p}", "re {p}"]   # no clear intent: annotators have to guess
OPEN = ["", "", "", "Hi,", "Hello", "hiya", "Morning.", "Dear Kestrel,", "hey", "Good afternoon,"]
EXTRA = ["I took the day off for this.", "It's a birthday present.", "The app says out for delivery.", "nobody knocked",
         "This is the second time.", "The driver left a card.", "I've emailed twice already.", "I'm out {d}.", "it's medicine"]
SIGN = ["", "", "", "Thanks", "thx", "Cheers", "Not happy.", "pls sort this", "Regards", "ta"]
SHORT = {"please": "pls", "you": "u", "tomorrow": "tmrw", "thanks": "thx", "parcel": "parcle", "delivery": "delivry",
         "today": "2day", "because": "cos", "for": "4", "are": "r"}   # what phone keyboards and thumbs do
NEAR = {"where_is_my_parcel": "delivery_late", "delivery_late": "where_is_my_parcel", "change_delivery": "where_is_my_parcel",
        "damaged": "delivery_late", "compliment": "change_delivery"}   # the intent a tired annotator slips to
TOWNS = ["Leicester", "Walsall", "Salford", "Wakefield", "Bath", "Gravesend", "Paisley", "Nairn", "Rotherham"]
DAYS_SAID = ["today", "tomorrow", "on Saturday", "on Monday", "this morning", "yesterday", "on the 14th", "last week"]

def scruff(rng, text):
    """Abbreviations, swapped letters and missing capitals, as people type on a phone."""
    out = []
    for w in text.split():
        if w.lower() in SHORT and rng.random() < 0.25:
            w = SHORT[w.lower()]
        elif len(w) > 5 and rng.random() < 0.04:
            k = rng.randrange(1, len(w) - 2)
            w = w[:k] + w[k + 1] + w[k] + w[k + 2:]
        out.append(w)
    return " ".join(out).lower() if rng.random() < 0.3 else " ".join(out)


def make_messages(seed=SEED, n=1200):
    """Simulated customer messages. Two annotators label each; they disagree on some, as people do."""
    rng, names, out = random.Random(seed + 4), list(SAY), []
    late_ids, all_ids = [p["parcel_id"] for p in PARCELS if p["late"] == 1], [p["parcel_id"] for p in PARCELS]
    for i in range(n):
        intent = rng.choices(names, weights=[30, 25, 20, 15, 10])[0]
        kind = rng.choices(["clear", "mixed", "vague"], weights=[74, 15, 11])[0]
        other = NEAR[intent] if rng.random() < 0.6 else rng.choice([x for x in names if x != intent])
        pid = rng.choice(late_ids if intent == "delivery_late" else all_ids)
        core = [rng.choice(VAGUE)] if kind == "vague" else [rng.choice(SAY[intent])] + [rng.choice(SAY[other])] * (kind == "mixed")
        rng.shuffle(core)
        parts = [rng.choice(OPEN), *(c + rng.choice([".", "", "!", "?"]) for c in core)]
        parts += rng.sample(EXTRA, rng.choice([0, 0, 1, 1, 2, 3])) + [rng.choice(SIGN)]
        said = pid if rng.random() < 0.75 else rng.choice(["my parcel", "my order", "it"])
        text = scruff(rng, " ".join(x for x in parts if x).format(p=said, d=rng.choice(DAYS_SAID), t=rng.choice(TOWNS)))
        if rng.random() < 0.06:   # personal data a later lesson must redact (reserved ranges only)
            text += f" Call me on 07700 900{rng.randint(100, 999)} or email c{i}@customer.example"
        a, b = (rng.choice([intent, other]) if kind != "clear" else NEAR[intent] if rng.random() < slip else intent
                for slip in (0.05, 0.12))   # annotator a slips on 5% of clear messages, b on 12%
        out.append({"message_id": f"M{i + 1:04d}", "parcel_id": pid, "text": text, "label_a": a, "label_b": b})
    return out


MESSAGES = make_messages()
print(len(MESSAGES), "messages;", sum(m["label_a"] != m["label_b"] for m in MESSAGES), "annotator disagreements;",
      sum("07700" in m["text"] for m in MESSAGES), "contain a phone number")

1200 messages; 301 annotator disagreements; 72 contain a phone number

from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import cohen_kappa_score, f1_score

a, b = [m["label_a"] for m in MESSAGES], [m["label_b"] for m in MESSAGES]
print("kappa between the annotators", round(cohen_kappa_score(a, b), 3))
order = list(range(len(MESSAGES)))
random.Random(0).shuffle(order)                     # the same 80/20 split Module 4 lesson 3 uses
train, test = order[:960], order[960:]
tfidf = TfidfVectorizer(ngram_range=(1, 2), sublinear_tf=True)
X_train = tfidf.fit_transform([MESSAGES[i]["text"] for i in train])
clf = LogisticRegression(max_iter=2000).fit(X_train, [a[i] for i in train])
guess = clf.predict(tfidf.transform([MESSAGES[i]["text"] for i in test]))
print("TF-IDF and logistic regression, macro F1 on 240 held-out messages against label_a",
      round(f1_score([a[i] for i in test], guess, average="macro"), 3))

kappa between the annotators 0.672
TF-IDF and logistic regression, macro F1 on 240 held-out messages against label_a 0.855

import hashlib
import json


def fingerprint(*datasets):
    """The first 12 hex digits of a SHA-256 hash of the data: equal fingerprints mean identical data."""
    blob = json.dumps(datasets, ensure_ascii=False, sort_keys=True, default=str).encode("utf-8")
    return hashlib.sha256(blob).hexdigest()[:12]


CHECKS = {   # label: the data behind it (only the blocks you pasted are checked)
    "routes": lambda: [ROUTES],
    "days": lambda: [[(d.isoformat(), dep, v) for (d, dep), v in DAYS.items()]],
    "parcels": lambda: [PARCELS],
    "messages": lambda: [MESSAGES],
    "all": lambda: [DEPOTS, FLEET, ROUTES, PARCELS, MESSAGES],
}
for label, data in CHECKS.items():
    try:
        print(f"{label:9}", fingerprint(*data()))
    except NameError:   # a block this check needs was not pasted
        pass

routes    3167417f391b
days      80a1703dc861
parcels   40ba9d4eaca4
messages  ba9d7ac7fe4f
all       f0423440d615

import pandas as pd

df = pd.DataFrame(PARCELS)
for c in ("ship_date", "promised_date", "delivered_date", "label_ready_date"):
    df[c] = pd.to_datetime(df[c])
print(df.shape[0], "rows,", df.shape[1], "columns:", ", ".join(df.columns))

147444 rows, 22 columns: parcel_id, ship_date, promised_date, depot_id, route_id, service, customer_type, ship_hour, weight_kg, distance_km, stops_on_route, address_quality, rain_mm, wind_kph, bank_holiday, driver_new, rural, island, attempts, delivered_date, late, label_ready_date

lab = df[df["late"].notna()]
print("rows", len(df), "| labelled", len(lab), "| waiting", df["late"].isna().sum(),
      "| first unlabelled ship date", df.loc[df["late"].isna(), "ship_date"].min().date())
by_depot = lab.groupby("depot_id")["late"].mean().round(3).to_dict()
print("late rate", round(lab["late"].mean(), 4), "| by depot", by_depot)
print("island late rate", round(lab.loc[lab["island"], "late"].mean(), 3), "on", int(lab["island"].sum()),
      "parcels | elsewhere", round(lab.loc[~lab["island"], "late"].mean(), 3))
print("late rate by attempts (the leak):", lab.groupby("attempts")["late"].mean().round(3).to_dict())
before = df["ship_date"] < pd.Timestamp(EVENTS["scanner_v4"])
print("median weight_kg before and after", EVENTS["scanner_v4"], ":", df.loc[before, "weight_kg"].median(),
      df.loc[~before, "weight_kg"].median())
don = lab[lab["depot_id"] == "DON"].groupby(lab["ship_date"].dt.to_period("W"))["late"].agg(["size", "mean"])
print("Doncaster by week (parcels, late rate):", [(int(s), round(float(m), 3)) for s, m in don.values])
print("bank-holiday parcels", int(df["bank_holiday"].sum()), "| late rate",
      round(lab.loc[lab["bank_holiday"], "late"].mean(), 3))

rows 147444 | labelled 144450 | waiting 2994 | first unlabelled ship date 2026-09-22
late rate 0.0866 | by depot {'BHM': 0.06, 'BRS': 0.058, 'DAR': 0.107, 'DON': 0.162, 'GLA': 0.078, 'INV': 0.173, 'LDS': 0.065, 'LEI': 0.091, 'MAN': 0.07}
island late rate 0.265 on 2645 parcels | elsewhere 0.083
late rate by attempts (the leak): {1.0: 0.034, 2.0: 0.561, 3.0: 1.0}
median weight_kg before and after 2026-09-07 : 1.82 1830.0
Doncaster by week (parcels, late rate): [(105, 0.086), (433, 0.155), (761, 0.162), (982, 0.17), (982, 0.172), (982, 0.155), (719, 0.161)]
bank-holiday parcels 5134 | late rate 0.167