Configuration

RE-Emission relies on a number of external configuration text files located in reemission/config and reemission/parameters. These configuration files allow modification of the package’s parameters and options, such as types of emission models (when alternative mdels are available), model parameters such as e.g. emission coefficients, nitrogen and phosphorus exports from land, emission coefficients of different land cover types, etc. The configuration files are provided in three different formats: ini, yaml and toml depending on the usage of the configuration file.

Note

We are working on adding a functionality that will allow the user to modify configuration files programmatically. For now, in order to modify the config file, the users need to find the file in the installation directory and modify it manually using a text editor.

Configuration files uses

  1. Application-wide configuration in app_config.yaml.

  2. Emission modelling configurations in config.ini.

  3. Output and Reporting configurations in inputs.yaml, outputs.yaml, parameters.yaml and internal_vars.yaml.

  4. Pre-impoundment emissions and landscape Nitrogen and Phosphorus exports in various .yaml files in reemission/parameters.

  5. Phosphorus removal efficiencies of different wastewater treatment technologies in phosphorus_loads.yaml.

  6. Visualisation and integration with GeoCARET in geocaret.toml and visualisation.toml.

Listings

1. Application-wide configuration

Application-wide configuration is used set the parameters of the logger, the \(\LaTeX\) compiler, and the locations of files used in the demo.

app_config.yaml
 1---
 2logging:
 3  level: DEBUG
 4  log_dir: '../../tmp/reemission'
 5  log_filename: reemission.log
 6  mode: w # w for writing and a for append
 7latex:
 8  compiler: pdflatex # pdflatex, latexmk, default
 9  clean_tex: True
10  compilations: 2
11demo_data:
12  dam_db:
13    url: ""
14    folder: "../../examples/demo/dams_shape"
15    file: "demo_dams.shp"
16  delineations:
17    url: ""
18    folder: "../../examples/demo/delinations"
19    file: ""
20...

2. Emission modelling parameters

This configuration .ini file is used to set the values of the emission model parametsr for the [CARBON_DIOXIDE], [METHANE] and [NITROUS OXIDE] emissions. The [CALCULATIONS] section sets different simulation/calculation options.

config.ini
 1[CARBON_DIOXIDE]
 2# Parameters reated to CO2 emissions
 3k1_diff = 1.860
 4k2_diff = -0.330
 5k3_diff = 0.0332
 6k4_diff = 0.0799
 7k5_diff = 0.0155
 8k6_diff = 0.2263
 9k7_diff = -0.32996
10# Atomic masses for conversion (g/mol)
11weight_C = 12
12weight_CO2 = 44
13# Conversion from g~CO2-C~m-2~d-1 to g~CO2e~m-2~yr-1
14
15# Based on stoichiometric relationship CO2/C = 44/12 and GWP100 of 1.0
16conv_coeff = 3.667
17# Global Warming Potential of CO2 over 100 years
18co2_gwp100 = 1.0
19# Global Warming Potential of CO2 over 20 years
20co2_gwp20 = 1.0
21
22[METHANE]
23# Parameters reated to CH4 emissions
24# CH4 diffusion
25k1_diff = 0.8032
26k2_diff = -0.01419
27k3_diff = 0.4594
28k4_diff = 0.04819
29# CH4 ebullition / bubbling emissions
30k1_ebull = -1.3104
31k2_ebull = 0.8515
32k3_ebull = 0.05198
33# CH4 degassing
34k1_degas = -6.9106
35k2_degas = 0.6017
36k3_degas = 2.9499679
37k4_degas = -0.014187
38# Conversion from mg CH4~m-2~d-1 to g~CO2e~m-2~yr-1
39# Atomic masses for conversion (g/mol)
40weight_C = 12
41weight_CO2 = 44
42weight_CH4 = 16
43# Based on stoichiometry between CH4-C and CO2e of 16/12 and GWP100 of 34
44conv_coeff = 16.55
45# Global Warming Potential of CH4 (28–36) over 100 years
46ch4_gwp100 = 34.0
47# Global Warming Potential of CH4 over 20 years
48ch4_gwp20 = 86.0
49
50[NITROUS_OXIDE]
51# Parameters reated to N2O emissions
52# Conversion from µg N2O-N m-2 day-1 to g~CO2e~m-2~yr-1
53# Based on stoichiometry between N2O-N and CO2e of 44/28 and GWP100 of 298
54conv_coeff = 0.170924
55# Global Warming Potential of N2O (265–298) over 100 years
56nitrous_gwp100 = 298.0
57# Global Warming Potential of N2O over 20 years
58nitrous_gwp20 = 500.0
59# Atomic masses (molar weights) (g/mol)
60weight_O = 16
61weight_P = 30.97
62weight_N = 14.0
63
64[CALCULATIONS]
65# Permissible rel. error in catchment area fractions
66eps_catchment_area_fractions = 0.01
67# Permissible rel. error in reservoir area fractions.
68eps_reservoir_area_fractions = 0.01
69# Calculation of P retention coefficient in reservoirs
70# Available methods: 'empirical' & 'larsen'
71ret_coeff_method = empirical
72# Calculation of annual total phosphorus loading to reservoirs
73# Available methods: 'g-res' % 'mcdowell'
74p_export_cal = g-res
75# Available models: model_1 and model_2
76nitrous_oxide_model = model_1
77# Use reduced ns_catchment, i.e. catchment - reservoir for P exports
78use_ns_catchment = true

