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=) :module: nemora.uncertainty

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``