Add documentation on allocation of household electricity profiles to …

…buildings

docs/data.rst

@@ -15,7 +15,7 @@ and their processing within the eGon-data pipeline are described here.
 Grid models
 ===========
 
-Power grid models of different voltage levels form a central part of the eGon data model, which is required for cross-grid-level optimization.
+Power grid models of different voltage levels form a central part of the eGon-data model, which is required for cross-grid-level optimization.
 In addition, sector coupling necessitates the representation of the gas grid infrastructure, which is also described in this section.
 
 Electricity grid

docs/data/electricity_demand.rst

@@ -1,4 +1,35 @@
-Information about electricity demands and their spatial and temporal aggregation 
+Information about electricity demands and their spatial and temporal aggregation
+
+
+.. figure:: /images/workflow_household_demand.png
+  :name: workflow-res-profiles-buildings
+  :width: 800
+
+  Workflow to setup residential demand profiles per building in hourly resolution
+
+
+The allocation of the chosen electricity profiles in each census cell to buildings
+is conducted in the dataset
+:py:class:`Demand_Building_Assignment <egon.data.datasets.electricity_demand_timeseries.hh_buildings.setup>`.
+For each cell, the profiles are randomly assigned to an OSM building within this cell.
+If there are more profiles than buildings, all additional profiles are further randomly
+allocated to buildings within the cell.
+Therefore, multiple profiles can be assigned to one building, making it a
+multi-household building.
+In case there are no OSM buildings that profiles can be assigned to, synthetic buildings
+are generated with a dimension of 5m x 5m.
+The number of synthetically created buildings per census cell is determined using
+the Germany-wide average of profiles per building (value is rounded up and only
+census cells with buildings are considered).
+The profile ID each building is assigned is written to data base table
+:py:class:`demand.egon_household_electricity_profile_of_buildings <egon.data.datasets.electricity_demand_timeseries.hh_buildings.HouseholdElectricityProfilesOfBuildings>`.
+Synthetically created buildings are written to data base table
+:py:class:`openstreetmap.osm_buildings_synthetic <egon.data.datasets.electricity_demand_timeseries.hh_buildings.OsmBuildingsSynthetic>`.
+The household 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 of the allocation to specific buildings
+are discussed in the dataset docstring of
+:py:class:`Demand_Building_Assignment <egon.data.datasets.electricity_demand_timeseries.hh_buildings.setup>`.
 
 .. _disagg-cts-elec-ref:
 
@@ -37,7 +68,7 @@ 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.
+If no building data is available, a synthetic building with a dimension of 5m x 5m 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:
 
@@ -46,8 +77,10 @@ We obtain four different categories of 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
+Synthetically created buildings are written to data base table
+:py:class:`openstreetmap.osm_buildings_synthetic <egon.data.datasets.electricity_demand_timeseries.hh_buildings.OsmBuildingsSynthetic>`.
+Information on the number of amenities within each building with CTS, comprising OSM
+buildings and synthetic buildings, is 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,

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

@@ -757,13 +757,15 @@ def map_houseprofiles_to_buildings():
 
 class setup(Dataset):
     """
-    Household electricity demand time series for scenarios in 2035 and 2050
-    assigned to OSM-buildings.
+    Household electricity demand profiles for scenarios in 2035 and 2050
+    assigned to buildings.
 
     Assignment of household electricity demand timeseries to OSM buildings
     and generation of randomly placed synthetic 5x5m buildings if no
     sufficient OSM-data available in the respective census cell.
 
+    For more information see data documentation on :ref:`electricity-demand-ref`.
+
     *Dependencies*
       * :py:func:`houseprofiles_in_census_cells
         <egon.data.datasets.electricity_demand_timeseries.hh_profiles.houseprofiles_in_census_cells>`
@@ -798,31 +800,19 @@ class setup(Dataset):
 
     **What is the goal?**
 
-    To assign every household demand timeseries, which already exist at cell
-    level, to a specific OSM building.
+    To assign every household demand profile allocated each census cell to a
+    specific building.
 
     **What is the challenge?**
 
     The census and the OSM dataset differ from each other. The census uses
     statistical methods and therefore lacks accuracy at high spatial
-    resolution. The OSM datasets is community based dataset which is
+    resolution. The OSM dataset is a community based dataset which is
     extended throughout and does not claim to be complete. By merging these
     datasets inconsistencies need to be addressed. For example: not yet
     tagged buildings in OSM or new building areas not considered in census
     2011.
 
-    **How are these datasets combined?**
-
-    The assignment of household demand timeseries to buildings takes place
-    at cell level. Within each cell a pool of profiles exists, produced by
-    the 'HH Demand" module. These profiles are randomly assigned to a
-    filtered list of OSM buildings within this cell. Every profile is
-    assigned to a building and every building get a profile assigned if
-    there is enough households by the census data. If there are more
-    profiles than buildings, all additional profiles are randomly assigned.
-    Therefore, multiple profiles can be assigned to one building, making it a
-    multi-household building.
-
     **What are central assumptions during the data processing?**
 
     * Mapping zensus data to OSM data is not trivial.
@@ -840,11 +830,11 @@ class setup(Dataset):
       is ceiled to the next higher integer. Ceiling is applied to avoid
       rounding to amount of 0 buildings.
 
-    * As this datasets is a cascade after profile assignement at census
-      cells also check drawbacks and limitations in hh_profiles.py.
+    * As this dataset uses the load profile assignment at census cell level
+      conducted in hh_profiles.py, also check drawbacks and limitations in that module.
 
     Example Query
-    -----
+    ----------------
 
     * Get a list with number of houses, households and household types per
       census cell