All-weather forest-disturbance monitoring for Spain: Sentinel-1 (SAR) and Sentinel-2 (optical) time-series fusion, from STAC ingestion to error-adjusted hectares.
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.
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) andtrend(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.
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) |
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]
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_nievesKey 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.
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.
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.
| 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 |
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.
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.
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}
}Released under the MIT License; see LICENSE. Sentinel data
© Copernicus / ESA; Hansen Global Forest Change © Hansen/UMD/Google/USGS/NASA;
ESA WorldCover © ESA.