# catalog/operations/temporal/aggregate/sar_temporal_features.yaml

id: sar_temporal_features
name: SAR Temporal Features
description: >
  Per-pixel temporal statistics (mean, sample standard deviation, 10th
  percentile, 90th percentile) over a raster time stack. The pre-event
  baseline that anchors SAR-anomaly detectors — wildfire, flood,
  deforestation, landslide. Hazard-agnostic; emits four bands in a single
  contiguous output.
version: 1.0.0
category: aggregate
type: stack-to-raster
default_implementation: native

inputs:
  - name: stack
    type: raster_stack
    format: geotiff
    description: >
      Time stack of single-band rasters at a common grid (band-major flat
      layout — time outer, pixel inner). Typically a Sentinel-1 GRD VH
      pre-event baseline window of ≥10 acquisitions.
    required: true

requires:
  bands: [vv, vh]

outputs:
  - name: features
    type: raster
    format: cog
    dtype: float32
    bands: 4
    band_names: [mean, std, p10, p90]
    description: >
      Four contiguous bands packed back-to-back: mean, sample std (n-1),
      10th percentile, 90th percentile. Same width × height as each input
      time step.

params: {}

granularity:
  min_resolution_m: 10
  max_resolution_m: 1000
  recommended_resolution_m: 10
  output_resolution: inherit
  minimum_bands: 1
  requires_continuous: true
  suitable_aoi_km2:
    min: 0.01
    max: 50000
  realtime_max_km2: 200

uncertainty:
  error_model: propagated
  factors:
    - name: baseline_length
      description: >
        Sample variance estimates become unreliable below ~10 acquisitions.
        With n=1 the std is undefined (NaN); with n=2 it is dominated by
        a single observation.
      severity: high
      mitigations:
        - "Use ≥10 acquisitions in the baseline window"
        - "Drop pixels with insufficient coverage (downstream filter)"
    - name: speckle
      description: >
        Per-scene SAR speckle inflates the temporal variance. Averaging
        over many scenes suppresses speckle ~sqrt(n).
      severity: medium
      mitigations:
        - "Multi-look prior to stacking (3x3 boxcar or refined Lee)"
        - "Use ≥6 months of acquisitions for a stable variance estimate"
    - name: seasonal_signal
      description: >
        Vegetation/soil-moisture seasonality contributes to baseline
        variability and can mask event-driven anomalies.
      severity: medium
      mitigations:
        - "Use a same-season baseline (e.g. JJA-only for a summer event)"
        - "Pair with year-on-year detrending if recurrent events are studied"
  limitations:
    - "Polarization and orbit pass must be consistent across the stack."
    - "All input scenes must be on the same grid (resample / co-register upstream)."
    - "NaN handling: NaN values are dropped from the count, not imputed."

execution:
  realtime_max_km2: 200
  cost_per_km2: 0.001
  time_per_km2_sec: 0.5
  memory_profile: medium
  profile:
    cpu: medium
    memory: medium
    io: medium
  scaling:
    model: linear
    parallelizable: true
    min_chunk_km2: 1

cache_policy:
  ttl_days: 90
  invalidate_on: [source_update]

# backends: audited 2026-08-14 (defect 50). NOTHING dispatches this op: no arm in folia-engine
# `dispatch_op`, no `registerOp`/OP_TABLE entry in packages/compute, no `_BUILTIN_OP_MAP`
# key in folia/compute.py, no backend manifest. Declared EMPTY on purpose — an absent
# block would be indistinguishable from one nobody ever wrote.
# packages/compute-wasm/src/temporal_ops.rs:2256 `sar_temporal_features` exists as a crate fn; nothing registers an op for it.
backends: {}

display_hints:
  map:
    renderer: maplibre
    palette: grayscale
    opacity: 0.8
  info:
    fields: [mean, std, p10, p90]
    format: "{value}"
    section: SAR Baseline

ui:
  icon: bar-chart-2
  color: "#4682B4"

provenance:
  references:
    - "Ban, Y., Zhang, P., et al. (2020). Near Real-Time Wildfire Progression Monitoring with Sentinel-1 SAR Time Series and Deep Learning. Scientific Reports 10:1322. https://doi.org/10.1038/s41598-019-56967-x"