3. Output and Reporting configuration

These configuration files set the presentation options for model inputs, outputs, parameters and intermediate variables. These settings are used in the Presenter class during creation of calculation outputs files - see Reporting of Outputs for examples.

Information for each variable follows a similar structure, see example of the output variable co2_diffusion representing calculated \(CO_2\) emission via diffusion. :

# CO2 emission through diffusion
co2_diffusion:
 include: True
 name: "CO2 diffusion flux"
 gas_name: "CO2"
 name_latex: "CO$_2$ diffusion flux"
 unit: "gCO2eq m-2 yr-1"
 unit_latex: "gCO$_{2,eq}$ m$^{-2}$ yr$^{-1}$"
 long_description: "Total CO2 emissions from a reservoir integrated over lifetime"
 hint: ""

  • include: (boolean): If the variable is to be included in the output files for reporting.

  • name: (string): Name of the variable

  • gas_name: Name of the gas which the (output) variable belongs to.

  • name_latex: (string): Name of the variable in \(\LaTeX\) format.

  • unit: (string): Unit in text format.

  • unit_latex: (string): Unit in \(\LaTeX\) format.

  • long_description: (string): Description of the variable.

  • hint: (string): Additional information about the variable.

Not all categories of variables contain the same information, e.g. inputs do not have names in \(\LaTeX\) format but the differences are small.


inputs.yaml
  1---
  2# Inputs to save for reporting of results
  3coordinates:
  4  include: True
  5  name: "Reservoir coordinates (lat/lon)"
  6  long_description: ""
  7  unit: "deg"
  8  unit_latex: "$^o$"
  9id:
 10  include: True
 11  name: "Reservoir ID"
 12  long_description: ""
 13  unit: ""
 14  unit_latex: ""
 15type:
 16  include: True
 17  name: "Reservoir type"
 18  long_description: ""
 19  unit: ""
 20  unit_latex: ""
 21monthly_temps:
 22  include: True
 23  name: "Monthly Temperatures"
 24  long_description: ""
 25  unit: "deg C"
 26  unit_latex: "$^o$C"
 27biogenic_factors:
 28  include: True
 29  name: "Biogenic factors"
 30  long_description: "Biome, Climate, Soil Type, Treatment Factor, Landuse Intensity"
 31  unit: ""
 32  unit_latex: ""
 33year_profile:
 34  include: True
 35  name: "Year vector for emission profiles"
 36  long_description: "List of years for which emission profiles are calculated"
 37  unit: "yr"
 38  unit_latex: "yr"
 39gasses:
 40  include: True
 41  name: "Calculated gas emissions"
 42  long_description: "List of gasses included in GHG emission calculations"
 43  unit: "-"
 44  unit_latex: "-"
 45catchment_inputs:
 46  include: True
 47  name: "Inputs for catchment-level process calculations"
 48  long_description: ""
 49  var_dict:
 50    runoff:
 51      name: "Annual runoff"
 52      unit: "mm/year"
 53      unit_latex: "mm/year"
 54    area:
 55      name: "Catchment area"
 56      unit: "km2"
 57      unit_latex: "km$^2$"
 58    riv_length:
 59      name: "Length of inundated river"
 60      unit: "km"
 61      unit_latex: "km"
 62    population:
 63      name: "Population"
 64      unit: "capita"
 65      unit_latex: "capita"
 66    area_fractions:
 67      name: "Area fractions"
 68      unit: "-"
 69      unit_latex: "-"
 70    slope:
 71      name: "Mean catchment slope"
 72      unit: "%"
 73      unit_latex: "\\%"
 74    precip:
 75      name: "Mean annual precipitation"
 76      unit: "mm/year"
 77      unit_latex: "mm/year"
 78    etransp:
 79      name: "Mean annual evapotranspiration"
 80      unit: "mm/year"
 81      unit_latex: "mm/year"
 82    soil_wetness:
 83      name: "Soil wetness"
 84      unit: "mm over profile"
 85      unit_latex: "mm over profile"
 86    mean_olsen:
 87      name: "Soil Olsen P content"
 88      unit: "kgP/ha"
 89      unit_latex: "kgP ha$^{-1}$"
 90reservoir_inputs:
 91  include: True
 92  name: "Inputs for reservoir-level process calculations"
 93  long_description: ""
 94  var_dict:
 95    volume:
 96      name: "Reservoir volume"
 97      unit: "m3"
 98      unit_latex: "m$^3$"
 99    area:
