spatial_serving/README.md

# Spatial Serving for Custom Granularity Outputs

FireWx-FM is trained as a gridded wildfire occupancy model. The released
checkpoint predicts a probability map on the 5 km California EPSG:5070 grid. For
web and client use, the same output can be served at any polygon-defined
granularity by adding a spatial aggregation layer. County and sub-county views
are examples, not fixed limits.

This folder provides that serving layer. It does not change the checkpoint and
does not retrain the model. It converts one gridded probability map into polygon
summaries such as mean probability, maximum probability, 90th percentile
probability, and area fraction above a threshold.

## Why this supports custom granularity

The model output is spatially gridded, not tied to administrative boundaries.
Any polygon boundary that overlaps the grid can be used as a serving unit:

| Serving unit | Input boundary file | Output |
|---|---|---|
| County or parish | County/parish polygons | One risk summary per polygon |
| Sub-county | Census tract, block group, fire district, or local administrative polygons | One risk summary per polygon |
| Custom granularity | User-provided GeoJSON/GPKG polygon layer | One risk summary per polygon |

For areas smaller than one native grid cell, the output should be interpreted as
a grid-informed area summary rather than a new high-resolution forecast. The
recommended web behavior is to show the polygon summary together with the native
grid resolution.

## Expected probability input

The adapter expects an `.npz` file with:

```text
prob  [y, x] or [1, y, x]  FireWx-FM probability map
lat   [y]                  EPSG:5070 y-coordinate centers
lon   [x]                  EPSG:5070 x-coordinate centers
```

The names can be changed with CLI flags if an inference pipeline writes
different array names.

## Command line

```bash
python spatial_serving/grid_to_polygons.py \
  --probability-npz ./outputs/firewx_probability_2024-10-01T00.npz \
  --polygons ./boundaries/california_counties.geojson \
  --id-column GEOID \
  --output ./outputs/firewx_county_summary.geojson
```

For custom granularity, pass any polygon file that defines the desired serving
units:

```bash
python spatial_serving/grid_to_polygons.py \
  --probability-npz ./outputs/firewx_probability_2024-10-01T00.npz \
  --polygons ./boundaries/custom_serving_units.gpkg \
  --id-column unit_id \
  --output ./outputs/firewx_custom_granularity_summary.geojson
```

## Output fields

| Field | Meaning |
|---|---|
| `cell_count` | Number of overlapping native grid cells |
| `firewx_prob_mean` | Mean probability over overlapping cells |
| `firewx_prob_max` | Maximum probability over overlapping cells |
| `firewx_prob_p90` | 90th percentile probability over overlapping cells |
| `firewx_area_fraction_ge_threshold` | Fraction of cells above the threshold |

The output can be `.geojson`, `.gpkg`, or `.csv`. GeoJSON/GPKG retain polygon
geometry for direct web-map use.

## Suggested web migration contract

1. Run FireWx-FM inference on the native grid.
2. Save the probability map with native grid coordinates.
3. Aggregate to the requested polygon boundary using this adapter.
4. Display both the requested serving granularity and the native grid resolution.

This keeps the model contract stable while allowing the webpage to expose
custom spatial granularities chosen by the user or application.