Skip to content

About

Sentinel-1 + Sentinel-2 forest-disturbance monitoring: STAC-native Dask cube, omnibus Wishart change detection and error-adjusted area with confidence intervals.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Sentinel Forest Tracker

All-weather forest-disturbance monitoring for Spain: Sentinel-1 (SAR) and Sentinel-2 (optical) time-series fusion, from STAC ingestion to error-adjusted hectares.

Python License: MIT Code style: black Typing: mypy strict CI

Sierra de la Culebra 2022 fire: Sentinel-2 true colour, before and after
Sierra de la Culebra (Zamora), 2022: the burn scar in Sentinel-2 true colour, at the start and end of the study period. Detected at a recall of 0.99 and an F1 of 0.85 against Hansen Global Forest Change.


Overview

Given the boundary polygon of a Spanish monte (managed forest unit) or comarca and a time window, the tool assembles an aligned Sentinel-1 and Sentinel-2 data cube (Xarray and Dask, streamed from the Microsoft Planetary Computer within a bounded memory footprint), restricts the analysis to forest standing at the start of the period, detects forest loss and its temporal evolution, characterises the disturbance type, and reports error-adjusted hectares with a confidence interval, scored against an independent reference.

All-weather SAR carries the detection through cloud cover, while the optical indices (NDVI, NBR and NIRv) confirm and characterise it. The loss map is assessed against Hansen Global Forest Change, a canopy-removal reference, and never as a statement of legality.

  • Three detection modes: omnibus (the Wishart test, for abrupt change), seasonal (a VH log-ratio combined with a dNBR burn term) and trend (a Theil-Sen and Mann-Kendall trajectory).
  • Disturbance typing: fire (dNBR), clear-cut (VH drop) and die-off (gradual trend).
  • Honest validation: precision, recall and F1 against an independent reference, plus an Olofsson (2014) error-adjusted loss area — reported as a point estimate, because a wall-to-wall reference cannot supply a meaningful confidence interval. A probability-sample estimator that can is provided separately in forest_tracker.sampling.
  • Rigour by construction: a forest mask at the start of the period (no leakage), a single relative orbit, Sentinel-2 processing-baseline-04.00 harmonisation, and forest-wide (non-circular) statistics.

Method references

Each module cites the paper behind its method in its docstring:

Method Source
Omnibus / Wishart change detection Conradsen et al. (2003, 2016); Canty et al. (2020)
Radiometric terrain correction Small (2011), Flattening Gamma, IEEE TGRS 49(8)
Error-adjusted area and accuracy Olofsson et al. (2014), RSE 148:42–57
Forest-loss reference Hansen et al. (2013), Science 342(6160)

Pipeline

flowchart LR
    A[AOI polygon<br/>Spanish monte] --> B[STAC search<br/>Planetary Computer]
    B --> C[Sentinel-1 RTC<br/>single relative orbit]
    B --> D[Sentinel-2 L2A<br/>baseline-04.00 harmonised]
    C --> E[Lazy Xarray + Dask cube<br/>bounded RAM]
    D --> E
    E --> F{Detection mode}
    F -->|omnibus| G[Wishart test<br/>abrupt change]
    F -->|seasonal| H[VH log-ratio + dNBR<br/>fire / clear-cut]
    F -->|trend| I[Theil-Sen + Mann-Kendall<br/>slow decline]
    G --> J[Forest mask at t0<br/>WorldCover / Hansen]
    H --> J
    I --> J
    J --> K[Disturbance typing<br/>fire / clear-cut / die-off]
    K --> L[Validation<br/>P/R/F1 + Olofsson area ± CI]
    L --> M[Reports and figures<br/>GeoTIFF · JSON · PNG]
Loading

Quickstart

uv venv .venv && uv pip install -e ".[dev]" --python .venv

# Fire (Sierra de la Culebra, 2022): a seasonal VH log-ratio with a dNBR burn
# term, gap-filled, forest-masked and validated against Hansen GFC.
forest-track --aoi examples/aoi/sierra_culebra.gpkg --epsg 32629 \
  --start 2021-01-01 --end 2022-12-31 --event-date 2022-06-15 \
  --mode seasonal --baseline 2021-06-01 2021-09-30 --recent 2022-07-15 2022-09-30 \
  --forest-mask --gap-fill --validate --before-after-ortho \
  --output-dir results/sierra_de_la_culebra

