From a004ddddb13df7ab3c910d6fc1bb53fe4cfe4b5d Mon Sep 17 00:00:00 2001 From: han16nah Date: Sun, 5 May 2024 11:30:41 +0200 Subject: [PATCH] update and restructure docs --- docs/businesstrips.rst | 30 --------- docs/calculate/electricity.rst | 10 +++ docs/calculate/emission_factors.rst | 2 - .../{heating_electricity.rst => heating.rst} | 17 +---- docs/calculate/transport_modes.rst | 22 ++++--- docs/conf.py | 4 +- docs/documentation.md | 38 +++++++----- docs/index.rst | 8 +-- docs/{commuting.rst => mobility.rst} | 62 ++++++++++++------- 9 files changed, 94 insertions(+), 99 deletions(-) delete mode 100644 docs/businesstrips.rst create mode 100644 docs/calculate/electricity.rst rename docs/calculate/{heating_electricity.rst => heating.rst} (72%) rename docs/{commuting.rst => mobility.rst} (53%) diff --git a/docs/businesstrips.rst b/docs/businesstrips.rst deleted file mode 100644 index ed1edbf..0000000 --- a/docs/businesstrips.rst +++ /dev/null @@ -1,30 +0,0 @@ -============== -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 `. -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 ' :doc:`Emission factors `). - -.. autofunction:: co2calculator.calculate.calc_co2_businesstrip diff --git a/docs/calculate/electricity.rst b/docs/calculate/electricity.rst new file mode 100644 index 0000000..9322093 --- /dev/null +++ b/docs/calculate/electricity.rst @@ -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 diff --git a/docs/calculate/emission_factors.rst b/docs/calculate/emission_factors.rst index c2f7d3c..f4ae690 100644 --- a/docs/calculate/emission_factors.rst +++ b/docs/calculate/emission_factors.rst @@ -6,8 +6,6 @@ For computing emissions, a central piece of information is the emission intensit 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 diff --git a/docs/calculate/heating_electricity.rst b/docs/calculate/heating.rst similarity index 72% rename from docs/calculate/heating_electricity.rst rename to docs/calculate/heating.rst index 9d19cfc..e549d00 100644 --- a/docs/calculate/heating_electricity.rst +++ b/docs/calculate/heating.rst @@ -1,11 +1,7 @@ -======================= -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. @@ -20,13 +16,6 @@ In these cases, it is possible to specify the `unit`. The consumption will then :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. +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. - -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 diff --git a/docs/calculate/transport_modes.rst b/docs/calculate/transport_modes.rst index 2ef4c4e..8e7ea27 100644 --- a/docs/calculate/transport_modes.rst +++ b/docs/calculate/transport_modes.rst @@ -4,7 +4,7 @@ Transportation modes .. contents:: -Business trips can be calculated for different modes of transport. +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 `. @@ -12,24 +12,32 @@ The specific emission factors for different configurations (e.g., vehicle size, 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``. +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, medium, large) and the -``occupancy`` in % (20, 50, 80, 100). The ``vehicle_range`` is set to long-distance automatically. +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 ``fuel_type`` (average, electric, diesel). -The ``vehicle_range`` is set to long-distance automatically. +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, premium_economy_class, first_class). +``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. diff --git a/docs/conf.py b/docs/conf.py index 3f1f4ce..d86352d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -64,7 +64,7 @@ html_theme_options = { "body_max_width": "none", "page_width": "80%", - "sidebar_width": "350px", + "sidebar_width": "250px", "fixed_sidebar": "true", "github_button": "true", "github_user": "pledge4future", @@ -72,7 +72,7 @@ "show_powered_by": "true", "sidebar_header": "#f15e44", "narrow_sidebar_bg": "#f15e44", - "font_family": "montserrat", + "font_family": "Roboto Condensed", } # Add any paths that contain custom static files (such as style sheets) here, diff --git a/docs/documentation.md b/docs/documentation.md index 0953380..b887561 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -5,10 +5,14 @@ The *co2calculator* can compute emissions caused by mobility, heating and electr ## 1 General information ### What are CO2e emissions? -Anthropogenic climate change is caused by greenhouse gases, such as carbon dioxide ($CO_2$), methane ($CH_4$), nitrous oxides ($N_2O$) and others. The molecules of these gases contribute differently to global warming. For example, the impact of one methane molecule is 21 times higher than the impact caused by one carbon dioxide molecule [(Moss et al. 2000)](https://animres.edpsciences.org/articles/animres/abs/2000/03/z0305/z0305.html). This is why the impact of different greenhouse gases is usually converted to the equivalent impact that carbon dioxide molecules would have, resulting in $CO_2$ equivalents as a standard unit [(Gohar & Shine 2007)](https://rmets.onlinelibrary.wiley.com/doi/10.1002/wea.103). The basic formula for a consumption value $c$ and an emission factor $\epsilon$ is: +Anthropogenic climate change is caused by greenhouse gases, such as carbon dioxide (CO2), methane (CH4), nitrous oxides (N2O) and others. The molecules of these gases contribute differently to global warming. For example, the impact of one methane molecule is 21 times higher than the impact caused by one carbon dioxide molecule ([Moss et al. 2000](https://animres.edpsciences.org/articles/animres/abs/2000/03/z0305/z0305.html)). This is why the impact of different greenhouse gases is usually converted to the equivalent impact that carbon dioxide molecules would have, resulting in CO2e equivalents as a standard unit ([Gohar & Shine 2007](https://rmets.onlinelibrary.wiley.com/doi/10.1002/wea.103)). The basic formula for a consumption value {math}`c` and an emission factor {math}`\epsilon` is: -$$ y_{co_2} = \epsilon \cdot c $$ +### Sources + +```{math} +y_{co_2} = \epsilon \cdot c +``` CO2e emissions are quantified in kilograms. The unit of consumption values depend on the specific activity. For heating and electricity, the input value is the consumption in kilowatt-hours (kWh), and for mobility, it is the distance travelled in kilometers (km). @@ -22,21 +26,19 @@ The CO2e emissions are calculated using emission factors from differe The specific emission factors for different activities are collected in [this emission factor table](https://github.com/pledge4future/co2calculator/blob/main/data/emission_factors.csv). Several data sources for emission factors are available with differences in their level of detail (e.g. occupancy rates of vehicles, car sizes...), geographic resolution (e.g. national, sub-national...) and up-to-dateness with resulting implications for their within- and across-country comparability. -With the selected sources, we aim at providing reliable and user-friendly emission calculations that are comparable across countries, most recent and that come along with acceptable user efforts. When comparisons within countries or more detailed heating emission calculations are required, we suggest to rely on national sources and to provide custom emission factors as district heating can vary significantly across district heating networks within a country. Similarly, while emission factors for most public and private transport are globally comparable, those for electrically powered trams or trains vary significantly across countries. For possible more detailed emission factors, see [Geographical coverage](#heading-target). - +With the selected sources, we aim at providing reliable and user-friendly emission calculations that are comparable across countries, most recent and that come along with acceptable user efforts. When comparisons within countries or more detailed heating emission calculations are required, we suggest to rely on national sources and to provide custom emission factors as district heating can vary significantly across district heating networks within a country. Similarly, while emission factors for most public and private transport are globally comparable, those for electrically powered trams or trains vary significantly across countries. For possible more detailed emission factors, see [Geographical coverage](#geographical-coverage). -(heading-target)= +(compliance-with-the-ghg-protocols)= ### Compliance with the GHG Protocols -The Greenhouse Gas (GHG) Protocol Corporate Standards provide a globally used framework to measure greenhouse gas emissions [(Greenhouse Gas Protocol 2024)](https://ghgprotocol.org/). They account for three scopes: +The Greenhouse Gas (GHG) Protocol Corporate Standards provide a globally used framework to measure greenhouse gas emissions ([Greenhouse Gas Protocol 2024](https://ghgprotocol.org/)). They account for three scopes: * Scope 1 emissions are direct emissions from sources that are owned or controlled by the reporting entity, such as emissions from combustion in owned vehicles or boilers. * Scope 2 emissions are indirect emissions caused by the generation of purchased or consumed electricity, heating, cooling or steam. * Scope 3 emissions are indirect emissions other than those captured in scope 3. These include all other emissions generated in the life cycle of the product, including production and disposal. For electricity and mobility, the *co2calculator* computes emissions based on the whole life cycle of a product, i.e. including scope 3 emissions. For heating, scope 1 emissions are caculated. - -(heading-target)= +(geographical-coverage)= ### Geographical coverage The *co2calculator* can compute heating and mobility CO2e emissions for the whole globe. For electricity, emissions of production mixes can be calculated for the whole globe and residual mixes for most European countries. @@ -47,7 +49,7 @@ Country-specific emission factors for Switzerland, Austria, Germany, France and ## 1 Electricity -Electricity CO2e emissions can either be calculated from country-specific production mixes or, when available, residual mixes ([Carbon Footprint 2023](https://www.carbonfootprint.com/international_electricity_factors.html)). Production mixes are the mix of fuels used by local power stations and, therefore, the basis for location-based reporting. Residual mixes are electricity mixes after removing energy from specific (e.g. green or renewable) tariffs. These values can thus be used for emission accounting when the user has not bought energy from a specific mix of fuels. Emission factors rely on total or, respectively, residual production fuel mixes, which include scope 2 and scope 3 emissions of the GHG protocol (for details, see [Compliance with the GHG Protocols](#heading-target)). +Electricity CO2e emissions can either be calculated from country-specific production mixes or, when available, residual mixes ([Carbon Footprint 2023](https://www.carbonfootprint.com/international_electricity_factors.html)). Production mixes are the mix of fuels used by local power stations and, therefore, the basis for location-based reporting. Residual mixes are electricity mixes after removing energy from specific (e.g. green or renewable) tariffs. These values can thus be used for emission accounting when the user has not bought energy from a specific mix of fuels. Emission factors rely on total or, respectively, residual production fuel mixes, which include scope 2 and scope 3 emissions of the GHG protocol (for details, see [Compliance with the GHG Protocols](#compliance-with-the-ghg-protocols)). Alternatively, users can provide specific emission factors, for example, when they use green or renewable tariffs. Consumption must be provided in kilowatt-hours (kWh). The returned CO2e emissions are quantified in kilograms. @@ -60,8 +62,8 @@ If the electricity consumption is only known for a building or building complex ## 2 Heating -Heating CO2e emissions depend on the type of burned fuel. Fuel types may be, for example, oil, gas, coal or biogas. The emissions are calculated using emission factors from [(GOV.UK 2023)](https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2023). -The provided emission factors reflect scope 1 emissions of the GHG protocol (for details, see [Compliance with the GHG Protocols](#heading-target)). +Heating CO2e emissions depend on the type of burned fuel. Fuel types may be, for example, oil, gas, coal or biogas. The emissions are calculated using emission factors from ([GOV.UK 2023](https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2023)). +The provided emission factors reflect scope 1 emissions of the GHG protocol (for details, see [Compliance with the GHG Protocols](#compliance-with-the-ghg-protocols)). As we only have values at country level, we note that district heating varies considerably between district heating networks within countries. Consumption must be provided in kilowatt-hours (kWh). The returned CO2e emissions are quantified in kilograms. @@ -73,16 +75,16 @@ If the heating consumption is only known for a building or building complex and ## 3 Mobility -CO2e emissions from the mobility sector are calculated using emission factors from [(mobitoool 2023)](https://www.mobitool.ch/de/tools/mobitool-faktoren-v2-1-25.html). The emissions include scope 3 emissions of the GHG protocol (for details, see [Compliance with the GHG Protocols](#heading-target)). For public transport, the emission factors assume certain occupancies. For private transport, an occupancy of one person is assumed. Further details can be found in [(Sacchi & Bauer 2023)](https://doi.org/10.5281/zenodo.5156043). +CO2e emissions from the mobility sector are calculated using emission factors from ([mobitoool 2023](https://www.mobitool.ch/de/tools/mobitool-faktoren-v2-1-25.html)). The emissions include scope 3 emissions of the GHG protocol (for details, see [Compliance with the GHG Protocols](#compliance-with-the-ghg-protocols)). For public transport, the emission factors assume certain occupancies. For private transport, an occupancy of one person is assumed. Further details can be found in ([Sacchi & Bauer 2023)](https://doi.org/10.5281/zenodo.5156043)). -Mobility emissions depend on the mode of transport, such as car or bicycle, and the distance travelled in kilometers (km). This distance may either be directly provided, or it may be computed from given start and stop locations using [distances.py](https://github.com/pledge4future/co2calculator/blob/main/co2calculator/distances.py). In the latter case, the coordinates of the locations are retrieved using geocoding before the travel distance between the locations is computed (for details, see [Geocoding](#heading-target)). +Mobility emissions depend on the mode of transport, such as car or bicycle, and the distance travelled in kilometers (km). This distance may either be directly provided, or it may be computed from given start and stop locations using [distances.py](https://github.com/pledge4future/co2calculator/blob/main/co2calculator/distances.py). In the latter case, the coordinates of the locations are retrieved using geocoding before the travel distance between the locations is computed (for details, see [Geocoding](#geocoding)). -(heading-target)= +(geocoding)= ### Geocoding Geocoding is done using the [openrouteservice](https://openrouteservice.org/dev/#/api-docs) geocoding service, which is built on top of [Pelias](https://github.com/pelias/pelias), a modular open-source search engine for the world. -To find airports, we use [ourairports-data](https://davidmegginson.github.io/ourairports-data/) to search by **IATA-code**. To find train stations inside the EU geocoding_train_stations, we use the train station database of [Trainline EU](https://github.com/trainline-eu/stations). For train trips outside of the EU and other modes of transport, we use [structured geocoding](https://github.com/pelias/documentation/blob/master/structured-geocoding.md). The structured geocoding parameters are: +To find airports, we use [ourairports-data](https://davidmegginson.github.io/ourairports-data/) to search by **IATA-code**. To find train stations inside the EU, we use the train station database of [Trainline EU](https://github.com/trainline-eu/stations). For train trips outside of the EU and other modes of transport, we use [structured geocoding](https://github.com/pelias/documentation/blob/master/structured-geocoding.md). The structured geocoding parameters are: - **country**: highest-level administrative division supported in a search. Full country name or two-/three-letter abbreviations supported - e.g., Germany / "DE" / "DEU" - **region**: first-level administrative divisions within countries, analogous to states and provinces in the US and Canada @@ -103,7 +105,7 @@ To find airports, we use [ourairports-data](https://davidmegginson.github.io/our For cars and motorbikes, distances are computed with [openrouteservice](https://openrouteservice.org/dev/#/api-docs/directions) with the `profile='driving-car'`. -For other modes of transport (airplane, ferry, train, bus), the distances between the locations as the crow flies are computed with the haversine formula. Then, different [detour coefficients or constants](#Detour) are applied. +For other modes of transport (airplane, ferry, train, bus), the distances between the locations as the crow flies are computed with the haversine formula. Then, different [detour coefficients or constants](#detour) are applied. With the `roundtrip`-parameter (type: boolean), users can define if their trip is a roundtrip and if so, the distance will be doubled. #### Detour @@ -124,7 +126,9 @@ Ferry | x 1.0 | Currently no source According to the IPCC (2021), ->"[the] term ‘carbon budget’ refers to the maximum amount of cumulative net global anthropogenic $CO_2$ emissions that would result in limiting global warming to a given level with a given probability, taking into account the effect of other anthropogenic climate forcers. This is referred to as the total carbon budget when expressed starting from the pre-industrial period, and as the remaining carbon budget when expressed from a recent specified date [...]. The remaining carbon budget indicates how much CO2 could still be emitted while keeping warming below a specific temperature level" ([IPCC 2021, p. 28](https://www.ipcc.ch/report/ar6/wg1/downloads/report/IPCC_AR6_WGI_SPM.pdf)). +>"[the] term ‘carbon budget’ refers to the maximum amount of cumulative net global anthropogenic $CO_2$ emissions that would result in limiting global warming to a given level with a given probability, taking into account the effect of other anthropogenic climate forcers. This is referred to as the total carbon budget when expressed starting from the pre-industrial period, and as the remaining carbon budget when expressed from a recent specified date [...]. The remaining carbon budget indicates how much CO2 could still be emitted while keeping warming below a specific temperature level". + +([IPCC 2021, p. 28](https://www.ipcc.ch/report/ar6/wg1/downloads/report/IPCC_AR6_WGI_SPM.pdf)) ### Calculation of the remaining carbon budget diff --git a/docs/index.rst b/docs/index.rst index 5abad77..9a4043f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,12 +19,10 @@ Contents documentation tutorial - businesstrips - commuting - calculate/heating_electricity + mobility + calculate/heating + calculate/electricity calculate/emission_factors - calculate/transport_modes - Indices and tables ================== diff --git a/docs/commuting.rst b/docs/mobility.rst similarity index 53% rename from docs/commuting.rst rename to docs/mobility.rst index d42482b..a90d7d1 100644 --- a/docs/commuting.rst +++ b/docs/mobility.rst @@ -1,8 +1,41 @@ -========= -Commuting -========= +======== +Mobility +======== + +.. toctree:: + :maxdepth: 2 + :caption: See also: + :titlesonly: + :includehidden: + + calculate/distances + calculate/transport_modes + +============== +Business Trips +============== + +The calculation of emissions from business trips is currently supported for the following modes of transport: + +* car +* bus +* train +* plane +* ferry -.. contents:: +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 `. +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 ' :doc:`Emission factors `). + +.. autofunction:: co2calculator.calculate.calc_co2_businesstrip + +============== +Commuting +============== The calculation of emissions from commuting is currently supported for the following modes of transport: @@ -37,28 +70,13 @@ hybrid, hydrogen, plug-in_hybrid), car ``size`` (average, small, medium, large) 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. +The quantity of CO2e emitted by a bus commute depends on the ``fuel_type`` (cng, diesel) and bus ``size`` (average, small, medium, large). 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 +Train, 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 +For train, tram, bicylce or pedelec, no specifica have to be provided.