deploy: 9c0ae9e

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: e034d179c20c6002bef13f6d2f368b30
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/api.rst.txt

@@ -0,0 +1,8 @@
+API Docs
+========
+
+.. autosummary::
+    :toctree: generated
+    :recursive:
+
+    co2calculator

_sources/calculate/distances.rst.txt

@@ -0,0 +1,110 @@
+=====================
+Distance calculations
+=====================
+
+Geocoding
+---------
+
+The first step in calculating the distance between two locations is to obtain the geographic coordinates of
+these locations, which is called *geocoding*. For this, we use the open-source geocoder `Pelias <https://pelias.io/>`_,
+as well as a database of train stations.
+
+a) Geocoding for air travel
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Most airports around the world can be identified by a unique code, assigned by the International Air Transport Association (`IATA <https://www.iata.org/>`_).
+To retrieve the location of airports, we use `Pelias <https://pelias.io/>`_ and search for the IATA code in combination with the keyword "Airport".
+
+.. autofunction:: co2calculator.distances.geocoding_airport
+
+In the ``calc_co2_businesstrip()`` function, the user only needs to provide the IATA codes for start and destination, e.g.::
+
+    emissions, distance, range_category, range_description = calc_co2_businesstrip(
+        transportation_mode: "plane",
+        start="FRA",
+        destination="SCQ",
+        seating = "economy_class",
+        roundtrip: bool = False)
+
+b) Geocoding for train trips
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To obtain the coordinates of train stations within Europe, we use the `train station database <https://github.com/trainline-eu/stations>`_
+by `Trainline <https://www.thetrainline.com/de?redirected=true>`_.
+
+.. autofunction:: co2calculator.distances.geocoding_train_stations
+
+As you can see above, a dictionary with the keys `country` and `station_name` has to be provided for both start and destination.
+Calculating a train trip may thus look like this::
+
+    start_dict = {
+                  "country": "DE",
+                  "station_name: "Heidelberg Hauptbahnhof"
+                  }
+    dest_dict = {
+                  "country": "DE",
+                  "station_name: "Hamburg Hauptbahnhof"
+                  }
+    emissions, distance, range_category, range_description = calc_co2_businesstrip(
+        transportation_mode: "train",
+        start=start_dict,
+        destination=dest_dict
+        roundtrip: bool = False)
+
+We use the fuzzy string matching package `thefuzz <https://github.com/seatgeek/thefuzz>`_ to find the train station in the database which best matches the
+user input.
+
+c) Geocoding for other trips
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For other trips (e.g., car or bus), we use `Pelias structured geocoding <https://github.com/pelias/documentation/blob/master/structured-geocoding.md>`_
+as included in `openrouteservice <https://openrouteservice.org/>`_.
+This means that the user has different predefined fields to specify an address.
+
+.. autofunction:: co2calculator.distances.geocoding_structured
+
+Good results can be achieved by specifying `country`, `locality` and `address`. Further specifications
+are usually not needed and can sometimes even negatively affect the geocoding results.
+
+Distance computation
+--------------------
+
+For the computation of distances between places of departure and destination, we use two different approaches,
+depending on the specified mode of transport:
+
+a) Distance as the crow flies + detour
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Calculating the distance as the crow flies (great circle distance) and multiplying by a detour coefficient or adding
+a detour constant.
+
+The distance as the crow flies is calculated using the haversine formula:
+
+.. autofunction:: co2calculator.distances.haversine
+
+The transport modes for which this approach is used are listed in the table below, together with their detour parameters.
+
+.. csv-table:: Detour parameters
+    :file: ../../data/detour.csv
+    :header-rows: 1
+    :stub-columns: 2
+    :widths: 10 30 30 30
+
+b) Road distance
+^^^^^^^^^^^^^^^^
+
+Calculating the road distance using `openrouteservice <https://openrouteservice.org/>`_.
+
+This approach is only used for the transport mode ``car``.
+
+Here is an example of how this works using the ``openrouteservice`` `Python library <https://pypi.org/project/openrouteservice/>`_).
+::
+
+    import openrouteservice
+    from openrouteservice.directions import directions
+
+    clnt = openrouteservice.Client(key=ors_api_key)
+
+    # coords: list/tuple of locations [lat,long]
+    route = directions(clnt, coords, profile="driving-car")
+    distance = route["routes"][0]["summary"]["distance"]

