Skip to content
MARC-KCPublic
forked from kvenkita/crxp

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Carolinas Regional Explorer (CRXP)

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.

Features

  • 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.

Embedding

/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.

Broadcasting map state to the parent window

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);
  • search is the user-facing query string with the leading ? (empty string when there are no params). Embed-plumbing flags like topnav are 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 — replaceState doesn't reactively update page.url).
  • targetOrigin is resolved from the parent origin (ancestorOrigins/document.referrer) against an allowlist — https://carolinasexplorer.com, Netlify deploy previews (https://<deploy>--<site>.netlify.app), and http://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 in src/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).

Indicators

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.

Develop

npm install
npm run dev          # http://localhost:5173
npm run test         # vitest
npm run check        # svelte-check

Build & deploy

npm run build        # validate the data contract + prebuild downloads + prerender
npm run build:full   # + OG cards + sitemap (production)
npm run preview

build 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).

Documentation

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 the crxp-data pipeline).

(Enable once in Settings → Pages → Source: "GitHub Actions".)

Architecture

  • 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; /explore composes 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.

Data contract (static/data/)

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

Tests

vitest covers the analytics helpers (z-scores, quantile breaks, Pearson/Spearman), the trend-series builder, and the data-contract gate. Run npm run test.

License, attribution & citation

  • 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.

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages