Table of Contents

1. About The Library
   • Features
2. Prerequisites
   • LaTeX installation guidelines
   • Debian-based Linux Distributions
   • Mac OS
   • Windows
3. Installation
• From PyPi
• From GitHub
4. Usage
• As a Toolbox
• Jupyter Notebook Examples
• Using Command Line Interface (CLI)
5. Example inputs
• Input JSON file
6. Example outputs
• Outputs in JSON format
• Outputs in a PDF report format
7. Configuration
• Configuration of inputs
• Configuration of outputs
• Configuration of global parameters
• Model coefficients
8. Documentation
9. Contributing
10. License
11. Citing
12. Contact
13. Acknowledgments
• Institutions
• Resources
14. References
15. Contributors

About The Library

Re-Emission is a Python library and a command line interface (CLI) tool for estimating CO₂, CH₄ and N₂O emissions from man-made reservoirs. It calculates full life-cycle emissions as well as emission profiles over time for each of the three greenhouse gases.

🔥 Features

• Calculates CO₂, CH₄ and N₂O emissions for a single reservoir and for batches of reservoirs.
• Two reservoir Phosphorus mass balance calculation methods in CO₂ emission calculations: G-Res method and McDowell method.
• Two N₂O calculation methods.
• Model parameters, and presentation of outputs are fully configurable using YAML files.
• Inputs can be constructed in Python using the Input class or read from JSON files.
• Outputs can be presented in JSON, LaTeX and PDF format and are configurable in the outputs.yaml configuration file.

(back to top)

Prerequisites

If you would like to generate output documents in a PDF format, you will need to install LaTeX. Without LaTeX, upon an attempt to compile the generated LaTeX source code to PDF, pylatex library implemented in this software will throw pylatex.errors.CompilerError. LaTeX source file with output results will still be created but it will not be able to get compiled to PostScript or PDF.

LaTeX installation guidelines

Debian-based Linux Distributions

For basic LaTex version (recommended)

sudo apt install texlive

For full LaTeX version with all packages (requires around 2GB to download and 5GB free space on a local hard drive)

sudo apt install texlive-full

Mac OS

BasicTeX (100MB) - minimum install without editor

brew install --cask basictex

MacTeX with built-in editor (3.2GB) - uses TeXLive

brew install --cask mactex

Windows

For easy install, download and run install-tl-windows.exe For more installation options, visit https://tug.org/texlive/windows.html. Or, make your life easier by getting yourself a Linux. 😏

(back to top)

Installation

From PyPi

Use the package manager pip to install reemission.

pip install re-mission

Type

pip install reemission -r requirements.txt -e .

if you'd like to use the package in a development mode.

From GitHub

1. Clone the repository using either:
   • HTTPS

   git clone https://github.com/tomjanus/reemission.git

   • SSH

   git clone [email protected]:tomjanus/reemission.git

2. Install from source:

   • for development

     pip install -r requirements.txt -e .

   • or as a build

     pip install build .

     or

     python3 -m build --sdist --wheel .

(back to top)

Usage

As a toolbox

For calculation of emissions for a number of reservoirs with input data in inputs.json file and output configuration in outputs.yaml file.

import reemission
# Import from the model module
from reemission.model import EmissionModel
# Import from the input module
from reemission.input import Inputs
input_data = Inputs.fromfile('reemission/tests/test_data/inputs.json')
output_config = 'reemission/config/emissions/outputs.yaml'
model = EmissionModel(inputs=input_data, config=output_config)
model.calculate()
print(mode.outputs)

Jupyter Notebook Examples

Using Command Line Interface (CLI)

In Terminal/Console

reemission [input-file] [output-file]

For more examples, please refer to the Documentation

Example inputs

Input JSON file

