# catalog/operations/raster/sar_log_ratio.yaml

id: sar_log_ratio
name: SAR Log-Ratio Anomaly
description: >
  Per-pixel log10 ratio of a single post-event SAR backscatter scene against
  a pre-event temporal baseline mean. Inputs are SAR backscatter in decibels
  (Sentinel-1 GRD convention); output is dimensionless. The anomaly map
  feeds the burn-detection CNN in the SAR4Wildfire (Ban & Zhang 2020)
  recipe and generalises to flood, deforestation, and landslide pipelines.
  Polarization-agnostic — the recipe selects VH or VV.
version: 1.0.0
category: raster
type: raster-to-raster
default_implementation: native

inputs:
  - name: post_db
    type: raster
    format: geotiff
    description: Post-event SAR backscatter scene, dB units (single band).
    required: true
  - name: baseline_mean_db
    type: raster
    format: geotiff
    description: >
      Pre-event temporal baseline mean of SAR backscatter, dB units.
      Typically the `mean` band emitted by `sar_temporal_features`.
    required: true

requires:
  bands: [vv]  # polarization-agnostic — recipe selects VV or VH; declared as VV by convention

outputs:
  - name: log_ratio
    type: raster
    format: cog
    dtype: float32
    # concept omitted — generic change indicator, no single concept slug
    description: >
      log10(linear_post / linear_baseline). Negative values indicate the
      post-event scene is darker than baseline (e.g. burned vegetation in
      VH); positive values indicate brighter (e.g. SAR-bright water or
      double-bounce on flooded urban surfaces).

params: {}

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

uncertainty:
  error_model: propagated
  factors:
    - name: speckle
      description: >
        SAR speckle noise propagates to the ratio. Use multi-look or
        sigma-Lee/refined-Lee filtering on inputs before calling.
      severity: high
      mitigations:
        - "Multi-look averaging (e.g. 3x3 boxcar) prior to log-ratio"
        - "Use 10+ scenes in the baseline mean to suppress per-scene speckle"
    - name: baseline_length
      description: >
        Short baselines (fewer than ~6 scenes) understate the pre-event
        backscatter variability and inflate apparent anomalies.
      severity: medium
      mitigations:
        - "Use ≥6 months / ≥10 acquisitions for the baseline window"
        - "Pair with sar_temporal_features outputs (μ + σ) to z-score"
  limitations:
    - "Polarization must match between baseline and post scene (VH vs VH)."
    - "Orbit pass (ASC vs DESC) must match — backscatter geometry differs."
    - "Inputs MUST be in dB. Passing linear backscatter will silently produce wrong anomalies."

execution:
  realtime_max_km2: 500
  cost_per_km2: 0.0003
  time_per_km2_sec: 0.2
  memory_profile: low
  profile:
    cpu: low
    memory: low
    io: medium
  scaling:
    model: linear
    parallelizable: true
    min_chunk_km2: 1

cache_policy:
  ttl_days: 30
  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/core_ops.rs:597 `sar_log_ratio` exists as a crate fn; nothing registers an op for it.
backends: {}

display_hints:
  map:
    renderer: maplibre
    palette: divergent
    opacity: 0.8
  info:
    fields: [log_ratio]
    format: "{value}"
    section: SAR Anomaly

ui:
  icon: trending-down
  color: "#8B0000"

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"