Add documentation of the spatial disaggregation of the CTS demand

docs/data.rst

@@ -41,6 +41,8 @@ Electricity
 
 .. include:: data/electricity_demand.rst
 
+.. _heat-demand-ref:
+
 Heat
 ----
 

docs/data/electricity_demand.rst

@@ -1 +1,70 @@
 Information about electricity demands and their spatial and temporal aggregation 
+
+.. _disagg-cts-elec-ref:
+
+Spatial disaggregation of CTS demand to buildings
++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The spatial disaggregation of the annual CTS demand to buildings is conducted in the dataset
+:py:class:`CtsDemandBuildings <egon.data.datasets.electricity_demand_timeseries.cts_buildings.CtsDemandBuildings>`.
+Both the electricity demand as well as the heat demand is disaggregated
+in the dataset. Here, only the disaggregation of the electricity demand is described.
+The disaggregation of the heat demand is analogous to it. More information on the resulting
+tables is given in section :ref:`heat-demand-ref`.
+
+The workflow generally consists of three steps. First, the annual demand from
+Peta5 [Peta]_ is used to identify census cells with demand.
+Second, Openstreetmap [OSM]_ data on buildings and amenities is used to map the demand to single buildings.
+If no sufficient OSM data are available, new synthetic buildings and if necessary
+synthetic amenities are generated.
+Third, each building's share of the HV-MV substation demand profile is determined
+based on the number of amenities within the building and the census cell(s) it is in.
+
+The workflow is in more detail shown in figure
+:ref:`disaggregation-cts-model` and described in the following.
+
+.. figure:: /images/flowchart_cts_disaggregation.jpg
+  :name: disaggregation-cts-model
+  :width: 800
+
+  Workflow for the disaggregation of the annual CTS demand to buildings
+
+In the :py:class:`OpenStreetMap <egon.data.datasets.osm.OpenStreetMap>` dataset, we filtered all
+OSM buildings and amenities for tags we relate to the CTS sector. Amenities are mapped
+to intersecting buildings and then intersected with the annual demand at census cell level. We obtain
+census cells with demand that have amenities within and census cells with demand that
+don't have amenities within.
+If there is no data on amenities, synthetic ones are assigned to existing buildings. We use
+the median value of amenities per census cell in the respective MV grid district
+to determine the number of synthetic amenities.
+If no building data is available, a synthetic building with a dimension of 5x5 m is randomly generated.
+This also happens for amenities that couldn't be assigned to any OSM building.
+We obtain four different categories of buildings with amenities:
+
+* Buildings with amenities
+* Synthetic buildings with amenities
+* Buildings with synthetic amenities
+* Synthetic buildings with synthetic amenities
+
+All buildings with CTS, comprising OSM buildings and synthetic buildings, including
+the number of amenities within the building are written to database table
+:py:class:`openstreetmap.egon_cts_buildings <egon.data.datasets.electricity_demand_timeseries.cts_buildings.CtsBuildings>`.
+
+To determine each building's share of the HV-MV substation demand profile,
+first, the share of each building on the demand per census cell is calculated
+using the number of amenities per building.
+Then, the share of each census cell on the demand per HV-MV substation is determined
+using the annual demand defined by Peta5.
+Both shares are finally multiplied and summed per building ID to determine each
+building's share of the HV-MV substation demand profile. The summing per building ID is
+necessary, as buildings can lie in multiple census cells and are therefore assigned
+a share in each of these census cells.
+The share of each CTS building on the CTS electricity demand profile per HV-MV substation
+in each scenario is saved to the database table
+:py:class:`demand.egon_cts_electricity_demand_building_share <egon.data.datasets.electricity_demand_timeseries.cts_buildings.EgonCtsElectricityDemandBuildingShare>`.
+The CTS electricity peak load per building is written to database table
+:py:class:`demand.egon_building_electricity_peak_loads <egon.data.datasets.electricity_demand_timeseries.hh_buildings.BuildingElectricityPeakLoads>`.
+
+Drawbacks and limitations as well as assumptions and challenges of the disaggregation
+are discussed in the dataset docstring of
+:py:class:`CtsDemandBuildings <egon.data.datasets.electricity_demand_timeseries.cts_buildings.CtsDemandBuildings>`.

src/egon/data/datasets/electricity_demand_timeseries/cts_buildings.py

@@ -127,12 +127,13 @@ class CtsDemandBuildings(Dataset):
     Generates CTS electricity and heat demand time series for scenarios in 2035 and 2050
     assigned to OSM-buildings.
 