# Slow decline (Sierra de las Nieves fir forest): a per-pixel NDVI trajectory.
forest-track --aoi examples/aoi/sierra_de_las_nieves.gpkg --epsg 32630 \
  --start 2016-01-01 --end 2023-12-31 --event-date 2019-06-01 \
  --mode trend --trend-index ndvi --forest-mask --before-after-ortho \
  --output-dir results/sierra_de_las_nieves

Key options. --validate scores the loss map against the Hansen GFC lossyear band over the forest population, writing precision, recall and F1 alongside an Olofsson error-adjusted area to validation.json. For the seasonal detector, --dnbr-min adds a dNBR burn term (fire is an optical signal, not a radar one) and --gap-fill back-fills cloud-gapped seasonal pixels from the wider pre- and post-event window; together they raised recall against Hansen from 0.47 to 0.99 (F1 from 0.58 to 0.85) on the Culebra fire at near-constant precision. --before-after-ortho saves a first-versus-last-season true-colour pair of the affected zone.

Further capabilities. Per-pixel SCL cloud masking is enabled by default (--no-scl-mask disables it). --export-vector writes a GeoPackage of disturbance polygons carrying area and type. A complete run may be driven from a TOML file (forest-track --config examples/config/culebra.toml) or from the included Dockerfile. The library also provides forest_tracker.sampling (an Olofsson probability-sample estimator — the only route in this project to a statistically valid confidence interval, requiring a drawn and interpreted sample), forest_tracker.breakdetect (per-pixel temporal break detection at any date) and forest_tracker.tiling (an AOI tile grid for province-scale processing). InSAR coherence from Sentinel-1 SLC is a documented next phase; it requires SLC data and a dedicated SAR processor, and is therefore not approximated here.

Use as a library

The project is a conventional installable package: every capability exposed by the command-line interface is also available programmatically. It can be installed directly from GitHub:

pip install "git+https://github.com/Juanmaherruzo/Sentinel-Forest-Tracker.git"
from datetime import date
from pathlib import Path

from forest_tracker.config import PipelineConfig
from forest_tracker.pipeline import Pipeline

cfg = PipelineConfig(
    aoi_path=Path("examples/aoi/sierra_culebra.gpkg"),
    start=date(2021, 1, 1), end=date(2022, 12, 31), event_date=date(2022, 6, 15),
    output_dir=Path("results/culebra"), epsg=32629,
    mode="seasonal",
    baseline=(date(2021, 6, 1), date(2021, 9, 30)),
    recent=(date(2022, 7, 15), date(2022, 9, 30)),
    forest_mask=True, gap_fill=True, validate=True,
)
result = Pipeline(cfg).run()
print(result.report.affected_ha, result.validation.metrics.f1)

The individual building blocks are reusable in isolation as well: forest_tracker.changedet.OmnibusChangeDetector, forest_tracker.trend.TemporalTrendDetector and forest_tracker.validate.Validator (the Olofsson error-adjusted area and confusion metrics) all operate on plain NumPy arrays.

Worked results

The emphasis throughout is on defensible numbers rather than headline figures. Two Spanish cases are presented, chosen to illustrate a strength and a limit.

Sierra de la Culebra (2022 fire): the strong, quantified case. A seasonal VH log-ratio combined with a dNBR burn term (fire is an optical signal to which C-band VH is nearly blind), gap-filled and forest-masked, then scored against Hansen GFC loss over the forest, yields a precision of 0.75, a recall of 0.99 and an F1 of 0.85, with an Olofsson error-adjusted loss area of 4,829 ha. Both the under-mapping baseline (3,002 ha) and the over-mapping final map (6,380 ha) converge on the same adjusted area, which is precisely the purpose of error-adjusted reporting. 4,829 ha is the defensible figure; 6,380 ha is the raw map and overstates the loss by about a third.

No confidence interval is quoted, and that is deliberate. The Olofsson variance is the variance of a probability sample; here the reference is a census, every pixel of it, so plugging the pixel count into that formula produces an interval of roughly ±7 ha on 4,829 — about ±0.14 %, which no satellite-derived burned area is known to. It would also ignore the dominant error term, which is Hansen's own. The estimator that yields a real interval, from a drawn stratified sample, is in forest_tracker.sampling; running that campaign is the natural next step and is listed under Scope.

