nyc311

What It Is

nyc311 is a typed Python toolkit for turning NYC 311 service-request data into reproducible complaint-intelligence outputs. It pairs a CLI with a composable SDK so the same workflow runs in batch jobs, scripts, notebooks, and downstream packages.

Why It Matters

311 records are a strong public signal for neighborhood quality of life, but usable detail sits in short descriptor text and inconsistent geography fields. This package makes that pipeline explicit, testable, and exportable for analysis, reporting, and mapping.

What Ships in 0.3

Core pipeline — load from local CSV or the live Socrata API, topic-label by keyword rules across nine high-volume complaint types, aggregate by borough or community district, and export CSV tables, boundary-backed GeoJSON, and markdown report cards.

Statistical modeling — interrupted-time-series (ITS), PELT changepoints, STL decomposition, Moran's I / LISA spatial autocorrelation, panel fixed/random-effects regressions, synthetic control, staggered difference-in-differences, event-study plots, and regression discontinuity (RDD). Spatial econometrics include spatial lag/error models and geographically weighted regression (GWR).

Equity analysis — Oaxaca-Blinder decomposition, Theil index, reporting-rate adjustment, and latent reporting-bias EM estimation.

Factor pipeline — domain-specific factors (ComplaintVolumeFactor, ResponseRateFactor, TopicConcentrationFactor, EquityGapFactor, SpatialLagFactor) via nyc311.factors.

Temporal infrastructure — balanced panel datasets, treatment-event modeling, and inverse-distance spatial weights via nyc311.temporal.

SDK namespaces: models, io, analysis, geographies, export, pipeline, samples, factors, temporal, stats, presets, and optional dataframes, spatial, plotting, science.

Install extras: pip install "nyc311[all]", [dataframes], [spatial], [plotting], [science], [stats], or [bayes] (BYM2 via PyMC).

Two research case studies ship under examples/: Rat Containerization (81K rodent complaints across 70 community districts) and Resolution Equity (1M requests with Oaxaca-Blinder, spatial autocorrelation, ITS, and bias estimation).

Ecosystem Fit

nyc311.geographies is the 311-facing layer over nyc-geo-toolkit. The examples/about-the-data folder walks the public datasets, column expectations, and how the package interprets them.