Skip to content

Commit

Permalink
deploy: 9c0ae9e
Browse files Browse the repository at this point in the history
  • Loading branch information
codingfabi committed May 5, 2024
0 parents commit 0077435
Show file tree
Hide file tree
Showing 52 changed files with 7,122 additions and 0 deletions.
4 changes: 4 additions & 0 deletions .buildinfo
Original file line number Diff line number Diff line change
@@ -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
Binary file added .doctrees/api.doctree
Binary file not shown.
Binary file added .doctrees/calculate/distances.doctree
Binary file not shown.
Binary file added .doctrees/calculate/electricity.doctree
Binary file not shown.
Binary file added .doctrees/calculate/emission_factors.doctree
Binary file not shown.
Binary file added .doctrees/calculate/heating.doctree
Binary file not shown.
Binary file added .doctrees/calculate/transport_modes.doctree
Binary file not shown.
Binary file added .doctrees/documentation.doctree
Binary file not shown.
Binary file added .doctrees/environment.pickle
Binary file not shown.
Binary file added .doctrees/index.doctree
Binary file not shown.
Binary file added .doctrees/mobility.doctree
Binary file not shown.
Binary file added .doctrees/tutorial.doctree
Binary file not shown.
Empty file added .nojekyll
Empty file.
Binary file added _images/Workflow_figure_co2_calculator.drawio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 8 additions & 0 deletions _sources/api.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
API Docs
========

.. autosummary::
:toctree: generated
:recursive:

co2calculator
110 changes: 110 additions & 0 deletions _sources/calculate/distances.rst.txt
Original file line number Diff line number Diff line change
@@ -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"]
10 changes: 10 additions & 0 deletions _sources/calculate/electricity.rst.txt
Original file line number Diff line number Diff line change
@@ -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
13 changes: 13 additions & 0 deletions _sources/calculate/emission_factors.rst.txt
Original file line number Diff line number Diff line change
@@ -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
21 changes: 21 additions & 0 deletions _sources/calculate/heating.rst.txt
Original file line number Diff line number Diff line change
@@ -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.
43 changes: 43 additions & 0 deletions _sources/calculate/transport_modes.rst.txt
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 0077435

Please sign in to comment.