{
    "Reservoir 1":
    {
        "monthly_temps": [10.56,11.99,15.46,18.29,20.79,22.09,22.46,22.66,
                          21.93,19.33,15.03,11.66],
        "year_vector": [1, 5, 10, 20, 30, 40, 50, 65, 80, 100],
        "gasses": ["co2", "ch4", "n2o"],
        "catchment":
        {
            "runoff": 1685.5619,
            "area": 78203.0,
            "population": 8463,
            "area_fractions": [0.0, 0.0, 0.0, 0.0, 0.0, 0.01092, 0.11996,
                               0.867257],
            "slope": 8.0,
            "precip": 2000.0,
            "etransp": 400.0,
            "soil_wetness": 140.0,
            "biogenic_factors":
            {
                "biome": "TROPICALMOISTBROADLEAF",
                "climate": "TROPICAL",
                "soil_type": "MINERAL",
                "treatment_factor": "NONE",
                "landuse_intensity": "LOW"
            }
        },
        "reservoir":{
            "volume": 7663812,
            "area": 0.56470,
            "max_depth": 32.0,
            "mean_depth": 13.6,
            "area_fractions": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
            "soil_carbon": 10.228
        }
    }
}

(back to top)

Example outputs

Outputs in JSON format

{
    "Reservoir 1": {
        "co2_diffusion": 243.65,
        "co2_diffusion_nonanthro": 167.25,
        "co2_preimp": -140.0,
        "co2_minus_nonanthro": 76.40,
        "co2_net": 216.40,
        "co2_profile": [
            737.05,
            422.16,
            330.28,
            257.19,
            221.57,
            199.04,
            182.98,
            165.54,
            152.78,
            140.00
        ],
        "ch4_diffusion": 95.09,
        "ch4_ebullition": 83.52,
        "ch4_degassing": 361.83,
        "ch4_preimp": 0.00,
        "ch4_net": 540.44,
        "ch4_profile": [
            1585.01,
            1399.71,
            1199.89,
            886.67,
            661.33,
            499.21,
            382.58,
            266.01,
            194.88,
            141.16
        ],
        "n2o_methodA": 1.198,
        "n2o_methodB": 1.332,
        "n2o_mean": 1.265,
        "n2o_profile": [
            1.20,
            1.20,
            1.20,
            1.20,
            1.20,
            1.20,
            1.20,
            1.20,
            1.20,
            1.20
        ]
    }
}

(back to top)

Outputs in a PDF report format

1. Input data in a tabular format in the output report in PDF format

2. Output data in a tabular format in the output report in PDF format

2. Output plots in the output report in PDF format

(back to top)

Configuration

Coefficients of the regressions constituting the model as well as parameters of different categories of soil and land use are stored in a number of yaml files in parameters/emissions/.

(back to top)

Configuration of inputs

Information about the names and the units of the model inputs is stored and can be configured in config/emissions/inputs.yaml e.g. for monthly temperatures which are represented in variable monthly_temps:

monthly_temps:
  include: True
  name: "Monthly Temperatures"
  long_description: ""
  unit: "deg C"
  unit_latex: "$^o$C"

• include: (boolean): If the variable is to be included in the output files for reporting.
• name: (string): Name of the variable
• long_description: (string): Description of the variable
• unit: (string): Unit in text format
• unit_latex: (string): Unit in LaTeX format

Finally, a global flag print_long_descriptions controls whether long descriptions are included alongside the included input variables in the output files.

(back to top)

Configuration of outputs

Similarly to inputs, definitions and units of model outputs and whether they are to be output in the output files, are stored in config/emissions/outputs.yaml, e.g. for pre-impoundment CO₂ emissions defined in variable co2_preimp:

co2_preimp:
  include: True
  name: "Preimpoundment CO2 emissions"
  gas_name: "CO2"
  name_latex: "Preimpoundment CO$_2$ emissions"
  unit: "gCO2eq m-2 yr-1"
  unit_latex: "gCO$_2$ m$^{-2}$ yr$^{-1}$"
  long_description: "CO2 emission in the area covered by the reservoir prior to impoundment"
  hint: "Negative values denote C sink (atmosphere to land flux)"

• include: (boolean): If the variable is to be included in the output files for reporting.
• name: (string): Name of the variable
• gas_name: (string): Name of the gas the variable is related to
• name_latex: (string): variable name 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): Further information about the variable

(back to top)

Configuration of global parameters

Information about global parameters such as e.g. Global Warming Potentials gwp100 is stored in config/emissions/parameters.yaml

