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, and sf R packages must be installed;

  • users may need to set R_LIBS_USER when sgsR is 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-stratum strata and total sample counts;

  • samples.csv — x, y, strata, type, and rule;

  • strata.csv — per-stratum cell count and metric min/max/mean;

  • strata.tif — the structural strata raster; and

  • metadata.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 Rscript or sgsR installation raises SgsRError with install guidance.

  • n_samples < 1, n_strata < 2, an unknown allocation, an unknown method, or a negative mindist raises ValueError.

  • 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).