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