nemora.synthesis
Nemora’s synthesis package is beginning with helper utilities that translate sampling bootstrap results into the DataFrame/metadata payloads that future stem and stand generators will consume. These helpers standardise how downstream modules access provenance (distribution, parameters, bins, tallies) alongside the sampled stems.
See also
docs/howto/synthesis.mdfor the integration guide that outlines how bootstrap payloads power upcoming synthesis flows.docs/howto/ws4_synthetic_fixture.mdfor the deterministic WS4 build/simulate fixture.docs/howto/sampling.mdfor background onBootstrapResultand the bootstrap sampling APIs.
Helper API
.. py:module:: nemora.synthesis.helpers
Bootstrap helpers for synthesis (forest/stand/tree) consumers.
.. py:class:: BootstrapPayload(frame, stacked, metadata) :module: nemora.synthesis.helpers
Bases: :py:class:object
Structured payload for synthesis bootstrap consumers.
.. py:attribute:: BootstrapPayload.frame :module: nemora.synthesis.helpers :type: ~pandas.DataFrame
.. py:attribute:: BootstrapPayload.metadata :module: nemora.synthesis.helpers :type: dict[str, object]
.. py:attribute:: BootstrapPayload.stacked :module: nemora.synthesis.helpers :type: ~numpy.ndarray
.. py:class:: StandDBHSampler(assignment, entry, *, sampling_config=None) :module: nemora.synthesis.helpers
Bases: :py:class:object
Sampler that draws DBH values for a single stand.
.. py:method:: StandDBHSampler.draw(*, rng=None, sample_size=None, resample=None) :module: nemora.synthesis.helpers
Draw DBH values using the configured sampler.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~numpy.ndarray\``
.. py:attribute:: StandDBHSampler.sampler_type :module: nemora.synthesis.helpers :type: ~typing.Literal[‘bootstrap’, ‘analytic’]
.. py:function:: bootstrap_payload(result) :module: nemora.synthesis.helpers
Return a structured payload with stacked samples + metadata.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.synthesis.helpers.BootstrapPayload``
.. py:function:: bootstrap_to_dataframe(result, *, attach_metadata=True) :module: nemora.synthesis.helpers
Return a DataFrame view of a bootstrap result with optional metadata.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~pandas.DataFrame``
.. py:function:: build_dbh_samplers(manifest, *, sampling_config=None) :module: nemora.synthesis.helpers
Construct DBH samplers for each stand assignment in a manifest.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\list`\ \[:py:class:`~nemora.synthesis.helpers.StandDBHSampler`]`
WS4 synthetic fixture
.. py:module:: nemora.synthesis.ws4_fixture
Deterministic synthetic landscape exported for the WS4 build/simulate path.
The fixture is intentionally small and homogeneous: Voronoi fragments, three synthetic age classes, one species, and placeholder tree structure. It is an integration fixture, not a calibrated forest or a yield-model claim.
.. py:class:: Ws4SyntheticFixture(directory, seed, truth_table, metadata, recipe_path, fragments_path, schedule_path) :module: nemora.synthesis.ws4_fixture
Bases: :py:class:object
Loaded fixture metadata and truth table.
.. py:attribute:: Ws4SyntheticFixture.directory :module: nemora.synthesis.ws4_fixture :type: ~pathlib.Path
.. py:attribute:: Ws4SyntheticFixture.fragments_path :module: nemora.synthesis.ws4_fixture :type: ~pathlib.Path
.. py:attribute:: Ws4SyntheticFixture.metadata :module: nemora.synthesis.ws4_fixture :type: dict[str, ~typing.Any]
.. py:attribute:: Ws4SyntheticFixture.recipe_path :module: nemora.synthesis.ws4_fixture :type: ~pathlib.Path
.. py:attribute:: Ws4SyntheticFixture.schedule_path :module: nemora.synthesis.ws4_fixture :type: ~pathlib.Path
.. py:attribute:: Ws4SyntheticFixture.seed :module: nemora.synthesis.ws4_fixture :type: int
.. py:attribute:: Ws4SyntheticFixture.truth_table :module: nemora.synthesis.ws4_fixture :type: ~pandas.DataFrame
.. py:function:: curve_value(age) :module: nemora.synthesis.ws4_fixture
Interpolate the synthetic natural-volume curve at age.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\float``
.. py:function:: generate_ws4_fixture(output_dir, *, seed, count=12, aspect_ratio=1.5, area_ha=36.0, trees_per_ha=200.0) :module: nemora.synthesis.ws4_fixture
Generate a deterministic synthetic landscape and WS4 build inputs.
:type output_dir: :sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`~pathlib.Path` :param output_dir: Directory to write the fixture files into. :type seed: :sphinx_autodoc_typehints_type::py:class:`int` :param seed: Required random seed. The same seed and parameters reproduce the same fragment geometry, tree summaries, truth table, and fixture metadata. :type count: :sphinx_autodoc_typehints_type::py:class:`int` :param count: Number of Voronoi fragments. :type aspect_ratio: :sphinx_autodoc_typehints_type::py:class:`float` :param aspect_ratio: Landscape width divided by height in local coordinates. :type area_ha: :sphinx_autodoc_typehints_type::py:class:`float` :param area_ha: Total landscape area in hectares. Polygon coordinate areas are scaled to this total. :type trees_per_ha: :sphinx_autodoc_typehints_type::py:class:`float``
:param trees_per_ha: Target stem density used to size the placeholder tree list.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.synthesis.ws4_fixture.Ws4SyntheticFixture``
.. py:function:: load_ws4_fixture(directory) :module: nemora.synthesis.ws4_fixture
Load and validate a fixture directory, including its truth table.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.synthesis.ws4_fixture.Ws4SyntheticFixture``