Validation methodology — Miami-Dade (closure track, outcomes, residual-z, survey)

Per-metric definitions, validation results, and known gaps for the enrollment / capacity / spending metrics behind /miami/methodology/analysis/enrollment. Mirrors verify/METHODOLOGY.md (NYC) and pipeline_philly/verify/METHODOLOGY.md in shape. The four checks are defined in docs/cities/miami/05_validation_spec.md.

Results — 2026-09-15 run (python -m pipeline_miami.verify.run_all)

Verdict: PASS (docs/qa_reports/miami/__enrollment_full_qa.json).

(ii) Base case — 12 components, zero mismatches

Tolerance is exact (0.0) for every component: these are counts and published percentages, not estimates.

(i) Completeness — PASS

Every Dade school row in each membership file is served and every served cell exists in the file (491 → 521 schools per year). Two active district-run schools in the MSID have no 2025-26 count (listed in __completeness.md); they are new numbers without membership yet.

(iii-b) Cross-publisher — PASS

FLDOE October membership vs the NCES CCD copy: 1,018 school-years, 98.3% exactly equal (2023-24: 518 of 518; 2018-19: 483 of 500, all within 2%). CCD carries 8–13 numbers per year that the FLDOE file does not (special programs the state reports under other numbers). Verdict rule: ≥95% exact.

(iv) Computed values — PASS

utilization_permanent_pct (1,311), enrollment_change_5yr_pct (2,330), k_to_g5_ratio (2,790), students_per_teacher (474) recomputed from the served inputs in Python; zero mismatches.

Outcomes track — 11 components, zero mismatches (docs/qa_reports/miami/__outcomes_validation.md)

Reported separately from the closure-track verdict (track: outcomes in components.yaml); it does not gate the enrollment page. Every component is an exact (ii) re-read of the source file with code that shares nothing with the loader. "Suppressed" counts cells where both sides agree the publisher withheld the value.

Outcomes track — cross-publisher and model checks

