name: wildfire-burn-history-aoi
version: "0.1"
status: draft
category: events-hazards
themes: [hazards]
family: fire-perimeter-aoi-history
description: >
  Wildfire burn history for an area of interest from the USGS Wildland Fire
  Combined Dataset (national perimeters, 1878-2021). Clips the fire perimeters
  to the AOI, then returns the burn footprint: how many distinct fires,
  total burned area, the most recent burn year (hence years-since-last-fire),
  and the largest single fire. Answers "has this place burned, how often, and
  how recently?" for any US location. The clipped perimeters are the
  show-your-work.

# Example AOI: northern California Sierra / Plumas (heavy recent fire history).
settings:
  aoi_west: -121.6
  aoi_south: 39.6
  aoi_east: -120.4
  aoi_north: 40.4
  reference_year: 2021          # dataset ends 2021; years-since is measured from here

inputs:
  aoi:
    bbox: [-121.6, 39.6, -120.4, 40.4]
    notes: >
      The perimeters carry a polygon `shape` geometry (no bbox column), so the
      AOI clip uses a DuckDB-spatial predicate (ST_Intersects with the AOI
      envelope). Requires the DuckDB `spatial` extension.
  dataset:
    uri: "@usgs/wildland-fire-combined"

layers:

  # ── SOURCE ──────────────────────────────────────────────────────────────
  source/perimeters:
    type: vector
    uri: "@usgs/wildland-fire-combined"
    description: USGS combined wildland fire perimeters (GeoParquet); geometry column is `shape`.
    params:
      asset: usgs-fires-2021/combined.parquet

  # ── COMPUTE ─────────────────────────────────────────────────────────────
  compute/in-aoi:
    type: table
    description: Fire perimeters intersecting the AOI rectangle.
    compute:
      op: tabular_filter
      inputs:
        table: { layer: source/perimeters }
      params:
        where: >
          ST_Intersects(shape, ST_MakeEnvelope(${settings.aoi_west}, ${settings.aoi_south},
          ${settings.aoi_east}, ${settings.aoi_north}))

  # ── RESULT ──────────────────────────────────────────────────────────────
  result/burn-summary:
    type: table
    description: >
      One-row burn-history summary for the AOI — fire count (recurrence),
      total + max burned area (ha), first/last burn year, years since last fire.
    compute:
      op: tabular_aggregate
      inputs:
        table: { layer: compute/in-aoi }
      params:
        group_by: []
        aggregations:
          fires: "COUNT(*)"
          burned_ha_total: "SUM(GIS_Hectares)"
          burned_ha_largest: "MAX(GIS_Hectares)"
          first_burn_year: "MIN(Fire_Year)"
          last_burn_year: "MAX(Fire_Year)"
          years_since_last_fire: "${settings.reference_year} - MAX(Fire_Year)"

outputs:
  primary:
    - result/burn-summary        # Parquet — AOI burn-history summary row
  show_your_work:
    - compute/in-aoi             # the individual fire perimeters behind the summary

license:
  recipe: Apache-2.0
  output_dataset: public-domain
  upstream_data:
    - { source: "@usgs/wildland-fire-combined", license: public-domain }