sgsR Sampling Bridge
nemora.sampling.sgsr wraps the GPL-3 sgsR R package through a small R
script. It stratifies a single structural metric layer with quantiles, allocates
samples, and returns the allocation, sample coordinates, and structural strata.
Port or bridge?
Bridge. sgsR is GPL (>= 3), while Nemora is MIT. Copying or porting sgsR
code into Nemora would create a licence and maintenance problem. The bridge
calls the installed R package instead.
The cost is a real R runtime dependency:
R and the
sgsR,terra, andsfR packages must be installed;users may need to set
R_LIBS_USERwhensgsRis in a non-default library;the bridge follows sgsR’s public function signatures, so an upstream API change can require a wrapper update; and
integration tests are skipped when sgsR is unavailable.
Install
# Debian/Ubuntu system libraries used by terra/sf
sudo apt-get install -y r-base libgdal-dev libgeos-dev libproj-dev libudunits2-dev
# R packages
Rscript -e 'install.packages(c("sgsR"), repos="https://cloud.r-project.org")'
If you installed sgsR into a custom library, set R_LIBS_USER before running
Nemora:
export R_LIBS_USER=/path/to/R/library
Worked example
The repository includes a deterministic 20 x 20 structural metric grid:
nemora sampling-sgsr examples/sgsr_sampling/structure.asc \
--output tmp/sgsr_example \
--n-samples 24 \
--seed 42 \
--n-strata 3
Equivalent Python:
from pathlib import Path
from nemora.sampling.sgsr import run_sgsr
result = run_sgsr(
Path("examples/sgsr_sampling/structure.asc"),
Path("tmp/sgsr_example"),
n_samples=24,
seed=42,
n_strata=3,
)
print(result.allocation)
print(result.strata)
print(result.samples.head())
The bridge writes:
allocation.csv— per-stratumstrataandtotalsample counts;samples.csv—x,y,strata,type, andrule;strata.csv— per-stratum cell count and metric min/max/mean;strata.tif— the structural strata raster; andmetadata.tsv— R/sgsR/terra/sf versions, licence, seed, and counts.
For the worked example the allocation is:
strata,total
1,8
2,8
3,8
The three strata contain 134, 133, and 133 cells. Their metric ranges are
approximately 7.0-11.486, 11.487-13.767, and 13.783-18.0.
Reproducibility
seed is required. Set the same metric, stratum count, allocation, method, and
seed to reproduce the same allocation and sample coordinates. The result
metadata records the seed, sgsR version, and GPL-3 licence.
The integration test runs the bridge twice and compares both the allocation and the sample table.
Errors and limits
A missing raster, constant raster, or raster with no valid cells raises a clear
SgsRError.A missing
RscriptorsgsRinstallation raisesSgsRErrorwith install guidance.n_samples < 1,n_strata < 2, an unknown allocation, an unknown method, or a negativemindistraisesValueError.The bridge does not add a new sampling theory, a LiDAR metric pipeline, a field campaign, or a FEMIC/ws4 model input. It is an adapter around the published sgsR workflow.
sgsR’s structural strata and allocation are only as meaningful as the input metric layer. The structural metric must be provided and validated by the user.
Tests
pytest tests/test_sgsr.py -q
The real bridge tests are skipped unless Rscript can load sgsR. The
argument, missing-input, missing-Rscript, and seed-required tests always run.
References
Goodbody, T.R.H., Coops, N.C., Queinnec, M., et al. (2023). sgsR: a structurally guided sampling toolbox for LiDAR-based forest inventories. Forestry: An International Journal of Forest Research. https://doi.org/10.1093/forestry/cpac055
Queinnec, M., White, J.C., & Coops, N.C. (2021). Comparing airborne and spaceborne photon-counting LiDAR canopy structural estimates across different boreal forest types. Remote Sensing of Environment, 262, 112510.
sgsR package: https://cran.r-project.org/package=sgsR (GPL >= 3).