Metabolism module#

This module provides information about the human metabolism.

This includes an estimation of the nutrient fractions that are excreted in urine and feces and a class to model that metabolism and provide consistent results between nutrient intake, excretion, and concentrations in excreta.

Age and gender#

Metabolic data can be provided for different age groups and genders. Genders are “male”, “female”, or “mixed”.

Age groups are separated as follow:

infants, less than 1 year-old (”< 1”),
toddlers, less than 4 year-old (“1-3”),
kids, up to 10 year-old (“4-10”),
teenagers (“11-17”),
adults (“18-64”), among which young adults (“18-24”),
seniors, above 65 (“>= 65”).

For age ranges that overlap several groups, the group with the largest overlap will be chosen.

Content#

`DataBasedMetabolicModel`(age_group[, sex, ...])	Data-only metabolic model to account for the consumption and excretion of an individual characterized by an age (group), a sex, a diet, and a localization (country or world region).
`Diet`(N_adult, P_adult, K_adult, Na_adult, ...)	Class storing a diet defined by the daily intakes of an average adult (18-64 age group).
`ReferenceHumanMetabolism`([diet])	Reference metabolic model that provides consistent results base on fixed excretion rates in urine and feces, as well as nutrient retention and various losses.
`body_composition`(nutrient[, ci, q])	Fraction of the body mass represented by nutrient.
`fraction_nutrient_excreta`(nutrient[, ...])	Fraction of the ingested nutrients that is excreted in urine and feces.
`fraction_nutrient_retention`(nutrient[, ci, q])	Fraction of a nutrient retained in the body during growth.
`get_diet`([diet])	Return a Diet or the dictionary of all pre-defined diets.
`intake_fraction_age`(age, adult_consumption)	Fraction of the adult intake consumed at a given age.

Details#

class orgmatt.metabolism.DataBasedMetabolicModel(age_group: str, sex: str | None = None, diet: str | None = None, country: str | None = None, region: str | None = None)[source]#

Data-only metabolic model to account for the consumption and excretion of an individual characterized by an age (group), a sex, a diet, and a localization (country or world region).

The model returns values present in the databases, potentially applying a correction to try to account for all requested characteristics. These corrections are computed, within the whole database, as the average contribution from the fields that were missing from the requested data. E.g. a Spanish vegan male teenager is requested but only “vegan male” is available in the database, so correction for “Spanish teenager” is computed, if this is also missing, correction for “Spanish” and “teenager” are applied separately. If one of the items is also missing, no correction is applied for this field and a warning is raised.

Warning

The consistency of all results is not guaranteed in this model, in particular, nutrient excretion in urine and feces may be greater than nutrient intake.

flow_fraction(nutrient: str, flow: Literal['urine', 'feces', 'retention'], ci: int = 0, q: list[float] | ndarray[tuple[int, ...], dtype[floating | int64]] | None = None, ignore_missing: bool = True, silent: bool = False) → float | ndarray[tuple[int, ...], dtype[floating | int64]][source]#

Fraction of a nutrient going in a type of flow (“urine”, “feces”, or “retention” in the body).

Parameters:

nutrient (str) – The nutrient of interest.
flow (str ("urine", "feces", or "retention")) – The flow considered.
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).
ignore_missing (bool, optional (default: True)) – Whether to raise an error or not if the value was not available and could not be properly corrected.
silent (bool, optional (default: False)) – Skip all errors and warnings (overrides ignore_missing).

property last_correction_status: int#

Number of corrections made to obtain the last returned value.

This can take the following values:

0 if the result was exact (directly present in the database)
-n < 0 if no correction could be provided for n separate fields
m > 0 if n individual corrections were combined to compute the final value

nutrient_excretion(duration: Quantity, nutrient: str, excreta: str = 'all', ci: int = 0, q: list[float] | ndarray[tuple[int, ...], dtype[floating | int64]] | None = None, ignore_missing: bool = True, silent: bool = False) → Quantity[source]#

Return the amount of nutrient excreted in urine and feces.

Warning

Computing excretion from urine and feces separately may lead to individual or combined excretions that are larger than the nutrient intake from food. Only excreta="all" is guaranteed to provide consistent results with the intake.

Parameters:

duration (float [time]) – Time interval over which the nitrogen is excreted.
nutrient (str) – Nutrient of interest among (‘N’, ‘K’, ‘P’, ‘Mg’, ‘Ca’).
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).
ignore_missing (bool, optional (default: True)) – Whether to raise an error or not if the value was not available and could not be properly corrected.
silent (bool, optional (default: False)) – Skip all errors and warnings (overrides ignore_missing).

