# -*- coding: utf-8 -*-
# SPDX-FileCopyrightText: 2022-2023 Tanguy Fardet
# SPDX-License-Identifier: GPL-3.0-or-later
# orgmatt/nutrients/nitrogen.py
import numpy as np
from pint import Quantity
from ..typing import NumericArrayLike, NumericOrArray, Optional
from .all_nutrients import (
nutrient_from_biowaste, nutrient_from_compound, nutrient_from_population)
__all__ = [
"nitrogen_from_population",
"nitrogen_from_urine",
"nitrogen_from_feces"
]
[docs]
def nitrogen_from_population(
pop: NumericOrArray,
duration: Quantity,
excreta: str = "all",
ci: int = 0,
q: Optional[NumericArrayLike] = None,
**kwargs
) -> Quantity:
'''
Compute the amount of nitrogen generated by a given population over a
certain duration using the ``food.csv`` or ``nutrients_excreted.csv``
database.
Parameters
----------
pop : float or array-like object
Number of inhabitants.
duration : Quantity (float) [time]
Time interval over which the nitrogen is excreted.
excreta : str (optional, default: "all")
Type of excreta ("urine", "feces", or "all").
ci : int (optional, default: 0)
Confidence interval (CI). If non-zero, the function will also return
the low and high expected values corresponding to that CI.
q : array-like of floats (optional: default: None)
Percentiles to compute (supersedes `ci`).
**kwargs : arguments to use a subset of the database
Additional arguments can be use to restrict the results to a subset of
the full database. E.g. one can add `excreta="feces"` to return only
nitrogen contained in feces, or `region="Europe"` to use only values
obtained from studies in European countries.
Returns
-------
nitrogen_mass : float or array of dimension D [mass]*[nitrogen]
Mean mass of excreted nitrogen if `q` is None or `ci` is 0. If `q` is
provided, returns the values associated to each percentile in `q` for
each entry in `pop`; otherwise one (low, mean, high) result per entry
in `pop`, giving the masses expected for the requested confidence
interval.
The dimension D is either 3, len(q), (len(pop), 3), or
(len(pop), len(q)) depending on `ci` and `q`.
'''
return nutrient_from_population(
pop, duration, "N", excreta=excreta, ci=ci, q=q, **kwargs)
[docs]
def nitrogen_from_urine(
amount: Quantity,
ci: int = 0,
q: Optional[NumericArrayLike] = None,
**kwargs
) -> Quantity:
'''
Compute the amount of nitrogen from a volume of urine using the
``excretion_content.csv`` database.
Parameters
----------
amount : Quantity (float or numpy array) [length]**3
Quantity of urine in liters or cubic meters.
ci : int (optional, default: 0)
Confidence interval (CI). If non-zero, the function will also return
the low and high expected values corresponding to that CI.
q : array-like of floats (optional: default: None)
Percentiles to compute (supersedes `ci`).
**kwargs : arguments to use a subset of the database
Additional arguments can be use to restrict the results to a subset of
the full database. E.g. one can add `group="adult"` to return only data
from adult individuals, or `region="Europe"` to use only values
obtained from studies in European countries.
Returns
-------
nitrogen_mass : float or array of dimension D [mass]*[nitrogen]
Mean mass of contained nitrogen if `q` is None or `ci` is 0. If `q` is
provided, returns the values associated to each percentile in `q` for
each entry in `amount`; otherwise one (low, mean, high) result per
entry in `amount`, giving the masses expected for the requested
confidence interval.
The dimension D is either 3, len(q), (len(amount), 3), or
(len(amount), len(q)) depending on `ci` and `q`.
'''
return nutrient_from_compound(amount, "N", "urine", ci=ci, q=q, **kwargs)
[docs]
def nitrogen_from_feces(
amount: Quantity,
ci: int = 0,
q: Optional[NumericArrayLike] = None,
wet: bool = True,
**kwargs
) -> Quantity:
'''
Compute the amount of nitrogen from a mass of feces using the
``excretion_content.csv`` database.
Parameters
----------
amount : Quantity (float or numpy array) [mass]
Mass of feces.
ci : int (optional, default: 0)
Confidence interval (CI). If non-zero, the function will also return
the low and high expected values corresponding to that CI.
q : array-like of floats (optional: default: None)
Percentiles to compute (supersedes `ci`).
wet : bool (optional, default: True)
Whether to compute the mass of wet feces (default) or dry solids.
**kwargs : arguments to use a subset of the database
Additional arguments can be use to restrict the results to a subset of
the full database. E.g. one can add `group="Adult"` to return only data
from adult individuals, or `region="Europe"` to use only values
obtained from studies in European countries.
Returns
-------
nitrogen_mass : float or array of dimension D [mass]*[nitrogen]
Mean mass of contained nitrogen if `q` is None or `ci` is 0. If `q` is
provided, returns the values associated to each percentile in `q` for
each entry in `amount`; otherwise one (low, mean, high) result per
entry in `amount`, giving the masses expected for the requested
confidence interval.
The dimension D is either 3, len(q), (len(amount), 3), or
(len(amount), len(q)) depending on `ci` and `q`.
'''
source = "feces (wet)" if wet else "feces (dry)"
return nutrient_from_compound(amount, "N", source, ci=ci, q=q, **kwargs)