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:

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

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:

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

Run FireWx-FM inference on the native grid.
Save the probability map with native grid coordinates.
Aggregate to the requested polygon boundary using this adapter.
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.