100      name: "Reservoir area"
101      unit: "km2"
102      unit_latex: "km$^2$"
103    max_depth:
104      name: "Maximum reservoir depth"
105      unit: "m"
106      unit_latex: "m"
107    mean_depth:
108      name: "Mean reservoir depth"
109      unit: "m"
110      unit_latex: "m"
111    area_fractions:
112      name: "Inundated area fractions"
113      unit: "-"
114      unit_latex: "-"
115    soil_carbon:
116      name: "Soil carbon in inundated area"
117      unit: "kgC/m2"
118      unit_latex: "kgC m$^{-2}$"
119    mean_radiance:
120      name: "Mean monthly horizontal radiance"
121      unit: "kWh/m2/d"
122      unit_latex: "kWh m$^{-2}$ d$^{-1}$"
123    mean_radiance_may_sept:
124      name: "Mean monthly horizontal radiance: May - Sept"
125      unit: "kWh/m2/d"
126      unit_latex: "kWh m$^{-2}$ d$^{-1}$"
127    mean_radiance_nov_mar:
128      name: "Mean monthly horizontal radiance: Nov - Mar"
129      unit: "kWh/m2/d"
130      unit_latex: "kWh m$^{-2}$ d$^{-1}$"
131    mean_monthly_windspeed:
132      name: "Mean monthly wind speed"
133      unit: "m/s"
134      unit_latex: "m s$^{-1}$"
135    water_intake_depth:
136      name: "Water intake depth below surface"
137      unit: "m"
138      unit_latex: "m"
139
140print_long_descriptions: False
141...

4a. Pre-impoundment emissions

Pre-impoundment emissions are emissions of landscape prior to reservoir creation. Pre-impoundment emissions depend on

Carbon_Dioxide/pre-impoundment.yaml
 1---
 2# Pre impoundment CO2 emission factors (tCO2-C/ha/yr) for land cover
 3# categories of inundated area – IHA land use categories.
 4
 5# Water bodies: n/a.
 6boreal:
 7  mineral:
 8    bare: 0.0
 9    crops: 0.0
10    forest: -0.4
11    shrubs: 0.0
12    urban: 0.0
13    wetlands: 0.0
14  organic:
15    bare: 2.8
16    crops: 7.9
17    forest: 0.6
18    shrubs: 5.7
19    urban: 6.4
20    wetlands: -0.5
21subtropical:
22  mineral:
23    bare: 0.0
24    crops: 0.0
25    forest: -1.4
26    shrubs: 0.0
27    urban: 0.0
28    wetlands: 0.0
29  organic:
30    bare: 2.0
31    crops: 11.7
32    forest: 2.6
33    shrubs: 9.6
34    urban: 6.4
35    wetlands: 0.1
36temperate:
37  mineral:
38    bare: 0.0
39    crops: 0.0
40    forest: -0.9
41    shrubs: 0.0
42    urban: 0.0
43    wetlands: 0.0
44  organic:
45    bare: 2.8
46    crops: 7.9
47    forest: 0.0
48    shrubs: 5.0
49    urban: 6.4
50    wetlands: -0.5
51tropical:
52  mineral:
53    bare: 0.0
54    crops: 0.0
55    forest: -1.4
56    shrubs: 0.0
57    urban: 0.0
58    wetlands: 0.0
59  organic:
60    bare: 2.0
61    crops: 11.7
62    forest: 15.3
63    shrubs: 9.6
64    urban: 6.4
65    wetlands: 0.0
66...

4b. Landscape N and P exports

McDowell/landscape_TN_export.yaml
 1---
 2# McDowell et al. 2020 landscape TN export model
 3# Regression model based on global empirical solute data
 4# Biomes categorical as intercept terms.
 5# Model predicts natural log (mg/L) to which the bias correction factor is
 6# applied. The mean annual catchment TN loading (kg yr-1) is then the predicted
 7# concentration (mg/L) * annual discharge (m3 yr-1) * 10-3
 8# Units and descriptions
 9# mean_prec: Mean precipitation (mean monthly, mm)
