Ground-reference error limits validation of remotely sensed forest structure

Data and code to reproduce every number in the study "Ground-reference error limits validation of remotely sensed forest structure".

The manuscript itself is not in this repository, by design. Everything needed to reproduce the analysis is.

What the analysis shows

Reference-error corrections in current practice assume a Gaussian, stationary, height-proportional field measurement error. All three assumptions are testable with repeat measurements at fixed points, and in this dataset all three fail.

Result	Value
Reference error, variance-based	σ_ref = 0.46 m (95% CI 0.26–0.63)
Reference error, robust	0.15 m
Excess kurtosis of repeat differences	103 — 75% of variance from 1.0% of pairs
Dependence on height	none (P = 0.13)
Stationarity across 20 campaigns	fails: 0.10–1.31 m, −2.3 cm yr⁻¹ (P = 0.015)
Grid points above the 15 m pole ceiling	85.4%
Truncation bias in mean canopy height	−35.6% (21.9 m → 14.1 m)
Alpine validation	RMSE 1.10 m, r² 0.993, slope 1.005 (n.s. vs 1)
Reference share of reported error variance	17.2% at σ_ref = 0.46 m; 82.9% at σ_ref = 1 m
Maximum attainable r² against this reference	0.997 (observed 0.993)
Biomass error variance attributable to RS height	20%; height elasticity of AGB = 3.08
Structure → biomass skill	r² = 0.75 in space, 0.30 through time
Repeat pairs needed for ±20% on σ_ref	~660, against ~13 under a Gaussian assumption

Every value above is written to results/results.json by the notebook, which also runs 16 automated checks over them.

Layout

data/raw/          the seven input files, unmodified (provenance in data/README.md)
notebooks/         reference_error_analysis.ipynb — the full analysis, top to bottom
figures/           Fig1–Fig5 as used in the manuscript
results/           results.json (every reported number + the 16 checks) and tables/
                   (intermediate tables). A run also writes results/figs/, which mirrors
                   figures/ and is not committed.
docs/              data-quality notes
src/               make_checksums.py

Reproducing

git clone https://github.com/<your-username>/canopy-reference-error.git
cd canopy-reference-error
conda env create -f environment.yml      # or: pip install -r requirements.txt
conda activate canopy-reference-error
jupyter lab notebooks/reference_error_analysis.ipynb

Run it top to bottom. It reads only from data/raw/ and writes only into results/. No network access is needed and no paths outside the repository are used. To run it headless:

jupyter nbconvert --to notebook --execute --inplace notebooks/reference_error_analysis.ipynb

To analyse the data from somewhere else on disk, set GROUND_DATA_DIR to that folder; the notebook falls back to data/raw/ when the variable is unset.

Scope and known limits

• σ_ref is measured at one tropical wet-forest site, one instrument, one crew. It is not asserted to transfer numerically. The Alpine decomposition is conditional on an assumed σ_ref and is reported as a sensitivity sweep, of which 17.2% and 82.9% are two points.
• Above the 15 m pole ceiling the error model is empirically unconstrained, and the Alpine trees it is applied to are mostly above 15 m.
• The crown-diameter comparison (RS 6.11 m vs field 3.96 m) confounds site with measurement definition and is a caveat only.
• The biomass workbook documents its values as kg per stem; they are Mg per stem. The notebook demonstrates this rather than assuming it — see docs/data-quality.md.

Licence

Code: MIT (LICENSE). Data: all input files are CC0 1.0 from public Dryad deposits and are redistributed here freely; derived tables, figures and documentation are CC BY 4.0. See LICENSE-DATA and data/README.md for per-file terms and the citations owed to the original data providers.

Citation

See CITATION.cff. Please also cite the underlying datasets:

Clark, D., Clark, D. & Kellner, J. (2021). Canopy height distributions and estimated above-ground biomass across a tropical rain forest landscape in Costa Rica, 1992–2018 [Dataset]. Dryad. https://doi.org/10.5061/dryad.fn2z34tst

Dalponte, M. & Coomes, D.A. (2017). Data from: Tree-centric mapping of forest carbon density from airborne laser scanning and hyperspectral data [Dataset]. Dryad. https://doi.org/10.5061/dryad.hf5rh