SPARC Labs

SPARC Labs LLC — Spatial Research Labs

Python 3.10+ DOI License Platform Academic Partnerships

SPARC turns environmental and infrastructure data into causal, uncertainty-quantified intervention scenarios — powered by physics-constrained spatial machine learning and Bayesian causal inference.

Published in Urban Climate (2025), SPARC has since reached 85% R2 on urban heat island prediction in Providence, RI, and has been applied to ForceSMIP climate forcing attribution at global scale. The pipeline auto-tunes itself from a Bayesian Matérn correlogram, trains four geographically-weighted base models alongside their differentiable neural surrogates, fuses them through a SharedTrunk + CityHead meta-learner with sparse spatial attention and a 10-term staged-curriculum PDE loss, validates causal structure with MC3 DAG search, NUTS edge posteriors (informed by Bayesian MGWR priors), and DoWhy refutations, then simulates physics-constrained, budget-optimized "what-if" scenarios with built-in uncertainty quantification — all from a single project.yml configuration file across 13 domain templates.

Get started: Watch the demo · Try it locally · Download the desktop app · Interested in piloting? Contact us

• See SPARC in Action
• Pipeline Architecture
• Supported Domains
• Installation
• Quick Start
• Desktop App
• Results: Urban Heat Island
• Results: ForceSMIP Climate Forcing Attribution
• Interpreting Results
• Limitations & Assumptions
• Roadmap
• Project Structure
• Configuration Reference
• Dependencies
• License

🎬 Video coming soon — Watch how SPARC runs a neighborhood heat scenario with interventions and uncertainty.

SPARC executes five stages in sequence. Each stage reads from the previous stage's output, producing a fully traceable chain from raw data to policy-relevant scenario maps.

Stage 0 Correlogram Analysis Moran's I + Bayesian Matérn + anisotropy → auto-wired KernelField
 │
Stage 1 GWEN Variable Selection Geographically-weighted elastic net ranks predictors (optional)
 │
Stage 2 Spatial CV + Neural Meta 4 base models → differentiable surrogates → SharedTrunk + CityHead
 │ 10-term PDE curriculum, sparse spatial attention, MC-Dropout
 │
Stage 3 Bayesian Causal Validation MC3 DAG search + DML/CATE + NUTS edge posteriors + DoWhy refutations
 │
Stage 4 Scenario Simulation 4-tier physics-constrained predictions + budget-optimized allocation

Quantifies spatial structure for every variable in the project. SPARC computes Moran's I at multiple distance lags, then fits a Bayesian Matérn(κ, ν) covariance model per variable via NUTS, retains the full posterior for κ (used downstream as a prior), and detects directional anisotropy by fitting separate correlograms along cardinal and 45° axes (yielding per-predictor ellipse parameters κ_x, κ_y, θ). A cross-correlogram between the outcome and each predictor produces a ×ばつV effective-range matrix describing which predictors influence the outcome at which spatial scales.

All of this is packaged into a single KernelField object that is auto-wired into Stage 2: optimal lag → GWR/GWRF bandwidths, correlation range → spatial-CV block size, anisotropy ellipses → kernel geometry for every base model and surrogate. No manual tuning required.

A geographically-weighted elastic net (GWEN) ranks predictor importance across space using the bandwidth selected in Stage 0. The output is a ranked feature list plus per-cell importance maps. A human approval sentinel (gwen_approved.txt) gates progression to Stage 2 so analysts can inspect and prune predictors before training.

Trains four classical base models on spatially-buffered folds (block size from Stage 0) to prevent spatial leakage. All four consume the KernelField so that bandwidth and anisotropy are consistent across the stack:

Each base model is mirrored by a differentiable PyTorch surrogate (DifferentiableGWR, DifferentiableGWRF, DifferentiableGGPGAM) that is pre-trained against the classical out-of-fold predictions and then fine-tuned end-to-end inside the meta-learner.

The SPARCMetaLearner is split into two halves so trained physics knowledge can transfer between projects while every deployment retains a city-specific output layer:

• SharedTrunk. A PDE-informed physics encoder built on SIREN (sinusoidal) layers ingests physics features (elevation, land cover, solar/forcing variables), a learnable α(x) process-rate field (optionally produced by ProcessRateNet), and an optional 3-way diurnal time embedding. The trunk fuses these into a shared latent that is portable across cities and domains.
• CityHead. Embeds the 4-dimensional surrogate prediction vector, applies sparse KNN spatial attention (SparseSpatialAttention, O(N · max_neighbors) — interpretable as a learned spatial-influence surface), and emits both a continuous regression output and multi-threshold exceedance heads (sigmoid classifiers for P(T > τ) at user-defined thresholds). MC-Dropout is left active at inference; 500 stochastic forward passes produce per-point predictive mean, std, and credible intervals.