Returns:

excretion – Amount of nutrient excreted over duration.

Return type:

Quantity [mass]*[nutrient]

class orgmatt.metabolism.Diet(N_adult: ~pint.registry.Quantity, P_adult: ~pint.registry.Quantity, K_adult: ~pint.registry.Quantity = <Quantity(nan, 'gK')>, Na_adult: ~pint.registry.Quantity = <Quantity(nan, 'gNa')>, water_intake: ~pint.registry.Quantity = <Quantity(2.5, 'liter')>, name: str = 'Custom', country: str = '', description: str = '')[source]#

Class storing a diet defined by the daily intakes of an average adult (18-64 age group).

N_adult#

Daily nitrogen intake for an average adult.

Type:: Quantity

P_adult#

Daily phosphorus intake for an average adult.

Type:: Quantity

K_adult#

Daily potassium intake for an average adult.

Type:: Quantity, optional (default: nan gK)

Na_adult#

Daily sodium intake for an average adult.

Type:: Quantity, optional (default: nan gNa)

water_intake#

Total amount of water ingested from solid and liquid intakes.

Type:: Quantity, optional (default: 2.5 L)

name#

Name of the diet.

Type:: str, optional (default: “Custom”)

country#

Country associated to the diet.

Type:: str, optional (default: “”)

description#

Description of the diet.

Type:: str, optional (default: “”)

class orgmatt.metabolism.ReferenceHumanMetabolism(diet: str | Diet | tuple[Quantity, ...] | None = None)[source]#

Reference metabolic model that provides consistent results base on fixed excretion rates in urine and feces, as well as nutrient retention and various losses. The model is consistent, meaning that the sum of all outputs and retention is always equal to the nutrient input from food.

This generic model provides approximate results for all age groups and sex/genders. The results for the excretions of an individual are computed based on the baseline ingestion from an average adult.

Note

This model should be rather good for most physiological conditions but will not provide relevant results for situations where extreme nutrient deprivation occurs. It may also deviate from experimental results for nutrient intakes that are significantly greater than recommended intakes.

Return the body composition for a given age and gender.

Parameters:

nutrient (str) – Nutrient of interest, either ‘N’ (nitrogen) pr ‘P’ (phosphorus).
age (int, array, or str, optional (default: "adult")) – Age or age group for which the nutrient intake should be calculated. Can be a year, a range of years like “18-44”, or a group among “infant”, “toddler”, “kid”, “teenager”, “young adult”, “adult”, “senior”.
sex ("male" or "female", optional (default: average value)) – Sex of the individual.

property diet#: Diet used in the model.

Fraction of a nutrient going in a type of flow (“urine”, “feces”, or “retention” in the body).

Parameters:

nutrient (str) – The nutrient of interest.
flow (str ("urine", "feces", or "retention")) – The flow considered.
age (int, array, or str, optional (default: "adult")) – Age or age group for which the nutrient intake should be calculated. Can be a year, a range of years like “18-44”, or a group among “infant”, “toddler”, “kid”, “teenager”, “young adult”, “adult”, “senior”.
sex ("male" or "female", optional (default: average value)) – Sex of the individual.

Returns:

fraction – Fraction of nutrient containd in flow. If age was an array, contains one entry per age.

Return type:

float or array of floats

Note

The retention fraction is generated such that, multiplied by the diet’s intakes, it gives the reference retention in g/day obtained in nutrient_retention.ipynb from US growth curves and body composition data. This means that models using different diets will lead to different fractions but identical absolute retention.

nutrient_excretion(duration: Quantity, nutrient: Literal['N', 'P', 'K'], excreta: Literal['urine', 'feces', 'all'] = 'all', age: float | ndarray[tuple[int, ...], dtype[floating | int64]] | str | None = None, sex: Literal['male', 'female'] | None = None) → Quantity[source]#

Return the amount of nutrient excreted in urine and/or feces.

Parameters:

duration (float [time]) – Time interval over which the nitrogen is excreted.
nutrient (str) – Nutrient of interest among (‘N’, ‘P’, ‘K’).
excreta (str (optional, default: "all")) – Type of excreta (“urine”, “feces”, or “all”).
age (int, array, or str, optional (default: "adult")) – Age or age group for which the nutrient intake should be calculated. Can be a year, a range of years like “18-44”, or a group among “infant”, “toddler”, “kid”, “teenager”, “young adult”, “adult”, “senior”.
sex ("male" or "female", optional (default: average value)) – Sex of the individual.