10# mean_slope: Mean slope of the catchment (%)
11# cropland: Percent of catchment area covered with croplands (%)
12# soil_wet: Soil wetness (mm over profile)
13# corr: Bias correction factor (-)
14# coeff_det: Coefficient of determination (-)
15# Biomes
16# deserts: deserts & xeric shrublands
17# mediterreanan forest: mediterranean forests, woodlands & scrub
18# montane grasslands: montane grasslands & shrublands
19# temperate broadleaf and mixed: temperate broadleaf & mixed forests
20# temperate coniferous: temperate conifer forests
21# temperate grasslands: temperate grasslands, savannas & shrublands
22# tropical dry broadleaf: tropical & subtropical dry broadleaf forests
23# tropical grasslands: tropical & subtropical grasslands, savannas & shrublands
24# tropical moist broadleaf: tropical & subtropical moist broadleaf forests
25# tundra: tundra
26intercept:
27  coeff: -1.5181
28  se: 0.2136
29mean_prec:
30  coeff: -0.0089
31  se: 0.0012
32mean_slope:
33  coeff: -0.1838
34  se: 0.0193
35cropland:
36  coeff: 0.0106
37  se: 0.0011
38soil_wet:
39  coeff: 0.0055
40  se: 0.0015
41biome:
42  deserts:
43    coeff: 1.9935
44    se: 0.2435
45  mediterreanan forests:
46    coeff: 3.2782
47    se: 0.4312
48  montane grasslands:
49    coeff: 1.5238
50    se: 0.2471
51  temperate broadleaf and mixed:
52    coeff: 1.3245
53    se: 0.1829
54  temperate coniferous:
55    coeff: 1.8488
56    se: 0.2202
57  temperate grasslands:
58    coeff: 1.6756
59    se: 0.1891
60  tropical dry broadleaf:
61    coeff: 1.0801
62    se: 0.2509
63  tropical grasslands:
64    coeff: 0.5203
65    se: 0.2309
66  tropical moist broadleaf:
67    coeff: 1.2144
68    se: 0.2089
69  tundra:
70    coeff: 0.0
71    se: 0.0
72corr: 0.595
73coeff_det: 0.60
74...

5. Phosphorus removal efficiencies

phopshporus_loads.yaml
1---
2# Categories of water treatment representing the percent of phosphorus
3# human input that reaches the reservoir:
4# 1 means no removal, 0 means 100% removal
5no treatment: 1
6primary (mechanical): 0.9
7secondary biological treatment: 0.3
8tertiary: 0.1
9...

4. Visualisation and integration with GeoCARET

Note

These settings are only used for the purpose of running a demonstration of how RE-Emission can be run in conjuction with GeoCARET - see Demo. They are not needed for any other functionality of the software.

geocaret.toml
 1[calculations]
 2    # Combination of runoff/evapotranspiration/precipitation fields to be used for water-mass balancing at the catchment scale
 3    runoff_field = "c_mar_mm_alt2"
 4    # c_mar_mm for Fekete et al. / c_mar_mm_alt2 for terraclim data
 5    et_field = "c_mpet_mm"
 6    precipitation_field = "c_map_mm_alt1"
 7# Parameters of HEET tabular data output 
 8[tab_data]
 9    # Mandatory fields required for generating input file(s) to RE-EMISSION