The meta-learner is trained against a joint loss that combines data fit with physics residual penalties. Eight core PDE terms cover heat diffusion (α∇2T − S), surface energy balance (Q* − Q_H − Q_E), directional consistency, anisotropy alignment with Stage 0, gradient-flux (Fourier's law), Gaussian curvature regularization, and α-field smoothness/prior terms. Two additional V3 temporal terms — transient consistency and nocturnal radiative-cooling calibration — activate when multi-snapshot data is supplied. A staged curriculum introduces terms gradually (heat diffusion at epoch 1, energy balance ~10, directional/anisotropy ~20, full stack ~30), each ramping linearly over five epochs to avoid optimizer shocks.

When lambda_jepa > 0, SPARC pretrains the trunk with a V-JEPA-2-AC-style objective: an EMATrunk (exponential-moving-average copy of the online trunk, stop-grad) provides target embeddings, a LatentPredictor maps (context, ActionEmbedding) to predicted target latents, and a cosine + VICReg loss aligns them while preventing representational collapse. ActionEmbedding encodes (treatment one-hot, |Δx|, sign, Δt), making the trunk action-conditioned for downstream causal inference.

When enabled, SPARC re-fits GWR many times by drawing κ values from the Stage 0 Matérn posterior — perturbing only the bandwidth — then stacks the per-cell coefficient matrices into a per-cell β posterior (mean, std, 89% HDI). These posteriors are persisted to the artifact store and consumed by Stage 3 NUTS as informed priors.

Laplacian eigenmaps and ClimateEncoder / PDEEncoder features can be injected as spatial side-information to either backend.

Given a user-defined DAG, Stage 3 produces a fully Bayesian picture of cause and effect — structure, magnitudes, heterogeneity, and robustness:

• MC3 DAG search. Metropolis-coupled MCMC over edge inclusion produces posterior edge-inclusion probabilities, a median-probability DAG, BIC/Bayes-factor model comparison, and acceptance diagnostics.
• Double Machine Learning + spatial CATE. Cross-fitted DML residualizes outcome and treatment (with HGB / OLS nuisance models); EconML's CausalForestDML, wrapped as SpatialCATEEstimator / BayesianSpatialCATE, then estimates per-cell Conditional Average Treatment Effects with credible bands.
• NUTS edge posteriors with informed priors. A per-edge Bayesian GLM is sampled with NUTS (numpyro), using the Stage 2 GWR β posterior from the Bayesian MGWR ensemble as its prior. The result is a full posterior over each causal edge — not a point estimate — that downstream scenarios can sample from directly.
• Bayesian causal PDP. causal_pdp_bayesian traces dose-response curves with credible bands across the treatment range and automatically detects saturation points, producing CausalDoseResponseCurve objects used by Stage 4.
• CATE-vs-GWR divergence audit. Per-cell comparison of Bayesian CATE to classical GWR coefficients reports correlation, sign-agreement rate, and flags cells where the two diverge by more than 2σ — a check on identification and a guide for human review.
• Robust causal discovery. PC-stable, LiNGAM, and GES are run as a diagnostic, scored against the expert DAG (typical edge F1 ≈ 0.6–0.8), and supplemented by the Wager 2025 causal-gaps add-on for DAG-identified vs. unidentified effect estimation.
• DoWhy refutations + E-values. Placebo treatment, random common cause, subset analysis, and unobserved-confounding bounds are reported per edge with E-values quantifying how strong a hidden confounder would need to be to nullify each finding.

Outputs include mc3_results.json, edge_inclusion_probs.csv, nuts_edge_samples / nuts_edge_summary.csv, cate_estimates.csv, divergence_audit.json, and scenario_coefficients.json.

Stage 4 turns the trained models and causal posteriors into physics-constrained counterfactual maps. The ScenarioSimulator chooses among four computational tiers of increasing sophistication, using the most informative method available given what Stages 0–3 produced:

Applied automatically across all tiers: variable bounds, diminishing returns (√ taper), sign enforcement, delta caps, Mahalanobis extrapolation guards that flag scenarios pushed beyond the training data covariance, combined constraints (e.g., Canopy + Impervious ≤ 100%), and PDE-residual penalties (energy-balance, advection–diffusion) carried over from the neural meta-learner.

For planning use cases, SPARC pairs the per-cell predicted benefit (from NUTS draws or the learned α field) with a user-supplied cost surface and solves a budget-constrained allocation problem via greedy, greedy-2opt, or MILP (PuLP) optimizers. A Pareto frontier is swept over budget multipliers (e.g., ×ばつ, ×ばつ, ×ばつ, ×ばつ, ×ばつ of baseline), and each solution is scored for equity with a Gini coefficient over the allocation. The result is a spend-vs-benefit curve with explicit fairness reporting.

Multiple treatments can be applied simultaneously through a JointScenarioBundle (sequential composition, independent superposition, or PDE-mediated interaction). Every scenario run is appended to a versioned scenario library (scenarios/library.jsonl) — a Git-like, append-only log of intervention configurations and results — so any plan can be reproduced or compared against future runs.

SPARC ships with 13 domain templates, each containing a pre-configured project.yml, physics priors, constraint caps, and a causal DAG:

Create a new project from any template:

sparc init --template uhi --output ./my_project

See the Desktop App section for the full-featured native experience with guided setup, spatial visualization, and visual DAG editing.

# 1. Scaffold from a template
sparc init --template uhi --output ./my_project
# 2. Edit project.yml (data path, CRS, predictors)
notepad ./my_project/project.yml
# 3. Validate
sparc validate --project ./my_project/project.yml
# 4. Run the full pipeline
sparc run --project ./my_project/project.yml --stage all

Or run stage-by-stage:

sparc run -p project.yml -s 0 # Correlogram analysis
sparc run -p project.yml -s 1 # GWEN variable selection (optional)
sparc run -p project.yml -s 2 # Model training
sparc run -p project.yml -s 3 # Causal validation
sparc run -p project.yml -s 4 # Scenario simulation

SPARC ships as a native desktop application built with Tauri v2 and React — no browser or cloud required. Your data stays on your machine.

Status: Fully functional core pipeline. Currently polishing additional features including Claude-assisted project setup, a visual DAG editor, and GPU-accelerated spatial maps via deck.gl.

Interested in piloting? Contact sparcurbanlabs@gmail.com for early access.

Key features:

• Runs entirely offline — no cloud, no API keys required for the core pipeline
• Native performance via Tauri v2 (lightweight ~15 MB, not Electron)
• Claude-powered guided project setup (optional, bring your own API key)
• Interactive spatial visualization with deck.gl and MapLibre GL
• Visual drag-and-drop DAG editor

Study area: Brown University campus and surrounding Providence, RI neighborhoods Target variable: Ambient Air Temperature z-score (AAT_z, °F) Observations: 54,701 spatial points at ~30 m resolution CRS: EPSG:3438 (RI State Plane) Predictors: Pct_Canopy, Pct_Impervious, NDVI, Albedo, Elevation_m, Distance_from_water_m

The enhanced meta-ensemble with 150 Laplacian eigenmaps achieved the best performance, explaining 94.4% of spatial temperature variance with an RMSE of 0.42 z-score units. The Laplacian features and PDE-curriculum training provided a +4.2 pp R2 uplift over the standard meta-ensemble — and roughly +9 pp over the original 2025 Urban Climate publication results, driven primarily by the SharedTrunk + CityHead architecture, sparse spatial attention, and the staged 10-term PDE loss.

Estimator: Double Machine Learning (DML) with 5-fold cross-fitting DAG: 3 treatments (Canopy, Impervious, Albedo) → 1 mediator (NDVI) → 1 outcome (AAT_z), with 2 confounders (Elevation, Distance from water)

Relative importance: Impervious (51.1%) > Canopy (37.9%) > Albedo (11.0%)

All three treatments passed all four refutation tests (placebo, random common cause, subset, unobserved confounding). Causal discovery (PC-stable, LiNGAM, GES) achieved an edge F1 of 0.71 against the expert DAG.

Results from Tier 1 (bayesian_beta — NUTS-sampled GWR locals), averaged across all 54,701 points:

Diminishing returns are visible beyond ~15 pp, where the √ taper begins to limit further cooling gains.

Note: These intervals were generated with only 10 Monte Carlo draws due to compute-time constraints and are preliminary. The narrow credible intervals reflect the limited draw count — production runs should use 500–1,000+ draws for robust uncertainty quantification. Updated results will be published in a future release.

Domain: Forced Component Estimation from GCM Ensemble Members (ForceSMIP Tier 1) Target variable: Sea-surface temperature trend (tos_trend, °C per 42-year trend) Approach: Fingerprinting — cross-sectional trend fields treated as spatial data Observations: 71,498 grid cells (2.5° global grid) CRS: EPSG:4326 → EPSG:6933 (NSIDC EASE-Grid 2.0, equal-area) Predictors: GMST_trend, GHG/aerosol/volcanic/solar forcing indices, ENSO, AMV, IPO, lat_abs, land_fraction, ocean_basin

Status: The pooled SST (tos) variable has been run through all four stages. TAS (surface air temperature) completed through Stage 1. PR (precipitation) and PSL (sea-level pressure) have been initialized with GWEN only.

The GWRF model was the best-performing individual model at R2 = 0.642. The meta-ensemble matched but did not improve upon GWRF, likely because the global climate trend fields have less local-scale heterogeneity than the urban heat data.

Estimator: DML DAG: Treatments (GMST_trend, AMV_index, IPO_index) → Outcome (tos_trend), with confounders (member_id, lat_abs, land_fraction, ocean_basin)

Relative importance: GMST_trend (65.3%) > IPO_index (17.7%) > AMV_index (17.0%)

GMST_trend passed all four refutation tests (E-value = 2.03). AMV and IPO had weaker robustness (E-values of 1.58 and 1.30, respectively), consistent with their partly-internal, partly-forced nature.

Simulated forced-response patterns under incremental global warming:

Internal variability scenarios (AMV, IPO) were also simulated, with AMV showing stronger spatial heterogeneity (std = 0.50 at +0.05 increment) driven by North Atlantic regional patterns.

SPARC produces a rich set of outputs across its five stages. Here is a quick reference for the most important metrics:

1. Check the "Avg. Actual Change" column — did the physics constraints cap the intervention? If actual < requested, bounds were hit.
2. Compare Tier 1 vs. Tier 2/3 — large disagreement may indicate spatial spillovers or non-linear interactions that simple per-cell β cannot capture.
3. Look at the Std column — high standard deviation means the effect varies significantly across space (spatial heterogeneity).
4. Review MC percentiles — if the 5th and 95th percentiles have the same sign, the direction of effect is robust.
5. Check diminishing returns — for large interventions (e.g., +50 pp canopy), the √ taper compresses gains. This is by design.

For a comprehensive plain-language guide, see docs/INTERPRETATION_GUIDE.md.

Transparency builds trust. Here is what SPARC does well, where it has boundaries, and what to keep in mind when interpreting results.

We actively work to reduce these limitations in each release. If you encounter an edge case or have domain-specific feedback, please open an issue or contact sparcurbanlabs@gmail.com.

SPARC is under active development. Key directions on the horizon:

Have ideas or want to collaborate? Reach out at sparcurbanlabs@gmail.com.

sparc-resilience/
├── sparc/ # Main package
│ ├── __main__.py # CLI entry point (sparc init / validate / run / scenario / report)
│ ├── config/ # Configuration loader, JSON schema validation, hardware profile
│ ├── data/ # Data utilities, temporal helpers
│ ├── models/ # OLS, GWR, GWRF, GGPGAM, GWEN, differentiable surrogates,
│ │ # SPARCMetaLearner (SharedTrunk + CityHead), ProcessRateNet,
│ │ # KernelField, SparseSpatialAttention/SIREN, EMATrunk, LatentPredictor,
│ │ # ActionEmbedding, ClimateEncoder, PDEEncoder
│ ├── features/ # Laplacian eigenmaps, fold-aware + temporal spatial features
│ ├── physics/ # PDE operators, 10-term PDE loss, energy balance, Poisson solver
│ ├── training/ # Curriculum, replay, EWC, CMA-ES, optimizer/loss helpers, JEPA loss
│ ├── inference/ # Zero-shot and few-shot inference utilities
│ ├── causal/ # DAG definition, MC3, NUTS, DML/CATE, causal PDP, divergence audit
│ ├── evaluation/ # Model evaluation metrics and diagnostics
│ ├── interventions/ # Scenario simulator (4-tier), ScenarioEngineV4, physics priors
│ ├── run/ # Pipeline orchestration — correlogram + Matérn + anisotropy,
│ │ # GWEN, spatial CV, v2_neural_training, v2_bayesian_causal,
│ │ # Bayesian MGWR ensemble, scenario runners, artifact I/O
│ ├── scenario/ # Scenario builder/validator, budget allocation, scenario library
│ ├── report/ # Report generation
│ ├── registry/ # Artifact store (SQLite), city registry, domain template registry
│ └── server/ # Local pipeline/IPC server for the desktop app
├── templates/ # Domain templates (13 domains)
├── examples/ # Example projects (Brown UHI)
├── tests/ # Smoke tests
├── docs/ # MANUAL, PIPELINE_GUIDE, CONTRIBUTING, INTERPRETATION_GUIDE
├── sparc-desktop/ # Tauri v2 + React desktop application
├── scripts/ # Helper scripts
├── pyproject.toml # Package metadata and dependencies
├── README.md
├── LICENSE
└── CITATION.cff

Every project is driven by a single project.yml file with these sections:

See docs/MANUAL.md for the full configuration reference and docs/PIPELINE_GUIDE.md for a step-by-step walkthrough.

Proprietary — SPARC Labs LLC.