Speciation¶

Speciation in emiproc means splitting a substance in multiple sub=substances.

This can be used for example to split NOx in NO and NO2 or to split the anthropogenic and biogenic part of a CO2.

emiproc.speciation.speciate( inv: Inventory, substance: str, speciation_ratios: xr.DataArray, drop: bool = True, country_mask_kwargs: dict[str, Any] = {}, ) → Inventory¶

Speciate a substance in an inventory.

Note

Profiles (vertical and temporal) are not speciated. The profiles of the speciated substance are simply applied. If you have specific profiles for the speciated substance, you need to set them after the speciation operation.

Parameters:

inv – The inventory to speciate.
substance – The substance to speciate.

speciation_ratios –

The speciation ratios. See read_speciation_table() to load them from a file. The ratios must be a 2-D data array. One dimension is the substances to create with the speciation, the other dimension is called ‘speciation’ and each element is a set of ratios that sum to 1. Each speciation can be specific to a category, a country, a year, or a type. This is done by adding coordinates on the ‘speciation’ dimension.

<xarray.DataArray (speciation: 5, substance: 2)>
# Speciation ratios
array([[0.5, 0.5],
    [0.2, 0.8],
    [0.3, 0.7],
    [0.4, 0.6],
    [0.1, 0.9]])
Coordinates:
* speciation  (speciation) int64 0 1 2 3 4
* substance   (substance) <U7 'CO2_ANT' 'CO2_BIO'
# Optional dimensions which tell which combination of parameters the ratios apply to
    category    (speciation) <U4 'adf' 'liku' 'adf' 'liku' 'blek'
    type        (speciation) <U7 'gridded' 'gridded' 'gridded' 'shapped' 'shapped'
    year        (speciation) int64 2010 2010 2010 2010 2010

drop – Whether to drop the speciated substance.
country_mask_kwargs – If the speciation ratios depend on the country, this function is used to pass optional arguments to emiproc.utilities.get_country_mask().

emiproc.speciation.merge_substances( inv: Inventory, substances: dict[str, list[str]], drop: bool = True, inplace: bool = False, ) → Inventory¶

Merge substances in an inventory.

Can also be used to rename substances by merging them with a single substance and dropping the old one. ex merge_substances(inv, {‘NOx’: [‘NOX’]}, drop=True) to rename NOX to NOx.

Parameters:

inv – The inventory to merge substances.
substances – A dict with the substances to merge. The keys are the new substance names. The values are the list of substances to merge. ex: {‘NOx’: [‘NO’, ‘NO2’]} will merge NO and NO2 into NOx.
drop – Whether to drop the merged substances.
inplace – Whether to modify the inventory in place.

Returns:

The inventory with the merged substances.

Input/Output¶

emiproc.speciation.read_speciation_table(

path: PathLike,

drop_zeros: bool = False,

check_sum: bool = True,

**kwargs,

) → DataArray¶

Read a speciation table from a file.

Format of the file:

` # Any comment line starting with # is ignored # The first line is the header, it contains optional information # to specify speciation factors for each category. category,country,substance0,substance1,substance2, ... cat0,c0,0.5,0.2,0.1, ... cat1,c0,0.3,0.5,0.0, ... cat0,c1,0.2,0.3,0.5, ... ... `

The table can contain optional dimensions:

countrymust follow the ISO3 naming convention
In case cells belong to no country and have emissions, you will need to set a default value for the speciation ratios. This can be done by adding a row with the country set to -99.
category
type : Whether applies to ‘gridded’ or ‘shapped’
year

Ratios are the fraction of the weight of the speciated substance. As emissions are given in mass/unit of time, the sum of the ratios for a given speciiation must be 1.

Parameters:

path – The path of the speciation table.
drop_zeros – Whether to drop the speciation ratios that sum to 0.
check_consistency – Whether to check that the speciation ratios sum to 1. If this is set to False, the check is not performed.
kwargs – Additional arguments to pass to pandas.read_csv().

Returns:

The speciation ratios. The speciation ratios are the weight fraction conversion from the speciated substance.