nemora.validation
nemora.validation compares a plot-conditioned synthetic stand with held-out
inventory plots. It fits a DBH distribution and a height–DBH relation on
training trees, generates a seeded one-hectare-equivalent stand, and reports
metrics, distribution distance, species mix, and plot-resampling uncertainty.
This is a validation layer, not a spatial tree map or an operational planning tool.
.. py:module:: nemora.validation
Plot-conditioned stand validation utilities.
The validation compares a synthetic one-hectare-equivalent stand with held-out FAIB plots. It fits a DBH distribution and a height–DBH relation on training trees, generates a seeded synthetic tree list, and reports metrics, distribution distance, species mix, and plot-resampling uncertainty.
.. py:class:: ModelComparison(results, scores, selected) :module: nemora.validation
Bases: :py:class:object
Comparison of candidate stand models on one held-out plot set.
.. py:method:: ModelComparison.comparison_frame() :module: nemora.validation
Return a compact model-comparison table.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pandas.DataFrame\``
.. py:attribute:: ModelComparison.results :module: nemora.validation :type: tuple[~nemora.validation.StandValidationResult, …]
.. py:attribute:: ModelComparison.scores :module: nemora.validation :type: dict[str, float]
.. py:attribute:: ModelComparison.selected :module: nemora.validation :type: str
.. py:method:: ModelComparison.to_dict() :module: nemora.validation
Return a JSON-serializable comparison summary.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`
.. py:class:: StandMetrics(trees, stems_per_ha, basal_area_m2_per_ha, qmd_cm, mean_dbh_cm, mean_height_m, species_proportions) :module: nemora.validation
Bases: :py:class:object
Summary metrics for one observed plot or one synthetic stand.
.. py:attribute:: StandMetrics.basal_area_m2_per_ha :module: nemora.validation :type: float
.. py:attribute:: StandMetrics.mean_dbh_cm :module: nemora.validation :type: float
.. py:attribute:: StandMetrics.mean_height_m :module: nemora.validation :type: float | None
.. py:attribute:: StandMetrics.qmd_cm :module: nemora.validation :type: float
.. py:attribute:: StandMetrics.species_proportions :module: nemora.validation :type: dict[str, float]
.. py:attribute:: StandMetrics.stems_per_ha :module: nemora.validation :type: float
.. py:method:: StandMetrics.to_dict() :module: nemora.validation
Return a JSON-serializable mapping.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`
.. py:attribute:: StandMetrics.trees :module: nemora.validation :type: int
.. py:class:: StandValidationResult(training, holdout, synthetic, relative_errors, dbh_ks_weighted, species_tv_distance, fit_parameters, height_fit, uncertainty, bootstrap_replicates, successful_bootstrap, seed, holdout_plots, synthetic_trees, model=’pooled_weibull’) :module: nemora.validation
Bases: :py:class:object
Result of a plot-conditioned stand validation.
.. py:attribute:: StandValidationResult.bootstrap_replicates :module: nemora.validation :type: int
.. py:method:: StandValidationResult.comparison_frame() :module: nemora.validation
Return a tidy metric table for reports.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~pandas.DataFrame\``
.. py:attribute:: StandValidationResult.dbh_ks_weighted :module: nemora.validation :type: float
.. py:attribute:: StandValidationResult.fit_parameters :module: nemora.validation :type: dict[str, float]
.. py:attribute:: StandValidationResult.height_fit :module: nemora.validation :type: dict[str, float]
.. py:attribute:: StandValidationResult.holdout :module: nemora.validation :type: ~nemora.validation.StandMetrics
.. py:attribute:: StandValidationResult.holdout_plots :module: nemora.validation :type: dict[str, ~nemora.validation.StandMetrics]
.. py:attribute:: StandValidationResult.model :module: nemora.validation :type: str
.. py:attribute:: StandValidationResult.relative_errors :module: nemora.validation :type: dict[str, float | None]
.. py:attribute:: StandValidationResult.seed :module: nemora.validation :type: int
.. py:attribute:: StandValidationResult.species_tv_distance :module: nemora.validation :type: float
.. py:attribute:: StandValidationResult.successful_bootstrap :module: nemora.validation :type: int
.. py:attribute:: StandValidationResult.synthetic :module: nemora.validation :type: ~nemora.validation.StandMetrics
.. py:attribute:: StandValidationResult.synthetic_trees :module: nemora.validation :type: ~pandas.DataFrame
.. py:method:: StandValidationResult.to_dict() :module: nemora.validation
Return a JSON-serializable summary without the synthetic tree rows.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`
.. py:attribute:: StandValidationResult.training :module: nemora.validation :type: ~nemora.validation.StandMetrics
.. py:attribute:: StandValidationResult.uncertainty :module: nemora.validation :type: dict[str, dict[str, float]]
.. py:function:: compare_stand_models(training_trees, holdout_trees, *, bin_width_cm=2.0, area_ha=1.0, seed=20261030) :module: nemora.validation
Compare pooled, species-stratified, and empirical stand models.
The score is the mean absolute relative error over the five stand metrics plus the weighted DBH KS and species total-variation distance. Lower is better. The baseline is retained when scores tie or when no candidate improves.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.validation.ModelComparison``
.. py:function:: generate_empirical_stand(trees, *, area_ha=1.0, seed=20261030) :module: nemora.validation
Generate a one-hectare-equivalent empirical tree list.
This is a scenario/synthesis helper, not a validation result. It samples
training tree rows with replacement, weighted by tally.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~pandas.DataFrame``
.. py:function:: stand_metrics_from_trees(trees, *, area_ha=1.0) :module: nemora.validation
Compute stand metrics from tree rows with expansion tallies.
:type trees: :sphinx_autodoc_typehints_type:\:py\:class\:\~pandas.DataFrame` :param trees: Tree rows with ``dbh_cm``, ``tally``, optional ``height_m``, and optional ``species_code``. :type area_ha: :sphinx_autodoc_typehints_type::py:class:`float``
:param area_ha: Area represented by the rows. Observed FAIB plot rows use the default
one-hectare expansion; a synthetic stand can pass its actual area.
:raises KeyError: If required tree columns are missing.
:raises ValueError: If area_ha is not positive or no valid tree rows remain.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.validation.StandMetrics``
.. py:function:: validate_empirical_stand(training_trees, holdout_trees, *, area_ha=1.0, bootstrap_replicates=100, seed=20261030) :module: nemora.validation
Validate a plot-level empirical stand against held-out plots.
The empirical candidate samples training tree rows with replacement, weighted by their expansion tallies, and keeps the observed DBH/height pairs. It is a non-parametric alternative to the pooled Weibull model.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.validation.StandValidationResult``
.. py:function:: validate_plot_conditioned_stand(training_trees, holdout_trees, *, bin_width_cm=2.0, area_ha=1.0, bootstrap_replicates=100, seed=20261030) :module: nemora.validation
Fit and validate a synthetic stand against held-out plots.
:type training_trees: :sphinx_autodoc_typehints_type:\:py\:class\:\~pandas.DataFrame` :param training_trees: Tree rows from training plots, with ``PHF_TREE`` expansion tallies. :type holdout_trees: :sphinx_autodoc_typehints_type::py:class:`~pandas.DataFrame` :param holdout_trees: Tree rows from held-out plots. :type bin_width_cm: :sphinx_autodoc_typehints_type::py:class:`float` :param bin_width_cm: DBH histogram width for the grouped Weibull fit. :type area_ha: :sphinx_autodoc_typehints_type::py:class:`float` :param area_ha: Synthetic stand area. Metrics are reported per hectare. :type bootstrap_replicates: :sphinx_autodoc_typehints_type::py:class:`int` :param bootstrap_replicates: Plot-resampling replicates. Set to zero to skip uncertainty. :type seed: :sphinx_autodoc_typehints_type::py:class:`int``
:param seed: Seed for the synthetic stand and plot bootstrap.
:raises ValueError: If either input has no valid plots/trees or the fit has too few bins.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.validation.StandValidationResult``
.. py:function:: validate_species_weibull_stand(training_trees, holdout_trees, *, bin_width_cm=2.0, area_ha=1.0, min_species_trees=25, seed=20261030) :module: nemora.validation
Validate species-stratified Weibull fits against held-out plots.
Species with fewer than min_species_trees training records fall back to
the pooled Weibull fit. Rare-species overfitting is therefore reported
rather than hidden.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.validation.StandValidationResult``
See also
docs/howto/stand_validation.mdfor the workflow and metric definitions.docs/howto/plot_selection.mdfor the plot and tree-detail input.