nemora.uncertainty module
.. py:module:: nemora.uncertainty
Curve uncertainty from observed/predicted ratios.
This module quantifies the uncertainty of an existing curve family. It does not
fit a new growth model. The input is a paired validation table: an observed
value and the curve’s prediction at the same stand. The ratio
observed / predicted is fitted with a positive-support distribution from the
Nemora registry, and the resulting interval becomes a multiplicative band.
The band is empirical. It inherits the validation sample’s bias, species mix, age range, and measurement error; it is not a parameter covariance from the original curve fit.
.. py:class:: CurveBand(distribution, parameters, level, sample_size, source=None, ratio_min=0.0, ratio_max=0.0, median_ratio=0.0, gof=
Bases: :py:class:object
A multiplicative curve band fitted to observed/predicted ratios.
.. attribute:: distribution
Registry name of the fitted positive-support distribution.
:type: str
.. attribute:: parameters
Fitted distribution parameters.
:type: dict[str, float]
.. attribute:: level
Nominal coverage level, for example ``0.90``.
:type: float
.. attribute:: sample_size
Number of validation pairs used for the fit.
:type: int
.. attribute:: source
Optional label for the validation source.
:type: str | None
.. attribute:: ratio_min, ratio_max, median_ratio
Observed ratio range and median, for diagnostics.
:type: float
.. attribute:: gof
Goodness-of-fit metrics returned by :func:`nemora.fit.fit_inventory`.
:type: dict[str, float]
.. py:method:: CurveBand.interval() :module: nemora.uncertainty
Return the lower and upper ratio quantiles for the band.
:returns: The ``(1 - level) / 2`` and ``1 - (1 - level) / 2`` quantiles of the
fitted distribution.
:rtype: tuple[float, float]
:raises ValueError: If the fitted distribution has no inverse CDF or the level is
outside ``(0, 1)``.
.. py:method:: CurveBand.to_dict() :module: nemora.uncertainty
Return a JSON-serializable description of the band.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`
.. py:function:: apply_ratio_band(predicted, band) :module: nemora.uncertainty
Apply a multiplicative band to predicted values.
:type predicted: :sphinx_autodoc_typehints_type:\:py\:data\:\~typing.Union`\ \[:py:class:`~numpy._typing._array_like._Buffer`, :py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]], :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]]], :py:class:`complex`, :py:class:`bytes`, :py:class:`str`, :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`complex` | :py:class:`bytes` | :py:class:`str`]] :param predicted: Central predicted values. Must be positive. :type predicted: array-like :type band: :sphinx_autodoc_typehints_type::py:class:`~nemora.uncertainty.CurveBand``
:param band: Fitted band.
:type band: CurveBand
:returns: Lower and upper bounds, in the same shape as predicted.
:rtype: tuple[numpy.ndarray, numpy.ndarray]
:raises ValueError: If a predicted value is not positive.
.. py:function:: band_coverage(observed, predicted, band) :module: nemora.uncertainty
Return the fraction of observations inside the band.
:type observed: :sphinx_autodoc_typehints_type:\:py\:data\:\~typing.Union`\ \[:py:class:`~numpy._typing._array_like._Buffer`, :py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]], :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]]], :py:class:`complex`, :py:class:`bytes`, :py:class:`str`, :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`complex` | :py:class:`bytes` | :py:class:`str`]] :param observed: Observed values. :type observed: array-like :type predicted: :sphinx_autodoc_typehints_type::py:data:`~typing.Union`\ \[:py:class:`~numpy._typing._array_like._Buffer`, :py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]], :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]]], :py:class:`complex`, :py:class:`bytes`, :py:class:`str`, :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`complex` | :py:class:`bytes` | :py:class:`str`]] :param predicted: Central predictions. :type predicted: array-like :type band: :sphinx_autodoc_typehints_type::py:class:`~nemora.uncertainty.CurveBand``
:param band: Fitted band.
:type band: CurveBand
:returns: Fraction of paired observations with
lower <= observed <= upper.
:rtype: float
:raises ValueError: If the paired arrays are invalid.
.. py:function:: fit_ratio_band(observed, predicted, *, distribution=’weibull’, bins=25, level=0.9, source=None) :module: nemora.uncertainty
Fit a multiplicative band to observed/predicted ratios.
:type observed: :sphinx_autodoc_typehints_type:\:py\:data\:\~typing.Union`\ \[:py:class:`~numpy._typing._array_like._Buffer`, :py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]], :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]]], :py:class:`complex`, :py:class:`bytes`, :py:class:`str`, :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`complex` | :py:class:`bytes` | :py:class:`str`]] :param observed: Observed values from the validation sample. :type observed: array-like :type predicted: :sphinx_autodoc_typehints_type::py:data:`~typing.Union`\ \[:py:class:`~numpy._typing._array_like._Buffer`, :py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]], :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]]], :py:class:`complex`, :py:class:`bytes`, :py:class:`str`, :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`complex` | :py:class:`bytes` | :py:class:`str`]] :param predicted: Curve predictions for the same observations. :type predicted: array-like :type distribution: :sphinx_autodoc_typehints_type::py:class:`str` :param distribution: Positive-support distribution from the Nemora registry. Defaults to ``"weibull"``. :type distribution: str, optional :type bins: :sphinx_autodoc_typehints_type::py:class:`int` | :py:class:`~collections.abc.Sequence`\ \[:py:class:`float`] :param bins: Histogram bins used to turn the raw ratios into grouped tallies for the existing fitting stack. Defaults to 25. :type bins: int or sequence of float, optional :type level: :sphinx_autodoc_typehints_type::py:class:`float` :param level: Nominal coverage level. Defaults to ``0.90``. :type level: float, optional :type source: :sphinx_autodoc_typehints_type::py:class:`str` | :py:obj:`None``
:param source: Optional validation-source label.
:type source: str | None, optional
:returns: Fitted band and diagnostics. :rtype: CurveBand
:raises ValueError: If the arrays are invalid, the level is outside (0, 1), the
distribution has no inverse CDF, or the fit fails.
.. py:function:: read_validation_csv(path, *, observed_column, predicted_column, filter_column=None, filter_value=None) :module: nemora.uncertainty
Read observed/predicted pairs from a CSV validation table.
:type path: :sphinx_autodoc_typehints_type:\:py\:class\:\~pathlib.Path` :param path: CSV file. :type path: pathlib.Path :type observed_column: :sphinx_autodoc_typehints_type::py:class:`str` :param observed_column: Column holding the observed values. :type observed_column: str :type predicted_column: :sphinx_autodoc_typehints_type::py:class:`str` :param predicted_column: Column holding the curve predictions. :type predicted_column: str :type filter_column: :sphinx_autodoc_typehints_type::py:class:`str` | :py:obj:`None` :param filter_column: Optional categorical filter column. :type filter_column: str | None, optional :type filter_value: :sphinx_autodoc_typehints_type::py:class:`str` | :py:obj:`None``
:param filter_value: Value to retain in filter_column.
:type filter_value: str | None, optional
:returns: Observed and predicted arrays. :rtype: tuple[numpy.ndarray, numpy.ndarray]
:raises ValueError: If a required column is missing or the filtered table is empty.
.. py:function:: write_band_csv(path, *, age, predicted, band) :module: nemora.uncertainty
Write a per-observation band table to CSV.
:type path: :sphinx_autodoc_typehints_type:\:py\:class\:\~pathlib.Path` :param path: Destination CSV path. :type path: pathlib.Path :type age: :sphinx_autodoc_typehints_type::py:data:`~typing.Union`\ \[:py:class:`~numpy._typing._array_like._Buffer`, :py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]], :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]]], :py:class:`complex`, :py:class:`bytes`, :py:class:`str`, :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`complex` | :py:class:`bytes` | :py:class:`str`]] :param age: Age or x-axis values aligned with ``predicted``. :type age: array-like :type predicted: :sphinx_autodoc_typehints_type::py:data:`~typing.Union`\ \[:py:class:`~numpy._typing._array_like._Buffer`, :py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]], :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`~numpy._typing._array_like._SupportsArray`\ \[:py:class:`~numpy.dtype`\ \[:py:data:`~typing.Any`]]], :py:class:`complex`, :py:class:`bytes`, :py:class:`str`, :py:class:`~numpy._typing._nested_sequence._NestedSequence`\ \[:py:class:`complex` | :py:class:`bytes` | :py:class:`str`]] :param predicted: Central predictions. :type predicted: array-like :type band: :sphinx_autodoc_typehints_type::py:class:`~nemora.uncertainty.CurveBand``
:param band: Fitted band.
:type band: CurveBand
:raises ValueError: If the arrays are invalid or the band cannot be applied.
:rtype: :sphinx_autodoc_typehints_type:\:py\:obj\:\None``