Returns:

excretion – Amount of nutrient excreted over duration. If age was an array, contains one entry per age.

Return type:

Quantity [mass]*[nutrient]

Return nutrient intake from food.

Parameters:

duration (float [time]) – Time interval over which the nitrogen is excreted.
nutrient (str) – Nutrient of interest among (‘N’, ‘K’, ‘P’, ‘Mg’, ‘Ca’).
age (int, array, or str, optional (default: "adult")) – Age or age group for which the nutrient intake should be calculated. Can be a year, a range of years like “18-44”, or a group among “infant”, “toddler”, “kid”, “teenager”, “young adult”, “adult”, “senior”.
sex ("male" or "female", optional (default: average value)) – Sex of the individual.

Returns:

intake – Intake of nutrient over duration. If age was an array, contains one entry per age.

Return type:

quantity

Return the amount of urine excreted. This is computed as 65% of the total water intake for a 25 year-old adult, $I_{H_2O}^{\text{tot}}$ . For individuals $y$ years old ( $y$ < 25`), it is defined as:

$V_u = V_u^{\text{min}} + \left(V_u^{(25yo)} - V_u^{\text{min}}\right) \cdot (1 - y / 25)$

where $V_u^{\text{min}} = \max(0.35 L, 0.16 \cdot I_{H_2O}^{\text{tot}})$ and $V_u^{(25yo)} = 0.65 \cdot I_{H_2O}^{\text{tot}}$ .

For individuals older than 25, it is defined as:

$V_u = V_u^{(25yo)} + 0.003 \cdot (y - 25)$

Parameters:

duration (float [time]) – Time interval over which the nitrogen is excreted.
age (int, array, or str, optional (default: "adult")) – Age or age group for which the nutrient intake should be calculated. Can be a year, a range of years like “18-44”, or a group among “infant”, “toddler”, “kid”, “teenager”, “young adult”, “adult”, “senior”.
sex ("male" or "female", optional (default: average value)) – Sex of the individual.

Returns:

volume – Volume of urine excreted over duration. If age was an array, contains one entry per age.

Return type:

Quantity [length]**3

Fraction of the body mass represented by nutrient.

Parameters:

nutrient (str) – Name of the nutrient (among “N”, “P”, “K”, “Ca”).
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 (dict, optional) – Additional arguments to constrain the result, e.g. “age”, “group”, “sex”, or “region”.

Return type:

A float in [0, 1) giving the fraction of body mass made of nutrient.

orgmatt.metabolism.fraction_nutrient_excreta(nutrient: str, excreta: Literal['urine', 'feces', 'all'] = 'all', ci: int = 0, q: list[float] | ndarray[tuple[int, ...], dtype[floating | int64]] | None = None, **kwargs) → float | ndarray[tuple[int, ...], dtype[floating | int64]][source]#

Fraction of the ingested nutrients that is excreted in urine and feces.

Other pathways notably include sweat, breathing, tegumen losses, and retention in bones and muscles before adulthood.

$f_{\text{excreta}}^{(n)} = 1 - f_{\text{other losses}}^{(n)} - f_{\text{retention}}^{(n)}$

Parameters:

nutrient (str) – The nutrient of interest.
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 specify an age or a group.

Returns:

A float in [0, 1) giving the fraction of the daily nutrient intake that
ends up in excreta (urine and feces combined).

Fraction of a nutrient retained in the body during growth.

Parameters:

nutrient (str) – The nutrient of interest.
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 specify an age or a group.

Returns:

A float in [0, 1) giving the fraction of the daily nutrient intake
retained in the body.

orgmatt.metabolism.get_diet(diet: str | Diet | tuple[Quantity, ...] | None = None) → Diet[source]#: Return a Diet or the dictionary of all pre-defined diets.

Fraction of the adult intake consumed at a given age.

Parameters:

age (float, int, str or array) – Age of the individual(s) in years. If a string is provided, it must be a group name, an integer or a range, e.g. (“4” or “16-20”).
adult_consumption (Quantity) – Average adult intake (mass of nitrogen, phosphorus, or potassium).
sex (str, optional (default: average value)) – Sex of the indivual(s).