• (iii-b) Absenteeism, FLDOE vs EDFacts (2022-23) — cross_publisher_absenteeism.py. The federal DG814 count is K-12 only (findings F.14), so the exact comparison is made on the 298 schools with no October PK membership: 247 exact, 284 within ±1 (95.3%; the federal perturbation), verdict PASS. At the 209 schools with PK the federal count is lower by 0.66 students per PK student (r = 0.86), reported as a regression rather than a mismatch.
• (iii-b) Race shares, FLDOE vs NCES CCD (2018-19, 2022-23, 2023-24) — cross_publisher_race.py. The served shares come from the state's suppressed race file with hidden cells allocated by the rule measured before adoption (F.15). Pass rule fixed in advance: |served − CCD| within the per-school process bound min(9 × hidden cells, unallocated) ÷ total + 0.5 pp for ≥ 99% of school-years, per share. A first, cruder rule (95% within 2 pp) came in at 87–90% and is now reported as information only. Result: 100% of 1,533 school-years per share within the bound (PASS); 82–87% within 2 pp; median Δ 0. docs/qa_reports/miami/__cross_publisher_race.md.
• Residual-z checks — residual_checks.py. R1: every outcome × year is refitted from the served inputs by a second solver (weighted normal equations on centred columns, against the engine's scaled least squares); max |Δz| 3.5 × 10⁻¹¹ over 46 fits once the per-cell CSV was written at full precision (a first run at six significant digits showed 5 × 10⁻⁶). R2: every served residual_z equals the committed CSV, no cell on one side only. R3: all z finite, flagged share below 50% (max 10.3%), at least 30 eligible cells per fit (min 83). Verdict PASS.
• Survey composites (ii) — independent source readers reconstruct favorable shares (agree for positive items, disagree for negative items) and treat zero-total response profiles as missing. They cover long-format sheets and the 2021–22 pivot caches. The committed item crosswalk is shared, so these tests validate implementation, not independent item selection. survey_source_check.py compares all four domains across ten independently mapped workbook layouts; per-metric served-vs-source reports are listed in components.yaml.

Per-metric definitions

• enrollment_oct — Survey 2 (October) headcount, all grades, from FLDOE's Membership by District and School by Grade. Total taken from the file's total sheet; where a grade cell carries */**, the loader keeps it suppressed unless the numeric grade cells already sum to the published total (then the token marks a grade not served and is stored as 0). Documented in scripts/loaders/miami/membership.ts.
• enrollment_oct_ccd — CCD "Education Unit Total" for the same date; loaded only as the cross-publisher reference.
• fish_capacity_school / fish_capacity_permanent / cofte / utilization_school_capacity_pct — the four numeric columns of the FISH Level of Service report, parsed from PDF with a two-parser gate (pipeline_miami/parse/fish_los.py); the state's utilization is COFTE ÷ school capacity. School numbers attached by name (exact / fuzzy / seven documented overrides); a number that maps to two facilities keeps the larger-capacity one.
• utilization_permanent_pct — derived: enrollment_oct ÷ fish_capacity_permanent for the same year; for 2025-26 (no state report yet) the latest FISH permanent capacity is used (325 schools), else the board book (1), else the GIS layer (3). The fallback counts are in the derived load's notes.
• enrollment_abc, fish_capacity_permanent_abc, utilization_permanent_pct_abc, projected_enrollment_y1/_y2 — the board's own capacity blocks for the 29 schools in the 2026-27 Attendance Zone Recommendations; arithmetic gate (printed % = enrollment ÷ capacity) passes on all 69 checks.
• per_pupil_expenditure_* — FLDOE ESSA school per-pupil expenditure columns, positional.
• teacher_fte, students_per_teacher — CCD school staff file (2023-24), and its ratio to enrollment_oct.
• enrollment_gis, fish_capacity_permanent_gis — the county layer's two fields, stored under 2024-25 (vintage inferred; docs/cities/miami/findings.md M.5).

Per-metric definitions — outcomes (P1)

• ela_achievement, math_achievement, science_achievement, social_studies_achievement, learning_gains_*, middle_school_acceleration, school_grade_points_pct, school_grade_letter_index, pct_econ_disadv — the component columns of FLDOE's School Grades workbook, one file per year (2018-19, 2021-22 → 2024-25; no grades were issued in 2019-20 or 2020-21). Every sheet is read (2022-23 ships one sheet per school type). The letter is stored as an index A=4 … F=0; blank component cells are stored as suppressed.
• fast_{ela,math}_g{3..10}_proficiency, science_g{5,8}proficiency, eoc{alg1,geometry,biology,civics,ushistory}_proficiency — "Percentage in Level 3 or Above" from the spring State Report of Schools file for that subject × grade, with "Number of Students" as the denominator. All students only (F.5). District and school columns are located by header text, not position (F.13).
• graduation_rate_4yr — the federal uniform four-year rate, total and by race / category subgroup, from the FLDOE graduation-rate workbook; rows keyed to a virtual-provider number are skipped.
• chronic_absenteeism_rate / absent_21plus_rate — the "absent 10% or more of days enrolled" and "absent 21+ days" shares from the two FLDOE attendance files, stored as percentages (the file's fractions × 100).
• attendance_rate — ADA ÷ ADM from the ADA/ADM file.
• pct_ell — exact English-learner share only when the source identifies the total; otherwise suppressed. pct_ell_lower_bound / pct_ell_upper_bound retain the range allowed by race-cell censoring. The model and peers use the named lower endpoint; the residual packet also refits at the upper endpoint on the same schools.
• sesir_*_per_100 — SESIR incident counts per 100 October students (total, violence, weapons, drugs, bullying categories as regexes over the incident-type column); unsuppressed counts (F.10).

Per-metric definitions — covariates, residual-z, survey

• pct_black … pct_two_or_more — shares of October membership from FLDOE's Membership by School by Grade by Race for every outcome year. Hidden cells (*/**, under 10 students) are allocated by splitting the school's exact unallocated count equally over its hidden cells after dropping hidden cells in grades whose by-grade total is already fully visible (zeros); blanks are grades not served. Measured error against the unsuppressed CCD copy: mean 0.8 pp on the Black and Hispanic shares in 2018-19 and 2023-24, 2.1–2.4 pp in 2022-23 where * also marks zeros (F.15). The CCD loader no longer writes shares.
• fitted / residual / residual_se / residual_z / outlier_flag / persistent_dir / persistent_n / residual_n — additive columns written by scripts/loaders/miami/residual_z.ts from pipeline_miami/analysis/residual_z.py: WLS of the outcome on same-year covariates (config/covariates.yaml), weights and sampling N from config/outcomes.yaml (n_rule), z = residual ÷ √(τ² + se²), where τ² is the residual variance net of the modelled sampling term, flags at |z| ≥ 2 oriented so positive is good, persistence 2 of the last 3 fitted years within a comparability regime (config/comparability.yaml, boundaries plus excluded_years). Descriptive, not causal.
• survey_{students|parents|staff}_{safety|leadership|teaching|resources} — mean favorable response share over the domain's core items (asked in every survey year for that group), agree on positive items and disagree on negative items; unknown responses receive no favorable credit and zero-total response profiles are missing, at least half the core items unsuppressed; denominator = responses. survey_*_recommend, survey_*_grade_ab, survey_*_response_rate — the workbook's school-level yes share, A + B share, and responses ÷ eligible where both are published. Normaliser: pipeline_miami/parse/climate_survey.py; crosswalk: data/cities/miami/reference/survey_items.csv.

Known gaps

• The FISH parser-A re-read keys facilities by the first text line of the name; 3 facilities per year share a first line with another facility (e.g. two campuses), so their served cells cannot be matched by that key and appear as served-only. Parser B (position-aware) is the loaded value; the gate compares A and B positionally at parse time and passes.
• No state FISH report exists yet for 2025-26; the derived utilization for that year uses 2024-25 capacity.
• Per-pupil expenditure files before 2021-22 have not been located under a guessable name.
• Outcome coverage in the harness is eleven components (one or more years each), not every metric × year: School Grades (ELA, math, economically disadvantaged share), both absenteeism definitions, graduation, and five SRS files spanning the FAST, science and EOC layouts. The remaining SRS files share one loader and one reader; School Grades components share one column-prefix reader.
• CRDC is fetched but not read by the harness; the outcomes track's cross-publisher checks are absenteeism (EDFacts) and race shares (CCD).
• Race shares are estimates in the presence of suppression. The current 2022–23 rule uses an adjacent-year prior; its measured error is reported in __cross_publisher_race.json. A process-bound check establishes consistency with the hidden counts, not estimation accuracy.
• The independent survey reader re-reads all three 2021–22 pivot caches. The staff label-offset diagnosis is still a documented inference from adjacent-year alignment; readers sharing that assumption do not independently prove it.
• The tested-N used as residual-z weight for School Grades components is October membership in the tested grades, not the tested count.
• The events table is hand-curated from the 2026-27 board book and the August 2026 letters; earlier boards' actions (2019-20, 2024-25 books) are fetched but not yet entered.