nemora.sampling
Sampling utilities built on the distribution registry, including PDF-to-CDF conversion, direct draws, mixture sampling, bootstrap helpers, and the optional sgsR bridge.
See also
docs/howto/sampling.mdfor the Python sampling workflows.docs/howto/sgsr_sampling.mdfor the optional R/sgsR structurally guided sampling bridge and its licence/runtime trade-off.
Core sampling API
.. py:module:: nemora.sampling
Sampling utilities built on top of the Nemora distribution registry.
.. py:class:: BootstrapResult(samples, distribution, parameters, bins, tallies, resamples, sample_size, rng_seed=None) :module: nemora.sampling
Bases: :py:class:object
Container returned by :func:bootstrap_inventory when metadata is requested.
.. py:attribute:: BootstrapResult.bins :module: nemora.sampling :type: ~numpy.ndarray
.. py:attribute:: BootstrapResult.distribution :module: nemora.sampling :type: str
.. py:attribute:: BootstrapResult.parameters :module: nemora.sampling :type: ~collections.abc.Mapping[str, float]
.. py:attribute:: BootstrapResult.resamples :module: nemora.sampling :type: int
.. py:attribute:: BootstrapResult.rng_seed :module: nemora.sampling :type: int | None
.. py:attribute:: BootstrapResult.sample_size :module: nemora.sampling :type: int
.. py:attribute:: BootstrapResult.samples :module: nemora.sampling :type: list[~numpy.ndarray]
.. py:method:: BootstrapResult.stacked() :module: nemora.sampling
Return all bootstrap samples concatenated along axis 0.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~numpy.ndarray\``
.. py:attribute:: BootstrapResult.tallies :module: nemora.sampling :type: ~numpy.ndarray
.. py:method:: BootstrapResult.to_dataframe() :module: nemora.sampling
Return bootstrap samples as a DataFrame with resample identifiers.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pandas.DataFrame\``
.. py:class:: DBHBootstrap(stand_id, dbh_vectors, metadata, frame) :module: nemora.sampling :canonical: nemora.sampling.helpers.DBHBootstrap
Bases: :py:class:object
Structured representation of bootstrap DBH samples per stand.
.. py:attribute:: DBHBootstrap.dbh_vectors :module: nemora.sampling :type: dict[int, ~numpy.ndarray]
.. py:attribute:: DBHBootstrap.frame :module: nemora.sampling :type: ~pandas.DataFrame | None
.. py:attribute:: DBHBootstrap.metadata :module: nemora.sampling :type: dict[str, ~typing.Any]
.. py:attribute:: DBHBootstrap.stand_id :module: nemora.sampling :type: str | int | None
.. py:class:: SamplingConfig(grid_points=2048, support_multiplier=5.0, integration_method=’trapezoid’, quad_abs_tol=1e-08, quad_rel_tol=1e-06, cache_numeric_cdf=False) :module: nemora.sampling
Bases: :py:class:object
Configuration controlling numerical inversion/sampling behaviour.
.. py:attribute:: SamplingConfig.cache_numeric_cdf :module: nemora.sampling :type: bool
.. py:attribute:: SamplingConfig.grid_points :module: nemora.sampling :type: int
.. py:attribute:: SamplingConfig.integration_method :module: nemora.sampling :type: ~typing.Literal[‘trapezoid’, ‘simpson’, ‘quad’]
.. py:attribute:: SamplingConfig.quad_abs_tol :module: nemora.sampling :type: float
.. py:attribute:: SamplingConfig.quad_rel_tol :module: nemora.sampling :type: float
.. py:attribute:: SamplingConfig.support_multiplier :module: nemora.sampling :type: float
.. py:exception:: SgsRError :module: nemora.sampling :canonical: nemora.sampling.sgsr.SgsRError
Bases: :py:class:RuntimeError
Raised when the R/sgsR bridge cannot produce a sampling result.
.. py:class:: SgsRResult(output_dir, allocation, samples, strata, metadata, strata_path, samples_path, allocation_path) :module: nemora.sampling :canonical: nemora.sampling.sgsr.SgsRResult
Bases: :py:class:object
Portable outputs from one sgsR bridge run.
.. py:attribute:: SgsRResult.allocation :module: nemora.sampling :type: ~pandas.DataFrame
.. py:attribute:: SgsRResult.allocation_path :module: nemora.sampling :type: ~pathlib.Path
.. py:attribute:: SgsRResult.metadata :module: nemora.sampling :type: dict[str, str]
.. py:attribute:: SgsRResult.output_dir :module: nemora.sampling :type: ~pathlib.Path
.. py:property:: SgsRResult.sample_count :module: nemora.sampling :type: int
Number of returned samples.
.. py:attribute:: SgsRResult.samples :module: nemora.sampling :type: ~pandas.DataFrame
.. py:attribute:: SgsRResult.samples_path :module: nemora.sampling :type: ~pathlib.Path
.. py:attribute:: SgsRResult.strata :module: nemora.sampling :type: ~pandas.DataFrame
.. py:attribute:: SgsRResult.strata_path :module: nemora.sampling :type: ~pathlib.Path
.. py:function:: bootstrap_dbh_vectors(result, *, stand_id=None, include_frame=True, extra_metadata=None) :module: nemora.sampling
Convert a :class:BootstrapResult into per-resample DBH vectors.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.sampling.helpers.DBHBootstrap``
.. py:function:: bootstrap_inventory(fit, bins, tallies, *, resamples, sample_size, random_state=None, return_result=False) :module: nemora.sampling
Bootstrap stand tables by sampling from a fitted distribution.
When return_result is True a :class:BootstrapResult with metadata is returned
instead of a bare list of arrays.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\list`\ \[:py:class:`~numpy.ndarray`] | :py:class:`~nemora.sampling.BootstrapResult``
.. py:function:: pdf_to_cdf(distribution, params, *, method=’analytic’, grid=None, config=None) :module: nemora.sampling
Return a callable CDF for the requested distribution.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~collections.abc.Callable`\ \[\[:py:class:`~numpy.ndarray`], :py:class:`~numpy.ndarray`]`
.. py:function:: run_sgsr(metric_path, output_dir, *, n_samples, seed, n_strata=4, allocation=’prop’, method=’Queinnec’, mindist=None, rscript=’Rscript’, timeout=600.0, env=None) :module: nemora.sampling
Run sgsR quantile stratification and stratified sampling.
:type metric_path: :sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`~pathlib.Path` :param metric_path: Single-layer structural metric raster readable by ``terra`` (for example a GeoTIFF or ESRI ASCII grid). :type output_dir: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path` :param output_dir: Directory for the R bridge artifacts: ``strata.tif``, ``allocation.csv``, ``samples.csv``, ``strata.csv``, and ``metadata.tsv``. :type n_samples: :sphinx_autodoc_typehints_type::py:class:`int` :param n_samples: Target plot count. :type seed: :sphinx_autodoc_typehints_type::py:class:`int` :param seed: Required R RNG seed. The same metric and parameters must reproduce the same allocation and sample coordinates. :type n_strata: :sphinx_autodoc_typehints_type::py:class:`int` :param n_strata: Number of quantile strata. :type allocation: :sphinx_autodoc_typehints_type::py:class:`str` :param allocation: ``prop``, ``equal``, or ``optim``. :type method: :sphinx_autodoc_typehints_type::py:class:`str` :param method: ``Queinnec`` or ``random``. :type mindist: :sphinx_autodoc_typehints_type::py:class:`float` | :py:obj:`None` :param mindist: Optional minimum distance between samples, in the raster CRS units. :type rscript: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path` :param rscript: Path or command name for ``Rscript``. :type timeout: :sphinx_autodoc_typehints_type::py:class:`float` :param timeout: Subprocess timeout in seconds. :type env: :sphinx_autodoc_typehints_type::py:class:`~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`str`] | :py:obj:`None``
:param env: Optional environment overrides. Use this to set R_LIBS_USER when
sgsR is installed in a non-default R library.
:returns: Allocation table, sample coordinates, structural strata, and bridge metadata. :rtype: SgsRResult
:raises SgsRError: If R/sgsR is unavailable, the input is invalid, the metric is constant, or the bridge fails.
.. py:function:: sample_distribution(distribution, params, size, *, random_state=None, config=None) :module: nemora.sampling
Draw samples from a registered distribution.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~numpy.ndarray``
.. py:function:: sample_mixture_fit(fit, size, *, random_state=None, lower=None, upper=None, weight_overrides=None) :module: nemora.sampling
Sample from a :class:MixtureFitResult.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~numpy.ndarray``
sgsR bridge
.. py:module:: nemora.sampling.sgsr
Python bridge to the GPL-3 sgsR structurally guided sampling package.
sgsR is not copied or reimplemented here. The bridge calls the installed R package through a small bundled script and returns the allocation, samples, and structural strata as DataFrames.
The R bridge is optional: install R plus sgsR and its dependencies before
using :func:run_sgsr.
.. py:exception:: SgsRError :module: nemora.sampling.sgsr
Bases: :py:class:RuntimeError
Raised when the R/sgsR bridge cannot produce a sampling result.
.. py:class:: SgsRResult(output_dir, allocation, samples, strata, metadata, strata_path, samples_path, allocation_path) :module: nemora.sampling.sgsr
Bases: :py:class:object
Portable outputs from one sgsR bridge run.
.. py:attribute:: SgsRResult.allocation :module: nemora.sampling.sgsr :type: ~pandas.DataFrame
.. py:attribute:: SgsRResult.allocation_path :module: nemora.sampling.sgsr :type: ~pathlib.Path
.. py:attribute:: SgsRResult.metadata :module: nemora.sampling.sgsr :type: dict[str, str]
.. py:attribute:: SgsRResult.output_dir :module: nemora.sampling.sgsr :type: ~pathlib.Path
.. py:property:: SgsRResult.sample_count :module: nemora.sampling.sgsr :type: int
Number of returned samples.
.. py:attribute:: SgsRResult.samples :module: nemora.sampling.sgsr :type: ~pandas.DataFrame
.. py:attribute:: SgsRResult.samples_path :module: nemora.sampling.sgsr :type: ~pathlib.Path
.. py:attribute:: SgsRResult.strata :module: nemora.sampling.sgsr :type: ~pandas.DataFrame
.. py:attribute:: SgsRResult.strata_path :module: nemora.sampling.sgsr :type: ~pathlib.Path
.. py:function:: run_sgsr(metric_path, output_dir, *, n_samples, seed, n_strata=4, allocation=’prop’, method=’Queinnec’, mindist=None, rscript=’Rscript’, timeout=600.0, env=None) :module: nemora.sampling.sgsr
Run sgsR quantile stratification and stratified sampling.
:type metric_path: :sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`~pathlib.Path` :param metric_path: Single-layer structural metric raster readable by ``terra`` (for example a GeoTIFF or ESRI ASCII grid). :type output_dir: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path` :param output_dir: Directory for the R bridge artifacts: ``strata.tif``, ``allocation.csv``, ``samples.csv``, ``strata.csv``, and ``metadata.tsv``. :type n_samples: :sphinx_autodoc_typehints_type::py:class:`int` :param n_samples: Target plot count. :type seed: :sphinx_autodoc_typehints_type::py:class:`int` :param seed: Required R RNG seed. The same metric and parameters must reproduce the same allocation and sample coordinates. :type n_strata: :sphinx_autodoc_typehints_type::py:class:`int` :param n_strata: Number of quantile strata. :type allocation: :sphinx_autodoc_typehints_type::py:class:`str` :param allocation: ``prop``, ``equal``, or ``optim``. :type method: :sphinx_autodoc_typehints_type::py:class:`str` :param method: ``Queinnec`` or ``random``. :type mindist: :sphinx_autodoc_typehints_type::py:class:`float` | :py:obj:`None` :param mindist: Optional minimum distance between samples, in the raster CRS units. :type rscript: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path` :param rscript: Path or command name for ``Rscript``. :type timeout: :sphinx_autodoc_typehints_type::py:class:`float` :param timeout: Subprocess timeout in seconds. :type env: :sphinx_autodoc_typehints_type::py:class:`~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`str`] | :py:obj:`None``
:param env: Optional environment overrides. Use this to set R_LIBS_USER when
sgsR is installed in a non-default R library.
:returns: Allocation table, sample coordinates, structural strata, and bridge metadata. :rtype: SgsRResult
:raises SgsRError: If R/sgsR is unavailable, the input is invalid, the metric is constant, or the bridge fails.