Merge branch 'main' into refactor/energy

README.md

@@ -10,25 +10,31 @@ This package is part of [Pledge4Future](https://pledge4future.org/), a project t
 
 ## :computer:  Installation
 
-`co2calculator` is currently only available on GitHub. To use the code, clone the repository as usual, for example with:
+### With pip (recommended)
 
-``` 
-git clone https://github.com/pledge4future/co2calculator.git
-```
+PyPi release coming soon!
 
-The repository has a submodule (https://github.com/trainline-eu/stations). This has to be pulled with the following command:
+<!--The recommended way to install this package is with pip from the Python Package Index ([PyPi](https://pypi.org/)):
 
 ```
-git submodule update --init --recursive
-```
+pip install -U co2calculator
+```-->
 
+### From source
 
-This package requires Python 3.9 and the packages listed in `requirements.txt`
+To install this package from source, clone the repository as usual, for example with:
 
-```
-$ pip install -r requirements.txt
+``` 
+git clone https://github.com/pledge4future/co2calculator.git
+cd co2calculator
 ```
 
+This package requires Python 3.10, 3.11 or 3.12 and can be installed using [poetry](https://python-poetry.org/). You can install it in your (virtual) environment with:
+
+```
+$ pip install -U poetry
+$ poetry install --no-root
+```
 
 
 ## ⌨  How to Use
@@ -48,11 +54,6 @@ The CO<sub>2</sub> Calculator uses the [OpenRouteService (ORS) API](https://open
 
 If you want to contribute to this project, please fork this repository and create a pull request with your suggested changes.
 
-Running the unit tests and applying the pre-commit hooks requires installing the packages listed in `requirements-dev.txt`.
-
-```
-$ pip install -r requirements-dev.txt
-```
 
 ### Install pre-commit hooks
 
@@ -77,14 +78,14 @@ $ pytest
 
 ### Emission factors
 
-- [Probas](https://www.probas.umweltbundesamt.de/php/index.php)
-- [UBA (2021). "Umweltfreundlich mobil"](https://www.umweltbundesamt.de/en/publikationen/umweltfreundlich-mobil)
-- [GOV.UK (2020). Greenhouse gas reporting: conversion factors 2020](https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2020)
+- [Carbon footprint (2023). International electricity factors](https://www.carbonfootprint.com/international_electricity_factors.html)
+- [GOV.UK (2023). Greenhouse gas reporting: conversion factors 2023](https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2023)
+- [mobitoool (2023). mobitool-Faktoren v3.0](https://www.mobitool.ch/de/tools/mobitool-faktoren-v2-1-25.html)
 
 ### Conversion factors
 
 - [BAFA (2020): Merkblatt zur Ermittlung des Gesamtenergieverbrauchs](https://www.bafa.de/SharedDocs/Downloads/DE/Energie/ea_ermittlung_gesamtenergieverbrauch.html)
-- [Krajnc, N. (2015): Wood fuels handbook, FAO](https://agris.fao.org/agris-search/search.do?recordID=XF2017001919)
+- [Krajnc, N. (2015): Wood fuels handbook, FAO](http://large.stanford.edu/courses/2017/ph240/timcheck1/docs/fao-krajnc-2015.pdf)
 
 ### Detour coefficients and constants
 
@@ -94,9 +95,10 @@ $ pytest
 - Detour coefficients for train trips (1.2) and bus trips (1.5):
     - Adapted from [GES 1point5](https://labos1point5.org/ges-1point5), who were advised by Frédéric Héran (economist and urban planner).
 
-### Airports
+### Airports and Train Stations
 
 - [OurAirports](https://ourairports.com/data/)
+- [Stations - A Database of European Train Stations (Trainline EU)](https://github.com/trainline-eu/stations)
 
 ## 🤝 Project partners
 

co2calculator/calculate.py

@@ -19,15 +19,19 @@
 
 from ._types import Kilogram, Kilometer
 from .constants import (
-    KWH_TO_TJ,
     Size,
     CarFuel,
     BusFuel,
     TrainFuel,
     TransportationMode,
+    CountryCode2,
 )
 from .data_handlers import EmissionFactors, ConversionFactors
 from .distances import create_distance_request, get_distance, range_categories
+from .parameters import (
+    ElectricityEmissionParameters,
+    HeatingEmissionParameters,
+)
 
 script_path = str(Path(__file__).parent)
 
@@ -68,7 +72,6 @@ def calc_co2_commuting(
     weekly_distance: Kilometer,
     size: Size = None,
     fuel_type: BusFuel | CarFuel | TrainFuel = None,
-    occupancy: int = None,
     passengers: int = None,
 ) -> Kilogram:
     """Calculate co2 emissions for commuting per mode of transport
@@ -77,13 +80,11 @@ def calc_co2_commuting(
     :param weekly_distance: distance in km per week
     :param size: size of car or bus if applicable: [small, medium, large, average]
     :param fuel_type: fuel type of car, bus or train if applicable
-    :param occupancy: occupancy [%], if applicable/known (only for bus): [20, 50, 80, 100]
     :param passengers: number of passengers, if applicable (only for car)
     :type transportation_mode: str
     :type weekly_distance: Kilometer
     :type size: str
     :type fuel_type: str
-    :type occupancy: int
     :type passengers: int
     :return: total weekly emissions for the respective mode of transport
     :rtype: Kilogram

co2calculator/constants.py

@@ -5,38 +5,26 @@
 import enum
 
 import iso3166
-import pandas as pd
-
-KWH_TO_TJ = 277777.77777778
-
-DF_AIRPORTS = pd.read_csv(
-    "https://davidmegginson.github.io/ourairports-data/airports.csv"
-)
+from co2calculator.data_handlers import Airports
 
 
 class HeatingFuel(enum.Enum):
     """Enum for heating fuel types"""
 
-    HEAT_PUMP_AIR = "heat_pump_air"
-    HEAT_PUMP_GROUND = "heat_pump_ground"
-    HEAT_PUMP_WATER = "heat_pump_water"
-    LIQUID_GAS = "liquid_gas"
     OIL = "oil"
-    PELLETS = "pellets"
-    SOLAR = "solar"
-    WOODCHIPS = "woodchips"
-    ELECTRICITY = "electricity"
-    GAS = "gas"
     COAL = "coal"
-    DISTRICT_HEATING = "district_heating"
+    GAS = "gas"
+    WOOD_PELLETS = "wood pellets"
+    WOOD_CHIPS = "wood chips"
+    LPG = "liquid gas"
 
 
 @enum.unique
 class ElectricityFuel(str, enum.Enum):
     """Enum for electricity fuel types"""
 
-    GERMAN_ENERGY_MIX = "german_energy_mix"
-    SOLAR = "solar"
+    PRODUCTION_FUEL_MIX = "production fuel mix"
+    RESIDUAL_FUEL_MIX = "residual fuel mix"
 
 
 @enum.unique
@@ -87,7 +75,6 @@ class FlightClass(str, enum.Enum):
     """Enum for flight classes"""
 
     ECONOMY = "economy_class"
-    PREMIUM_ECONOMY = "premium_economy_class"
     BUSINESS = "business_class"
     FIRST = "first_class"
     AVERAGE = "average"
@@ -106,9 +93,9 @@ class FerryClass(str, enum.Enum):
 class FlightRange(str, enum.Enum):
     """Enum for flight ranges"""
 
-    DOMESTIC = "domestic"
     SHORT_HAUL = "short-haul"
     LONG_HAUL = "long-haul"
+    AVERAGE = "average"
 
 
 @enum.unique
@@ -232,7 +219,7 @@ def __get_validators__(cls):
 
     @classmethod
     def validate_iata_code(cls, iata_code: str) -> str:
-        if iata_code in DF_AIRPORTS["iata_code"].values:
+        if iata_code in Airports().airports["iata_code"].values:
             return iata_code
         else:
             raise ValueError(f"{iata_code} was not found in airport database")

co2calculator/data/conversion_factors_heating.csv

@@ -1,7 +1,7 @@
 ,fuel_type,unit,conversion_value
 0,oil,l,10.6
-1,liquid_gas,kg,14.1
+1,liquid gas,kg,14.1
 2,coal,kg,6.0
-3,pellet,kg,5.4
-4,woodchips,kg,5.2
+3,wood pellets,kg,5.4
+4,wood chips,kg,5.2
 5,gas,m^3,10.8