-    Disaggregation of CTS heat & electricity demand time series from MV Substation
-    to census cells via annual demand and then to OSM buildings via
+    Disaggregation of CTS heat & electricity demand time series from HV-MV substation
+    to census cells via annual demand per census cell and then to OSM buildings via
     amenity tags or randomly if no sufficient OSM-data is available in the
     respective census cell. If no OSM-buildings or synthetic residential buildings
     are available new synthetic 5x5m buildings are generated.
 
+    For more information see data documentation on :ref:`disagg-cts-elec-ref`.
 
     *Dependencies*
       * :py:class:`OsmBuildingsStreets <egon.data.datasets.osm_buildings_streets.OsmBuildingsStreets>`
@@ -181,15 +182,6 @@ class CtsDemandBuildings(Dataset):
         DemandRegio SLP Gas for selected economic sectors at nuts3. Scaled with
         annual demand from `demand.egon_peta_heat`.
 
-    **What is the goal?**
-
-    To disaggregate cts heat and electricity time series from MV substation level
-    to geo-referenced buildings, the annual demand from DemandRegio and Peta5 is
-    used to identify census cells with load demand. We use Openstreetmap data and
-    filter tags to identify buildings and count the  amenities within. The number
-    of amenities and the annual demand serve to assign a demand share of the MV
-    substation profile to the building.
-
     **What is the challenge?**
 
     The OSM, DemandRegio and Peta5 dataset differ from each other. The OSM dataset
@@ -202,41 +194,6 @@ class CtsDemandBuildings(Dataset):
     be addressed. For example: not yet tagged buildings or amenities in OSM, or
     building shapes exceeding census cells.
 
-
-    **How are these datasets combined?**
-
-
-    The methodology for heat and electricity is the same and only differs in the
-    annual demand and MV/HV Substation profile. In a previous dataset
-    (openstreetmap), we filter all OSM buildings and amenities for tags, we relate
-    to the cts sector. Amenities are mapped to intersecting buildings and then
-    intersected with the annual demand which exists at census cell level. We obtain
-    census cells with demand and amenities and without amenities. If there is no
-    data on amenities, synthetic ones are assigned to existing buildings. We use
-    the median value of amenities/census cell for n and all filtered buildings +
-    synthetic residential buildings. If no building data is available a synthetic
-    building is randomly generated. This also happens for amenities which couldn't
-    be assigned to any osm building. All census cells with an annual demand are
-    covered this way, and we obtain four different categories of buildings with
-    amenities:
-
-    * Buildings with amenities
-    * Synthetic buildings with amenities
-    * Buildings with synthetic amenities
-    * Synthetics buildings with synthetic amenities
-
-    The amenities are summed per census cell (of amenity) and building to derive
-    the building amenity share per census cell. Multiplied with the annual demand,
-    we receive the profile demand share for each cell. Some buildings exceed the
-    census cell shape and have amenities in different cells although mapped to one
-    building only. To have unique buildings the demand share is summed once more
-    per building id. This factor can now be used to obtain the profile for each
-    building.
-
-    A schematic flow chart exist in the correspondent issue #671:
-    https://github.com/openego/eGon-data/issues/671#issuecomment-1260740258
-
-
     **What are central assumptions during the data processing?**
 
     * We assume OSM data to be the most reliable and complete open source dataset.
@@ -245,7 +202,6 @@ class CtsDemandBuildings(Dataset):
     * Missing OSM buildings are generated for each amenity.
     * Missing amenities are generated by median value of amenities/census cell.
 
-
     **Drawbacks and limitations of the data**
 
     * Shape of profiles for each building is similar within a MVGD and only scaled
@@ -446,9 +402,9 @@ def buildings_with_amenities():
     """
     Amenities which are assigned to buildings are determined and grouped per
     building and zensus cell. Buildings covering multiple cells therefore
-    exists multiple times but in different zensus cells. This is necessary to
+    exist multiple times but in different zensus cells. This is necessary to
     cover as many cells with a cts demand as possible. If buildings exist in
-    multiple mvgds (bus_id) , only the amenities within the same as the
+    multiple mvgds (bus_id), only the amenities within the same as the
     building centroid are kept. If as a result, a census cell is uncovered
     by any buildings, a synthetic amenity is placed. The buildings are
     aggregated afterwards during the calculation of the profile_share.