gwp100:
  include: True
  name: "Global Warming Potential for a 100-year timescale"
  name_latex: "Global Warming Potential for a 100-year timescale"
  unit: "-"
  unit_latex: "-"
  long_description: ""

Model coefficients

Values of model coefficients, i.e. regressions used to estimate different gas emissions are stored in config/emissions/config.ini file. E.g. coefficients for CO₂ emission calculations are listed below.

[CARBON_DIOXIDE]
# Parameters reated to CO2 emissions
c_1 = 1.8569682
age = -0.329955
temp = 0.0332459
resArea = 0.0799146
soilC = 0.015512
ResTP = 0.2263344
calc = -0.32996
# Conversion from mg~CO2-C~m-2~d-1 to g~CO2eq~m-2~yr-1
# Based on stoichiometric relationship CO2/C = 44/12 and GWP100 of 1.0
conv_coeff = 1.33833
# Global Warming Potential of CO2 over 100 years
co2_gwp100 = 1.0

In addition, various coefficient tables and parameters required to calculate various emission components are stored in multiple YAML files in parameters/emissions/.

📚 Documentation

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repository and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

MIT

(back to top)

Citing

If you use RE-Emission for academic research, please cite the library using the following BibTeX entry.

@misc{reemission2022,
 author = {Tomasz Janus, Christopher Barry, Jaise Kuriakose},
 title = {RE-Emission: Python tool for calculating greenhouse gas emissions from man-made reservoirs},
 year = {2022},
 url = {https://github.com/tomjanus/reemission},
}

(back to top)

📬 Contact

• Tomasz Janus [email protected]
• Christopher Barry - [email protected]
• Jaise Kuriakose - [email protected]

Project Link: https://github.com/tomjanus/reemission

(back to top)

Acknowledgments

Institutions

Development of this software was funded, to a large degree, by the University of Manchester and the FutureDams project.

(back to top)

Resources

• Best README Template
• Choose an Open Source License
• Img Shields
• GitHub Pages
• Cookiecutter template for a Python library
• Cookiecutter template for a Python package

(back to top)

References

[1] Marco Aurelio dos Santos, Luiz Pinguelli Rosa, Bohdan Sikar, Elizabeth Sikar, Ednaldo Oliveira dos Santos. (2006). Gross greenhouse gas fluxes from hydro-power reservoir compared to thermo-power plants. Energy Policy, Volume 34, Issue 4, pp. 481-488, ISSN 0301-421. https://doi.org/10.1016/j.enpol.2004.06.015

[2] Beaulieu, J. J., Tank, J. L., Hamilton, S. K., Wollheim, W. M., Hall, R. O., Mulholland, P. J., Dahm, C. N. (2011). Nitrous oxide emission from denitrification in stream and river networks. Proceedings of the National Academy of Sciences of the United States of America, 108(1), 214–219. https://doi.org/10.1073/pnas.1011464108

[3] Scherer, Laura and Pfister, Stephan (2016) Hydropower's Biogenic Carbon Footprint. PLOS ONE, Volume 9, 1-11, https://doi.org/10.1371/journal.pone.0161947.

[4] Yves T. Prairie, Sara Mercier-Blais, John A. Harrison, Cynthia Soued, Paul del Giorgio, Atle Harby, Jukka Alm, Vincent Chanudet, Roy Nahas (2021) A new modelling framework to assess biogenic GHG emissions from reservoirs: The G-res tool. Environmental Modelling & Software, Volume 143, 105-117, ISSN 1364-8152, https://doi.org/10.1016/j.envsoft.2021.105117.

[5] Prairie YT, Alm J, Harby A, Mercier-Blais S, Nahas R. 2017. The GHG Reservoir Tool (G-res) Technical documentation. Updated version 3.0 (2021-10-27). UNESCO/IHA research project on the GHG status of freshwater reservoirs. Joint publication of the UNESCO Chair in Global Environmental Change and the International Hydropower Association. 73 pages.

(back to top)

Contributors ✨

Tomasz Janus 💻⚠️ 🐛🎨📖

Aung Kyaw Kyaw 💻⚠️

Chris Barry 🖋🤔📖

Jaise Kurkakose 🖋🤔📖

This project follows the all-contributors specification. Contributions of any kind welcome!

(back to top)