_sources/calculate/electricity.rst.txt

@@ -0,0 +1,10 @@
+===========
+Electricity
+===========
+
+.. contents::
+
+
+Electricity emissions are computed based on the consumption (in kWh) and the emission factors for a specified energy mix or energy source.
+
+.. autofunction:: co2calculator.calculate.calc_co2_electricity

_sources/calculate/emission_factors.rst.txt

@@ -0,0 +1,13 @@
+
+Emission factors
+================
+
+For computing emissions, a central piece of information is the emission intensity of the different activities.
+These are expressed by emission factors.
+Below, you can find a list of all activities and their emission factors (in co2e per unit).
+Within one category, the emission intensity may differ drastically depending on the specification
+
+.. csv-table:: Conversion factors heating
+    :file: ../../data/emission_factors.csv
+    :header-rows: 1
+    :stub-columns: 2

_sources/calculate/heating.rst.txt

@@ -0,0 +1,21 @@
+
+=======
+Heating
+=======
+
+Heating emissions are computed based on the consumption (typically in kWh) and the emission factors for a specified fuel type.
+
+.. autofunction:: co2calculator.calculate.calc_co2_heating
+
+Per default, the expected unit is kWh. For some fuel types, the consumption may also be specified using different units, e.g., litres of oil or kg of wood chips.
+In these cases, it is possible to specify the `unit`. The consumption will then be converted from the specified unit to kWh, based on common conversion factors:
+
+.. csv-table:: Conversion factors heating
+    :file: ../../data/conversion_factors_heating.csv
+    :header-rows: 1
+    :stub-columns: 2
+    :widths: 10 30 30 30
+
+The parameter `area_share` accounts for the fact, that the heating energy consumption may often only be known for an entire building, while a working group just occupies parts of the building.
+In this case, the (approximate) share of the building floor space, that is occupied by the working group can be provided.
+The `area_share` must be between 0.0 and 1.0 and is 1.0 by default.

_sources/calculate/transport_modes.rst.txt

@@ -0,0 +1,43 @@
+====================
+Transportation modes
+====================
+
+.. contents::
+
+Trips can be calculated for different modes of transport.
+The overview here summarizes, which parameters influence the carbon emission intensity of a trip for the different transportation modes.
+The specific emission factors for different configurations (e.g., vehicle size, fuel type, etc.) are documented under
+:doc:`Emission factors <emission_factors>`.
+
+Car trip
+--------
+The quantity of CO2e emitted by a car trip depends on the ``fuel_type`` (average, cng, diesel, electric, gasoline,
+hybrid, plug-in_hybrid), car ``size`` (average, small, medium, large) and the number of ``passengers``.
+
+Bus trip
+--------
+The quantity of CO2e emitted by a bus trip depends on the bus ``size`` (average, small, medium, large)and the ``vehicle_range`` (local, long-distance).
+
+Train trip
+----------
+The quantity of CO2e emitted by a train trip depends on the ``vehicle_range`` (local, long-distance).
+
+Plane trip
+----------
+The quantity of CO2e emitted by a plane trip depends on the
+``seating_class`` (average, economy_class, business_class, first_class).
+
+Ferry trip
+----------
+The quantity of CO2e emitted by a ferry trip depends on the
+``seating_class`` (average, Foot passenger, Car passenger).
+
+
+Motorbike trip
+--------------
+The quantity of CO2e emitted by a motorbike trip depends on the ``size`` (average, small, medium, large) of the
+motorbike.
+
+Tram, trolleybus, bicycle or pedelec trip
+-----------------------------------------
+For tram, trolleybus, bicylce or pedelec, no specifica have to be provided.