An open, uncertainty-aware platform for exploring small-area (census-tract) community indicators across the 14-county Charlotte region (11 NC + 3 SC counties; ~752 2020 census tracts). The app renders interactive choropleths, trends, and spatial analyses entirely in the browser from a static, versioned data contract.
Stack: SvelteKit (Svelte 5 runes) · MapLibre GL · static prerendered data · @sveltejs/adapter-static.
- Choropleth explorer with quantile class breaks held consistent across years, an interactive legend that filters the map, and a year slider.
- Uncertainty, first-class. Estimates carry a 90% margin of error (band on the trend), a reliability flag (ok / caution / unreliable from the coefficient of variation), and an optional on-map hatch for unreliable tracts. County values are the authoritative published county estimate (ACS county tables / CDC PLACES county / county zonal); the region is correctly pooled (sum, pooled rate, or population-weighted), with MOE carried through.
- Comparable-period change. 5- and 10-year change between non-overlapping ACS periods, with a significance test (so noise isn't read as change).
- Bivariate analysis — a 3×3 tercile choropleth plus a correlation scatter of standardized values (marginal distributions, regression line, Pearson + Spearman, two-way map↔dot hover), shown as descriptive only.
- Spatial clusters (LISA) — Local Moran's I with a without-replacement conditional-permutation null and Benjamini–Hochberg FDR control (computed in the data pipeline, shipped precomputed).
- Researched briefs — every indicator has a plain-language, cited "why this matters" brief with verified "Learn more" resources, plus an "About the data" provenance note.
- County profiles — one per county, with a real-polygon inset/locator map, a 14-county switcher, metric cards, social sharing, and a standard attribution footer.
- Custom reports — a printable multi-tract report, shareable on social media (selection encoded in the URL), with the same attribution footer. Approximate OpenStreetMap neighborhood names aid orientation.
- Find your neighborhood — search by street address (region-filtered typeahead) or use your current location to jump straight to your tract. Address lookup goes through a small serverless geocoding function; geolocation is resolved in the browser by point-in-polygon.
- Open-data downloads — per-indicator CSV and JSON, or the complete dataset as a prebuilt
.zip(refreshed on every build). - Navigation — indicators are listed alphabetically within each theme (Character separated from the Quality-of-Life dimensions); dropdowns are grouped into theme-colored sections.
- Provenance in context — source vintage plus model-based and pre-2020 harmonized badges.
/embed is a chrome-less, iframe-able choropleth page (no site header, nav, or footer),
driven by the same query params as /explore:
| Param | Meaning |
|---|---|
i |
indicator slug (unknown/absent falls back to the first indicator) |
y |
year (snaps to the latest year with data) |
geo |
tract or county |
z, lat, lng |
restored camera (malformed values are ignored → region fit) |
interactive=0 |
locks the view: no pan/zoom handlers, no nav/recenter controls |
nav=1 |
keeps the indicator side navigation (themes + indicators) inside the embed |
topnav=1 |
adds the site's top-nav bar (Explore/Indicators/Reports/Methods/About) without the logo or site name; links navigate inside the iframe, and the site keeps its brand hidden while framed |
?topnav=1 also works on every site page (/explore/, /indicators/, /county/<fips>/,
/methods/, /about/): the page renders with its normal top navigation but no logo or
site name, and nav links carry the flag forward — a brand-less embed view of the whole site.
When /explore/ runs inside a cross-origin iframe (e.g. the container site at
carolinasexplorer.com/map embeds it with ?topnav=1), the container can't read the
iframe's URL. So the app posts its state to the parent on every change, letting the container
mirror it into its own address bar and keep /map?… URLs shareable and deep-linkable:
window.parent.postMessage({ type: 'crxp:state', search: '?i=household-income&z=11' }, targetOrigin);searchis the user-facing query string with the leading?(empty string when there are no params). Embed-plumbing flags liketopnavare stripped — only indicator + map-position state reaches the container.- Embedded-only. Nothing is posted when
window.parent === window(standalone), so there is no behavioral or console change outside an iframe. - One message per distinct state, deduped, emitted whenever the selected indicator or the map
camera changes (it reacts to the same reactive source that writes the address bar, not
page.url—replaceStatedoesn't reactively updatepage.url). targetOriginis resolved from the parent origin (ancestorOrigins/document.referrer) against an allowlist —https://carolinasexplorer.com, Netlify deploy previews (https://<deploy>--<site>.netlify.app), andhttp://localhost:1111/http://127.0.0.1:1111(container dev server). A verified allowlisted origin is targeted exactly; otherwise it falls back to'*'(the payload is non-sensitive). An unverified origin is never targeted directly.- Emitter only. The container deep-links in by appending the query string to the iframe
src, which the app already restores from its URL on load — there is no inbound message listener. Contract and helpers live insrc/lib/embed-bridge.js.
The page shows the map, a top bar with the indicator + year and a "View full map ↗"
link (opens /explore/ with the embed's full query string), and the interactive legend
(hidden below 380 px viewport height). Cooperative gestures are on by default —
scrolling a host article over the map does not zoom it (Ctrl/⌘ + scroll zooms; drag pans).
Prerendered like the rest of the site; sets noindex.
<iframe
src="https://<host>/embed/?i=household-income&y=2020&z=9.5&lat=35.2271&lng=-80.8431"
width="800" height="450" style="border:0"
title="Carolinas Regional Explorer embed"></iframe>You don't need to hand-build these URLs: the Share / embed button on /explore
opens a dialog with the shareable link and a copy-able iframe snippet
(size presets + a static/no-interaction toggle). A user-facing how-to covering this app
and the well-being dashboard is in EMBEDDING.md. Design and implementation notes:
EMBED_1.md (camera-in-URL), EMBED_2.md (the /embed route),
EMBED_3.md (the Share/Embed dialog), EMBED_PHASES.md (roadmap).
65 indicators across 8 active themes — Character, Economy, Education, Engagement, Environment, Health, Housing, Transportation (Safety and Arts & Culture are not yet populated). Data come from the U.S. Census ACS 5-Year estimates (annual 2014–2024, 42 indicators), CDC PLACES (16 model-based health measures, including health-related social needs), the USGS National Land Cover Database (incl. Tree Canopy Cover), and EOG VIIRS nighttime lights.
The data is produced by a separate, open data pipeline and delivered to this app as the static contract in
static/data/ (see below). This repository contains the application only.
npm install
npm run dev # http://localhost:5173
npm run test # vitest
npm run check # svelte-checknpm run build # validate the data contract + prebuild downloads + prerender
npm run build:full # + OG cards + sitemap (production)
npm run previewbuild runs build:data (contract validation) and build:zip (prebuilds the per-indicator CSVs and the
crxp-data.zip download artifact under static/downloads/, git-ignored) before the Vite prerender.
Deployed as a static site on Netlify (netlify.toml: npm run build:full, publish dir build/).
No server or database at runtime. Non-prerendered routes fall back to 404.html (adapter-static).
Two Quarto documents are rendered and published to GitHub Pages by a GitHub Actions workflow on push:
- Application technical documentation (
docs/app-technical-documentation.qmd) — architecture, components, routes, the data contract, and maintenance. - Methodology guide (
docs/methodology-guide.qmd) — how each indicator is computed, uncertainty handling, boundary harmonization, and the spatial methods (kept in sync with thecrxp-datapipeline).
(Enable once in Settings → Pages → Source: "GitHub Actions".)
- No god component. All imperative MapLibre code lives in
src/lib/map/MapController.js; UI components are presentational; small rune state slices (src/lib/state/*.svelte.js) hold app state;/explorecomposes them and drives the controller one-directionally (state →$effect→ controller method). - Geometry is value-free. Tract/county geometry carries only
geoid; indicator values join at runtime via MapLibre feature-state, so one geometry serves every indicator and year. - Lazy data. The manifest loads once; per-indicator value/analytics files load on demand.
- Analytics are precomputed. z-scores and LISA come from the pipeline (single statistical source of truth); the app does not recompute them.
The app consumes static files validated by scripts/build-data.mjs (the build fails on any violation):
| Path | Purpose |
|---|---|
manifest.json |
indicator catalog + theme categories + schemaVersion |
geo/tracts.geojson, geo/counties.geojson |
geometry (geoid only) |
values/<id>.json |
per-indicator values + MOE / CV / reliability + per-year breaks/stats |
analytics/z/<id>.json, analytics/lisa/<id>.json |
bivariate z-scores, FDR-controlled LISA quadrants |
aggregates.json |
county + region averages (and their MOE) by year |
areas/{tracts,counties,places}.json |
area manifests (drive prerender + search) |
meta/m<id>.md |
indicator metadata (what / how / why / source) |
provenance.json |
library + GDAL/PROJ versions that produced the data |
vitest covers the analytics helpers (z-scores, quantile breaks, Pearson/Spearman), the trend-series
builder, and the data-contract gate. Run npm run test.
- Code: MIT (
LICENSE). Copyright (c) 2026 Kailas Venkitasubramanian. - Data: the produced dataset (
static/data/and the downloads) is CC BY 4.0 (LICENSE-data.md); please credit "Carolinas Regional Explorer, UNC Charlotte Urban Institute." - Trademarks: "UNC Charlotte" and the crown logo are marks of The University of North Carolina at Charlotte and are not licensed for reuse; remove or replace them in derivatives.
- Citation: please cite the working paper — see
CITATION.cff, which powers GitHub's "Cite this repository."
Upstream data are public-domain (U.S. Census / ACS, CDC PLACES, USGS NLCD, EOG VIIRS); neighborhood names are © OpenStreetMap contributors (ODbL).
A research project of the UNC Charlotte Urban Institute, in the lineage of the Charlotte-Mecklenburg Quality of Life Explorer.