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

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.