deploy: bb5d955

.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: cd44277946ced39c9c532366abb48ddc
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/businesstrips.rst.txt

@@ -0,0 +1,30 @@
+==============
+Business trips
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: See also:
+   :titlesonly:
+   :includehidden:
+
+   calculate/distances
+   calculate/transport_modes
+
+The calculation of emissions from business trips is currently supported for the following modes of transport:
+
+* car
+* bus
+* train
+* plane
+* ferry
+
+The user must specify either the distance of a trip or the location of departure and destination.
+The distance (in km) may be used, when the user has the direct information of the distance travelled, e.g., from the speedometer of a car.
+In other cases, the distance can be calculated from the given locations, see :ref:`Distance calculations <Distance calculations>`.
+With the boolean paramter ``roundtrip``, users can indicate whether a trip was a roundtrip, in which case the distance wil be doubled.
+
+Aside of the mode of transport, the user should provide the specifica of the trip, depending on the mode of transport
+(see :doc'Transportation modes <calculate/transport_modes>' :doc:`Emission factors <calculate/emission_factors>`).
+
+.. autofunction:: co2calculator.calculate.calc_co2_businesstrip

_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/emission_factors.rst.txt

@@ -0,0 +1,15 @@
+
+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
+Let's take a trip by car. A medium battery electric car emits around 0.056 kg co2e/km (including emissions from
+manufacturing), while an average car driving on gasoline emits 0.224 kg co2e/km.
+
+.. csv-table:: Conversion factors heating
+    :file: ../../data/emission_factors.csv
+    :header-rows: 1
+    :stub-columns: 2

_sources/calculate/heating_electricity.rst.txt

@@ -0,0 +1,32 @@
+=======================
+Heating and electricity
+=======================
+
+.. contents::
+
+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 buildin.
+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.
+
+Electricity
+-----------
+
+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/transport_modes.rst.txt

@@ -0,0 +1,35 @@
+====================
+Transportation modes
+====================
+
+.. contents::
+
+Business 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, hydrogen, 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, medium, large) and the
+``occupancy`` in % (20, 50, 80, 100). The ``vehicle_range`` is set to long-distance automatically.
+
+Train trip
+----------
+The quantity of CO2e emitted by a train trip depends on the ``fuel_type`` (average, electric, diesel).
+The ``vehicle_range`` is set to long-distance automatically.
+
+Plane trip
+----------
+The quantity of CO2e emitted by a plane trip depends on the
+``seating_class`` (average, economy_class, business_class, premium_economy_class, first_class).
+
+Ferry trip
+----------
+The quantity of CO2e emitted by a ferry trip depends on the
+``seating_class`` (average, Foot passenger, Car passenger).

_sources/commuting.rst.txt

@@ -0,0 +1,64 @@
+=========
+Commuting
+=========
+
+.. contents::
+
+The calculation of emissions from commuting is currently supported for the following modes of transport:
+
+* car
+* bus
+* train
+* motorbike
+* tram
+* bicycle
+* pedelec
+
+Their specific emission factors for different configurations (e.g., vehicle size, fuel type, etc.) are documented under
+:doc:`Emission factors <calculate/emission_factors>`.
+
+For each mode of transport used for the commute, the user must provide the average ``weekly_distance`` (in km) travelled during
+a given time period. The users are asked to enter their usual commuting behaviour and should estimate the distance as
+accurately as possible. If they often use a different mode of transport if there is bad weather or in the cold season,
+they should account for this by estimating the mean distance for each transportation mode over the entire year. The
+commuting data may also be entered separately for each month or once for the summer months and for the winter months
+(e.g., April-October and November-March).
+
+Aside of the mode of transport and the weekly distance, the user should provide the specifica of the commute, depending on
+the mode of transport (see :doc:`Emission factors <calculate/emission_factors>`).
+
+.. autofunction:: co2calculator.calculate.calc_co2_commuting
+
+
+Car commute
+-----------
+The quantity of CO2e emitted by a car commute depends on the ``fuel_type`` (average, cng, diesel, electric, gasoline,
+hybrid, hydrogen, plug-in_hybrid), car ``size`` (average, small, medium, large) and the number of ``passengers``.
+
+Bus commute
+-----------
+The quantity of CO2e emitted by a bus commute depends on the bus ``size`` (average, medium, large) and the
+``occupancy`` in % (20, 50, 80, 100). The ``vehicle_range`` is set to local automatically.
+
+Train commute
+-------------
+The quantity of CO2e emitted by a train commute depends on the ``fuel_type`` (average, electric, diesel).
+The ``vehicle_range`` is set to local automatically.
+
+Motorbike commute
+-----------------
+The quantity of CO2e emitted by a motorbike commute depends on the ``size`` (average, small, medium, large) of the
+motorbike.
+
+Tram, bicycle or pedelec commute
+--------------------------------
+For tram, bicylce or pedelec, no specifica have to be provided.
+
+
+Aggregating emissions to the group level
+----------------------------------------
+If it can be assumed that a representative sample (``n_participants``) of the entire group (``n_members``) have entered
+their commuting data, an estimate of the commuting emissions for the entire group can be obtained using the following
+function:
+
+.. autofunction:: co2calculator.calculate.commuting_emissions_group