Package: bonsai-ipcc
bonsai_ipccThebonsai_ipccpython package enables users to calculate national greenhouse gas (GHG) inventories based on the guidelines provided by the International Panel on Climate Change.By usingvolumesandchapters, the python package follows the structure of the IPCC guidelines and allows users to access individual equations and sequences of equations asbonsai_ipcc.<volume>.<chapter>.elementary.<equation>orbonsai_ipcc.<volume>.<chapter>.sequence.<tier_method>. The package allows users to access the data as Pandas dataframes inbonsai_ipcc.<volume>.<chapter>.dimension.<table>orbonsai_ipcc.<volume>.<chapter>.parameter.<table>: dimensions list valid coordinates to access parameters; parameters are values to be used in equations. When using thebonsai_ipccpython package, it may helpful to also use thepdf documentsfor additional information.The package also allows uncertainty information to be taken into account. Within a sequence, the user can choose between analytical error propagation and Monte Carlo simulation. Thereby, the values of an equation are transformed intoufloatornumpy.array, respectively.A comrehensive documentation is availablehere.Installation for usersYou can install the package from PyPi singpip:pipinstallbonsai_ipccYou can also download the package from gitlab.com
Replace the keywordtagby the specific version, e.g.,v0.3.0.pipinstallgit+ssh://git@gitlab.com/bonsamurais/bonsai/util/ipcc.git@tagChangepiptopip3in Linux. Note that the path may change in future versions.Installation for developersCreate a python environmentThebonsai_ipccpackage requirespython>=3.9. If you use conda as your python package manager, you could do something like:conda create --name py311 python=3.11
conda activate py311Install the package in editable modegitclonegit@gitlab.com:bonsamurais/bonsai/util/ipcc.gitcdbonsai_ipcc
pipinstall-e.Basic useInside a Python console or notebook, create an instance of theIPCCclass like this:importbonsai_ipccmy_ipcc=bonsai_ipcc.IPCC()Withmy_ipcc.<volume>.<chapter>thebonsai_ipccpackage follows the structure of the IPCC guidelines.
To show the elementary equations and sequences of a certain chapter in a specific volume:dir(my_ipcc.waste.swd.elementary)# dir(my_ipcc.waste.swd.sequence)To find information about a elementary equation:help(my_ipcc.waste.swd.elementary.ddoc_from_wd_data)The following will print the docstring with information on the parameters and the reqiured units:Help on function ddoc_from_wd_data in module bonsai_ipcc.waste.swd.elementary:

ddoc_from_wd_data_tier1(waste, doc, doc_f, mcf)
    Equation 3.2 (tier 1)

    Calculates the decomposable doc (ddocm) from waste disposal data.

    Argument
    ---------
    waste (tonnes) : float
        Amount of waste
        (either wet or dry-matter, but attention to doc!)
    doc (kg/kg) : float
        Fraction of degradable organic carbon in waste.
    doc_F (kg/kg) : float
        Fraction of doc that can decompose.
    mcf (kg/kg) : float
        CH4 correction factor for aerobic decomposition in the year of decompostion.

    Returns
    -------
    VALUE: float
        Decomposable doc (tonnes/year)To show the dimensions of a certain parameter:my_ipcc.waste.swd.parameter.mcf.index.namesFrozenList(['swds_type', 'property'])To find the possible values of a dimension:my_ipcc.waste.swd.dimension.swds_type.indexIndex(['managed', 'managed_well_s-a', 'managed_poorly_s-a', 'managed_well_a-a',
       'managed_poorly_a-a', 'unmanaged_deep', 'unmanaged_shallow',
       'uncharacterised'],
      dtype='object', name='code')To retrieve the value and the unit of a certain parameter.my_ipcc.waste.swd.parameter.mcf.loc[("managed","def")]value      1.0
unit     kg/kg
Name: (managed, def), dtype: objectRun a tier sequenceDespite the fact that various default data for parameter tables is provided within thebonsai_ipccpackage, in most cases, the user still needs to collect data to calculate the greenhouse gas inventories.
For thetier1_co2sequence in theincinerationchapter of volumewaste, data for urban population is required.
The data can be added as a pandas DataFrame.importbonsai_ipccimportpandasaspd# urban populationd={"year":[2010,2010,2010,2010,2010],"region":["DE","DE","DE","DE","DE"],"property":["def","min","max","abs_min","abs_max"],"value":[62940432,61996325.52,63884538.48,0.0,"inf",],"unit":["cap/yr","cap/yr","cap/yr","cap/yr","cap/yr",],}urb_pop=pd.DataFrame(d).set_index(["year","region","property"])my_ipcc=bonsai_ipcc.IPCC()my_ipcc.waste.incineration.parameter.urb_population=urb_popNOTE:When adding own data, the user is encouraged to also specify uncertainty information. Property "def" is always required and specifies the mean value. For uncertainty analysis "min", "max", "abs_min" and "abs_max" are required ("min": 2.5 percentile, "max": 97.5 percentile, "abs_min": absolute minimum, "abs_max": absolute maximum).To get a list of all parameters involved in the sequence, you can do:my_ipcc.inspect(my_ipcc.waste.incineration.sequence.tier1_co2)To calculate the GHG inventory based on a tier method, specifiy the keywords of the sequence:my_tier=my_ipcc.waste.incineration.sequence.tier1_co2(year=2010,region="DE",wastetype="msw_plastics",incintype="inc_unspecified",uncertainty="def")# show the list of steps of the sequencemy_tier.__dict__For uncertainty calculation based on Monte Carlo useuncertainty="monte_carlo", for analytical error propagation useuncertainty="analytical".To retrieve the result's value of a sequence's step, type:my_tier.co2_emissions.valueNOTE:The type ofvaluedepends on the uncertainty assessment. Foruncertainty = "def":type = float, foruncertainty = "analytical":type = ufloatand foruncertainty = "monte-carlo":type = numpy.array. Furthermore, some tier sequences provide time series instead of one single value. If so,valueis of typenumpy.array, including the values for different years. The type of each years' value also depend on the uncertainty assessment.