10    mandatory_fields = [
11        "id", "type", "c_area_km2", "c_biome", "c_climate_zone", 'c_landcover_0', 
12        'c_landcover_1', 'c_landcover_2', 'c_landcover_3', 'c_landcover_4', 
13        'c_landcover_5', 'c_landcover_6', 'c_landcover_7', 'c_landcover_8', 
14        "c_mar_mm",  "c_map_mm", "c_masm_mm", "c_mean_olsen", "c_mean_slope_pc",
15        "c_mpet_mm", "n_population", "c_soil_type", "dam_height", "dam_lat", 
16        "dam_lon", "future_dam_model", "ms_length", "name", "r_area_km2",
17        'r_landcover_bysoil_0', 'r_landcover_bysoil_1', 'r_landcover_bysoil_2',
18        'r_landcover_bysoil_3', 'r_landcover_bysoil_4', 'r_landcover_bysoil_5',
19        'r_landcover_bysoil_6', 'r_landcover_bysoil_7', 'r_landcover_bysoil_8',
20        'r_landcover_bysoil_9', 'r_landcover_bysoil_10',
21        'r_landcover_bysoil_11', 'r_landcover_bysoil_12',
22        'r_landcover_bysoil_13', 'r_landcover_bysoil_14',
23        'r_landcover_bysoil_15', 'r_landcover_bysoil_16',
24        'r_landcover_bysoil_17', 'r_landcover_bysoil_18',
25        'r_landcover_bysoil_19', 'r_landcover_bysoil_20',
26        'r_landcover_bysoil_21', 'r_landcover_bysoil_22',
27        'r_landcover_bysoil_23', 'r_landcover_bysoil_24',
28        'r_landcover_bysoil_25', 'r_landcover_bysoil_26', 
29        "r_maximum_depth_m", "r_mean_annual_windspeed",  'r_mean_depth_m',
30        'r_mean_temp_1', 'r_mean_temp_2', 'r_mean_temp_3', 
31        'r_mean_temp_4', 'r_mean_temp_5', 'r_mean_temp_6', 'r_mean_temp_7', 
32        'r_mean_temp_8', 'r_mean_temp_9', 'r_mean_temp_10', 'r_mean_temp_11', 
33        'r_mean_temp_12', "r_mghr_all_kwhperm2perday", 
34        "r_mghr_may_sept_kwhperm2perday", "r_mghr_nov_mar_kwhperm2perday",
35        "r_msocs_kgperm2", "r_volume_m3", "year_commissioned",
36        "c_landuse_intensity", "c_treatment_factor"]
37    # Alternative fields, e.g. fields containing outputs required for calculating
38    # gas emissions that are derived from alternative data sources
39    alternative_fields = [
40        "c_mad_m3_pers", "c_map_mm_alt1", "c_mar_mm_alt1", "c_mar_mm_alt2",
41        "c_masm_mm_alt1", "c_mmr_mm_alt2", "c_mpet_mm_alt1",
42        "r_mghr_all_kwhperm2perday_alt1", "r_mghr_may_sept_kwhperm2perday_alt1",
43        "r_mghr_nov_mar_kwhperm2perday_alt1"]
44    # Fields that are currently not used for derivation of RE-EMISSION inputs
45    # but may be used for ghg emission calculations with other models
46    unused_inputs = [
47        "c_msbdod_kgperdm3", "c_msnc_gperkg", "c_msocc_gperkg", "c_msocc_perc", 
48        "c_msocs_kgperm2", "c_mswc_molperkg", "c_mswn_molperkg", 
49        "r_maximum_depth_m_alt1", "r_maximum_depth_m_alt2",
50        "r_msbdod_kgperdm3", "r_msnc_gperkg", "r_msocc_gperkg", "r_msocc_perc"]
51[shp_concat]
52[shp_concat.catchments]
53    pattern = "C_*.shp"
54    filename = "catchments.shp"
55[shp_concat.flooded_rivers]
56    pattern = "MS_*.shp"
57    filename = "rivers.shp"
58[shp_concat.dams]
59    pattern = "PS_*.shp"
60    filename = "dams.shp"
61[shp_concat.reservoirs]
62    pattern = "R_*.shp"
63    filename = "reservoirs.shp"
64[shp_concat.catchments_minus_reservoirs]
65    pattern = "N_*.shp"
66    filename = "catchments_minus_reservoirs.shp"
67[shp_output]
68[shp_output.catchments]
69    # Mapping between index of the tabular data and index of the original shp
70    match_keys = ["id", "id"]
71    # Fields to be copied from the tabular data to the shape file
72    fields = ["c_mar_mm", "c_area_km2", "n_population", "c_mean_slope_pc",
73              "c_map_mm", "c_mpet_mm", "c_masm_mm", "c_biome", "c_soil_type",
74              "c_mean_olsen", "ms_length"]
75[shp_output.dams]
76    # Mapping between index of the tabular data and index of the original shp
77    match_keys = ["id", "id"]
78    # Fields to be copied from the tabular data to the shape file
79    fields = ["dam_height", "dam_lat", "dam_lon"]
80[shp_output.reservoirs]
81    # Mapping between index of the tabular data and index of the original shp
82    match_keys = ["id", "id"]
83    # Fields to be copied from the tabular data to the shape file
84    fields = ["type", "r_volume_m3","r_area_km2", "r_maximum_depth_m", "r_mean_depth_m",
85              "r_msocs_kgperm2", "r_mghr_all_kwhperm2perday",
86              "r_mghr_may_sept_kwhperm2perday",
87              "r_mghr_nov_mar_kwhperm2perday", "r_mean_annual_windspeed",
88              "c_mar_mm", "c_area_km2", "n_population", "c_mean_slope_pc",
89              "c_map_mm", "c_mpet_mm", "c_masm_mm", "c_biome", "c_soil_type",
90              "c_mean_olsen", "ms_length"]