Tutorial#

This page provides a walkthrough of the basic features of OrgMatt.

To run this tutorial, it is recommended to use either IPython or Jupyter, since they will provide automatic autocompletion of the various functions, as well as easy access to the docstring help. Otherwise your can use the orgmatt.help() function.

First, import the OrgMatt package (all code will assume this has been done):

>>> import orgmatt as om

Then, you will be able to use the help from IPython by typing, for instance:

>>> om.nutrients?

In Jupyter, the docstring can be viewed using Shift + Tab.

Overview#

OrgMatt contains different modules:

data to load the databases,
excreta to compute the amount of urine and feces generated by a population,
impacts to compute the impacts of different processes to deal with the organic matter,
metabolism to get more accurate information about the nutrient flows within the human body,
nutrients to compute the amount of nutrients generated by people or contained in a volume of urine or mass of feces,
units that contains the units.

These modules can be imported separately or accessed via

# import all content from a module
from orgmatt.units import *
# access the module
om.nutrients
# import the module under a specific name
import orgmatt.nutrients as omn

To compute the nutrients, use the associated module, for instance, those excreted by a population can be computed via

omn.nutrient_from_population(1000, 1*month, "K")

to get the potassium excreted by 1000 adults over a month; see nutrient_from_population() for details.

To find out which functions are present in a module, check their documentation (there is a link for each one in the Module section of the menubar on the right).

Science (and OrgMatt) requires units!#

Most functions in OrgMatt return dimensioned quantities (volumes of urine, mass of nutrients, etc), therefore units are everywhere.

You can find a list of units in the units module. As you will need the all the time, it is recommended to always do:

from orgmatt.units import *

This will make the following units available:

L for liters,
m for meters and $m^3$ ,
g, kg, and t for grams, kilograms, and tons,
day, week, and year for time,
various gases (CO2, CH4…), elements (C, N, K, P…), and their associated masses (gCO2, kgN, tC),
and the GHG unit CO2e ( $\text{CO}_2$ equivalents) with its massic variants (gCO2e, kgCO2e, tCO2e).

All units (including standard physical units not listed above) are also available via the ureg variable

ureg.acre

To compute the amount of nitrogen generated by 100 persons over a week, one should thus use the week unit:

ngen = om.nutrients.nitrogen_from_population(100, 1*week)

The result, ngen is a pint.Quantity with a magnitude, a unit, and a dimensionality:

ngen.m gives the magnitude (somewhere around 10),
ngen.u gives the unit (kgN, kilogram of nitrogen),
ngen.dimensionality gives {"[mass]": 1, "nitrogen": 1}.

Data#

OrgMatt makes use of a lot of data to compute the values returned by all its functions, some of the entries in the databases use accronyms for brevity.

To get additional information about (hopefully) any data, use the help() function, e.g.

om.help("TOC")

returns the meaning of TOC: “Total Organic Carbon”.

The databases are contained in the orgmatt/data folder, as CSV files. The list of available datasets can be obtained via list_datasets(). Each individual dataset can then be accessed via its name and the get_dataset() function. An visual overview of the dataset can also be shown via plot_dataset().

See orgmatt.data for more details about the datasets.

Default values and auto-correction#

On the difficulty of providing sane default results#

In the databases, some values are present for different age and sex groups; for instance, we have data on food intake and excretion for “kids”, “adults”, “senior”, “female”, “male”, etc. If no constraint is provided to the function, we chose to return only values related to adults by default, i.e. not providing any input to the function is equivalent to setting group="adult". If you want to get results from all groups together, use group=None.

In the future, we may also make sure to properly average entries labelled “male” and “female”, such that default results are for an “average” population, or only return “mixed” results by default. However this is not the case at the moment, so some results may be lower or higher than the expected average depending on whether more entries were found for “female” or “male” subjects.

Accounting for variability#

By default, all functions return a weighted average from the database entries. This weighted average is computed by:

generating 20*(sample size) random variables from N(0, 1) for each entry
setting the deviation to the correct values by:
- if min/max values are present, multiplying the deviations by 2*(mean - mean) for negative values, 2*(max - mean) for positive values
- if only std is available, then all deviations are multiplied by it
- if no values are available, variations are multiplied by zero
adding the deviations to the mean value
taking the mean of all generated entries

In addition to returning the mean value, the functions can also return:

a confidence interval around the mean, via the ci parameter; e.g. for ci=90, the function returns [low, mean, high] values, with low corresponding to the 5th percentile and high corresponding to the 95th percentile,
any set of percentiles from the distribution via the q variable,
all generated values if ci is set to -1.

Auto-correcting results#

When no result in the database can fit all the requested constraints, the functions will usually return an NaN value (not a number). If you would like to get a real result even when all constraints cannot be honored, you can pass the auto_correct=True argument to most functions. When that argument is set, the function will drop the minimal amount of constraints that lead to a non-empty data table from which it can return a real value.

res = om.nutrients.nitrogen_from_population(
    1, 1*year, diet="vegan", sex="male", age="15-17", auto_correct=True)

To know which constraints were ignored, you can pass an empty list to the skipped_constraints argument and it will be populated with all the ignored constraints.

skipped = []

res = om.nutrients.nitrogen_from_population(
    1, 1*year, diet="vegan", sex="male", age="15-17", auto_correct=True,
    skipped_constraints=skipped)

print(skipped)

For human intake and excretion, you can go further by using the DataBasedMetabolicModel class that will automatically try to compute correction factors to account for the missing constraints.

from orgmatt.metabolism import DataBasedMetabolicModel

m = DataBasedMetabolicModel(age_group="15-17", diet="vegan", sex="male", country="FRA")

res = m.nutrient_excretion(1*year, "N")

Note

We initially used sex (and not gender) because that was the data available in the medical literature and it might make sense from a metabolic perspective as we see significant differences between the populations’ averages, despite obvious and very large inter-individual variability within groups. We are aware of the limitations of this denomination and binary division but hope that it will have limited impact for the purpose of this tool. We will replace “sex” with “gender” in a near future while keeping the “male”/”female” entries.