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.

Content#

MetabolicDataModel(age_group[, sex, diet, ...])

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).

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.

Details#

class orgmatt.metabolism.MetabolicDataModel(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.

Note

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

property age: str#

Return the age of the modeled person

property country: str | None#

Return the country of the modeled person

property diet: str | None#

Return the diet of the modeled person

flow_fraction(nutrient: str, flow: Literal['urine', 'feces', 'retention'], ci: int = 0, q: list[float] | ndarray[Any, dtype[floating | int64]] | None = None, ignore_missing: bool = True) → float | ndarray[Any, 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).

property group: str#

Return the age group of the modeled person

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[Any, dtype[floating | int64]] | None = None, ignore_missing: bool = True) → 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.

Returns:

excretion – Amount of nutrient excreted over duration.

Return type:

Quantity [mass]*[nutrient]

nutrient_intake(duration: Quantity, nutrient: str, ci: int = 0, q: list[float] | ndarray[Any, dtype[floating | int64]] | None = None, ignore_missing: bool = True) → Quantity[source]#

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’).

  • 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.

Returns:

intake – Intake of nutrient over duration.

Return type:

quantity

property region: str | None#

Return the region of the modeled person

urine_concentration(nutrient: str, water_intake: Quantity | None = None, ci: int = 0, q: list[float] | ndarray[Any, dtype[floating | int64]] | None = None) → Quantity[source]#

Average concentration of a nutrient in urine.

Parameters:

  • nutrient (str) – Nutrient of interest among (‘N’, ‘P’, ‘K’).

  • water_intake (float [length]**3, optional (default: inferred)) – Daily amount of water ingested over duration from all solids and liquids.

  • 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).

urine_excretion(duration: Quantity, water_intake: Quantity | None = None) → Quantity[source]#

Amount of urine excreted over duration.

Parameters:

  • duration (float [time]) – Time interval over which urine is excreted.

  • water_intake (float [length]**3, optional (default: inferred)) – Amount of water ingested over duration from all solids and liquids.

orgmatt.metabolism.body_composition(nutrient: str, ci: int = 0, q: list[float] | ndarray[Any, dtype[floating | int64]] | None = None, **kwargs) → float | ndarray[Any, dtype[floating | int64]][source]#

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[Any, dtype[floating | int64]] | None = None, **kwargs) → float | ndarray[Any, 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).

orgmatt.metabolism.fraction_nutrient_retention(nutrient: str, ci: int = 0, q: list[float] | ndarray[Any, dtype[floating | int64]] | None = None, **kwargs) → float | ndarray[Any, dtype[floating | int64]][source]#

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.