A second caveat on the metrics: Hansen is a ~30 m product resampled onto the 10 m analysis grid, so one reference observation becomes roughly nine identical pixels. Precision, recall and F1 are unaffected in expectation, but the effective sample size is far below the raw pixel counts in validation.json.

Sierra de las Nieves (fir-forest decline): the subtle, honest case. A per-pixel Theil-Sen slope with a Mann-Kendall significance test, applied to the 2016–2023 NDVI trajectory, identifies largely stable forest together with 5.9 ha of genuine, significant decline (under 0.1 % of the unit). This is also the case that exposed and corrected a Sentinel-2 processing-baseline-04.00 offset which had otherwise fabricated roughly an order of magnitude more apparent decline; the temporal view is what revealed it. It is deliberately not validated against Hansen, which maps canopy removal and is blind to standing die-off, and would therefore be an inappropriate reference.

Rigour is maintained throughout: a forest mask at the start of the period (no leakage), a single relative orbit, Sentinel-2 harmonisation, forest-wide (non-circular) reporting, and metrics computed over the whole region with an error-adjusted area rather than a hand-picked patch.

Results

Sierra de la Culebra: 2022 fire (seasonal, validated against Hansen)

Detection panel: VH change, confirmed loss and seasonal delta-NDVI

Sierra de las Nieves: fir-forest NDVI decline (trend)

Trend panel: NDVI slope, significant decline and per-year trajectories

Sierra de las Nieves: Sentinel-2 true colour, start and end of study

What this project demonstrates

Skill How it is demonstrated
STAC and cloud-native EO sentinel-1-rtc and sentinel-2-l2a ingested from the Planetary Computer via COG range reads, without full-scene downloads
SAR literacy Backscatter (γ⁰), speckle, orbit geometry, decibel versus linear scaling, the equivalent number of looks and multilooking, all handled correctly
Xarray and Dask A lazy, chunked, out-of-core cube with a bounded memory footprint over long time series, together with de-duplicated S2 fetches
Multi-sensor fusion Two sensors of differing physics, resolution and revisit aligned onto a single grid
Rigorous change detection A citable statistic (the omnibus / Wishart test) and a robust trend (Theil-Sen with Mann-Kendall), rather than a naive image difference
Rigorous validation Confusion metrics and an Olofsson error-adjusted area over the whole region rather than a curated patch — and knowing which uncertainty claims a census reference does not support
Senior engineering Fully typed (mypy --strict), tested (pytest), linted (ruff and black), CI-gated and packaged with pyproject

Scope

This is batch time-series change detection for Spain, and neither real-time streaming nor a global map. It began with a single phenomenon, a single AOI and a single method, and has since grown a seasonal mode, a temporal-trend mode, a forest mask at t0, disturbance typing and error-adjusted validation, while remaining batch and reproducible.

Probability-sample validation is the most valuable outstanding item. The estimator is implemented (forest_tracker.sampling); what is missing is the campaign — drawing ~500 stratified points and interpreting each one — which is the only way this project can quote a confidence interval that means anything. Tile-scale runs and near-real-time operation also remain future work.

Contributing and feedback

Recommendations and improvements of any kind are welcome, whether they concern methodology, performance, additional disturbance types, validation strategy or the documentation. Please open an issue to begin a discussion, or submit a pull request. An issue that describes an idea is just as valuable as an implementation.

The quality gates (ruff, black, mypy --strict and pytest) run in CI on every push and pull request; running them locally beforehand keeps the loop fast.

Citation

If you use this work in your research, please cite it as follows:

@software{herruzo2026sentinelforesttracker,
  author = {Herruzo, Juan Manuel},
  title  = {Sentinel Forest Tracker},
  year   = {2026},
  url    = {https://github.com/Juanmaherruzo/Sentinel-Forest-Tracker}
}

License

Released under the MIT License; see LICENSE. Sentinel data © Copernicus / ESA; Hansen Global Forest Change © Hansen/UMD/Google/USGS/NASA; ESA WorldCover © ESA.

About

Sentinel-1 + Sentinel-2 forest-disturbance monitoring: STAC-native Dask cube, omnibus Wishart change detection and error-adjusted area with confidence intervals.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages