Branch-month panels and the rollout clock

Last updated: 5 Oct 20265 min read

tutorial

A rollout panel contains one outcome per stable unit and period, plus the first period that unit was exposed to the intervention.

Choose the observational unit

Suppose a support organization introduces a new triage screen branch by branch. The outcome is the monthly rate of cases breaching a service target, measured from cases created in each month. One row represents one branch and one arrival month. Counting activity events instead would give busy branches more rows without changing the number of rollout units. Define the eligible case population, denominator and reporting cutoff before assembling the panel. Grain and cardinality guard the join.

Record first exposure, not latest configuration

A branch receives the screen on a particular month. Store the first month the branch actually used it and retain the operational evidence for that date. A current configuration flag joined backward makes pre-rollout months appear treated. The teaching audit below derives treatment from a fixed adoption map and rejects a panel row that claims exposure before adoption. If a branch later disables the screen, the absorbing-treatment design no longer fits; record the stop and choose a different analysis.

Make the calendar explicit

A missing branch-month can mean no eligible cases, delayed ingestion, a closed branch or a broken extraction. Those states are not interchangeable with a measured zero breach rate. The audit requires a complete set of requested periods for each branch; a production dataset can instead document justified exclusions and their effect on the estimand. A branch entering after the study began has no pre-period history for early adoption comparisons. Cohort entry matters here too.

Separate assignment and measurement clocks

A rollout approved on the twentieth may first affect arrivals on the twenty-first, while the monthly outcome mixes earlier and later cases. Define whether that month is a partial-exposure transition to exclude, split or model. A status correction entered later should not silently change the historical adoption date. Freeze outcome extracts and policy logs for each analysis version.

Check support before estimating

Tabulate how many branches adopt in each period, how many never adopt, and which months are available both before and after each adoption. An effect for the earliest cohort three months later needs comparison branches still untreated at that later month. A regression cannot create that support. Cohort-time contrasts use this panel after it passes the clock checks.

Implementation

def audit_branch_panel(panel_rows, first_use_month, required_months):
    expected = {(branch_id, month)
                for branch_id in first_use_month for month in required_months}
    observed = set()
    for branch_id, month, breach_rate, treated_flag in panel_rows:
        key = (branch_id, month)
        if key in observed or branch_id not in first_use_month:
            raise ValueError("duplicate row or unknown branch")
        if not 0 <= breach_rate <= 1 or treated_flag not in (0, 1):
            raise ValueError("invalid metric or exposure")
        adoption = first_use_month[branch_id]
        expected_flag = int(adoption is not None and month >= adoption)
        if treated_flag != expected_flag:
            raise ValueError("exposure contradicts first-use month")
        observed.add(key)
    if observed != expected:
        raise ValueError("missing or extra branch-month")
    return {"branches": len(first_use_month), "rows": len(panel_rows)}

adoption = {"North": 3, "West": None}
panel = [("North", 1, .18, 0), ("North", 2, .17, 0),
         ("North", 3, .12, 1), ("West", 1, .16, 0),
         ("West", 2, .15, 0), ("West", 3, .15, 0)]
assert audit_branch_panel(panel, adoption, [1, 2, 3]) == {
    "branches": 2, "rows": 6}

Performance and operating cost

Checking R rows and B branches across M required months costs O(R + B × M) expected time and O(R + B × M) space for key sets. Large panels should enforce a unique branch-period key at ingestion and retain a separate audit of missing cells.

Common Mistakes

Do not backfill the current treatment flag into pre-rollout months.
Do not turn an absent branch-month into a zero outcome.
Do not call a partially exposed transition month fully treated without a stated rule.