# 00 — Overview ## 1. Why Philadelphia Philadelphia is structurally **simpler** than NYC (one school district instead of 32 community districts; ~300 schools instead of ~1,800) and has data sources that are **as good or better** than NYC's on every axis the current platform exercises. The same analytical machinery — peer groups, residual-z outliers, comparability regimes, the four-check verification harness — drops in once the source layer is rewritten. The civic case: the District publishes a serious official report (SPREE) and the state publishes a comparable accountability index (Future Ready PA Index), so there is a **reference point to validate against and improve on** — same posture as the NYC build vs. NYC's School Quality Snapshot. ## 2. Scope (v1) - **Universe:** School District of Philadelphia district schools + Philadelphia-located brick-and-mortar charter and Renaissance Charter schools (≈210 + ≈85). Cyber charters are **out of scope for v1** (they serve students statewide; attribution to Philly is conceptually fuzzy). They're addable as a tagged subset in v2. - **Outcomes:** PSSA grades 3–8 ELA & Math proficiency, Keystone HS subjects (Algebra I, Literature, Biology), four-year graduation rate, chronic absenteeism. Survey climate via the Philly School Experience Survey (PSES). - **Geography taxonomy:** SDP Learning Network (replaces NYC's community-district concept), Philly City Council district, neighborhood (Census tract aggregations from OpenDataPhilly), school type, admission category, grade band. - **Methodology:** lift KX's spec verbatim — peer groups KNN(K=40) with hard filters on grade band + admission category, soft demographic distance; residual-z outliers (WLS on the spec's covariate set); comparability regimes for PSSA test-version changes. - **Out of scope for v1:** statewide comparisons (Philly vs. suburban PA), per-pupil funding (same gap as NYC — patchy data), principal-tenure analytics (same gap). ## 3. Decisions (settled 2026-06-03) All seven open decisions resolved. Recording with rationale so the reasoning is recoverable later. | # | Decision | Resolution | Notes | |---|---|---|---| | O.1 | **Same repo vs new repo** | **Same repo (multi-city namespace).** Repo also **renamed `nyc-edu-data` → `edu-data`** to reflect multi-city scope. | GitHub auto-redirects old URLs ~6 months. Vercel deploy wiring (installation ID, not URL) survives the rename. Philly code lives under `docs/cities/philly/`, `pipeline_philly/`, `data/cities/philly/`, and `philly/*` branches. NYC code paths stay single-tenant until shared infrastructure is genuinely needed. | | O.2 | **Charter inclusion model** | **(a) — one universe, tagged.** | Matches PDE's data shape (district + charter on same grain) and NYC's posture. `school_type` enum follows PDE's 5-value taxonomy (regular/charter/compctc/cyber/specialed) per `findings.md §F.5`; `is_renaissance` is a derived boolean. | | O.3 | **SDP's SPREE role** | **(c) — both.** Cross-referenced ranking *and* (iii-a) spot-check oracle. | Mirrors NYC's posture with the School Quality Snapshot. Same-publisher caveat applies (presentation cross-reference, not independent oracle). Independent (iii-b) oracle is Future Ready PA Index, available day one. | | O.4 | **PSSA test-version regimes** | **Two regime breaks: 2014-15 (PA Core redesign) and 2022-23 (post-COVID recalibration).** Standardized z within regime; raw values across. | Same comparability posture as NYC's 2022-23 handling. Encoded in `comparability.yaml` during P3. | | O.5 | **Keystone aggregation rule** | **Latest-attempt, all-students, banded by school grade band.** | Matches PDE's published convention. Encoded in `outcomes.yaml`. | | O.6 | **PSES survey rollup scope** | **Teacher + student as first-class rollups; parent + principal + support-staff as school-profile detail.** Loader still ingests all 5 respondent groups into `survey_responses`. | Avoids UX bloat from 5 top-line survey metrics; mirrors NYC's two-first-class posture. | | O.7 | **PVAAS growth as first-class v1 indicator** | **Yes — include in v1.** | Future Ready exposes PVAAS growth per subject × subgroup (per `findings.md §F.2`). NYC didn't have this; status-vs-growth methodology question is settled here by data availability. Metric naming: `pvaas_growth_*`. | | O.8 | **Actual vs Acct population cut for SDP PSSA** | **Acct as canonical** (matches SDP's published SPREE composite). Loader ingests both files; the primary metric value comes from `*_Acct_*.csv`; a parallel `_actual` exposes the all-tested cut for transparency. A per-school "Acct vs Actual" diff report runs at ingest time as an additional reconciliation gate (analogous to a population-cut variant of the (ii) base case). | Same gap NYC has — Philly just publishes both cuts natively, so we don't have to reverse-engineer the accountability cohort. See `05_validation_spec.md §"Acct vs Actual"` for the validation posture. | ## 4. Inheritance from NYC build The Philly build reuses, without modification: - **Methodology spec** (`docs/design/nyc-school-outcomes-spec.md`) — engine, peer-group construction, residual-z math, comparability handling. - **Reference scaffold** (`docs/design/reference-scaffold/`) — `pipeline/analysis/engine.py`, `outliers.py`, `trends.py`, `verify/{checks,reconcile}.py`, configs. - **Validation taxonomy** (`docs/design/05_validation_spec.md`, `verify/METHODOLOGY.md`) — (i)–(iv) definitions. - **Front-end shape** — Outliers / Movers / Stories / school profiles, with the same direction-adjusted percentile semantics, peer-group toggles, and recipes infrastructure. - **Contribution workflow** — branch-per-capability, additive + feature-flagged, PR linked to gap analysis and spec. What is **new and Philly-specific**: - Source connectors (Philly publishes via OpenDataPhilly Socrata + Future Ready PA Index Excel downloads + PDE bulk files; no NYCDOE InfoHub equivalent). - Geography taxonomy (Learning Networks instead of community districts). - The eight known story lines (charter-sector comparison, Mastery/Renaissance trajectory, school-closure retrospective on Hite's 2013 closures, etc.) replace NYC's Renewal / Small Schools / D15 stories. ## 5. Out-of-band: what this branch does NOT include - Any ingested Philadelphia data — not even sample rows. Until the open decisions land, the source connectors are unwritten. - Any code change to NYC paths. Everything is under `docs/cities/philly/`. - A decision about repo split (O.1). The plan documents are written so they apply equally to "same repo, new namespace" and "new repo, copy-then-modify." ## 6. Next step Decisions settled 2026-06-03; work proceeds from `03_integration_plan.md`. First-fetch (P1 prelim) shipped on `philly/first-fetch` — two Future Ready sources resolved. Next batch: PSES + SPREE + OpenDataPhilly discovery, then P0 scaffolding under same-repo conventions.