Get rid of duplicated documentation and cross-reference data and data…

…set documentation

docs/data/electricity_supply.rst

@@ -25,6 +25,8 @@ Offshore wind
 PV ground mounted
 ++++++++++++++++++
 
+.. _pv-rooftop-ref:
+
 PV rooftop
 +++++++++++
 

src/egon/data/datasets/emobility/motorized_individual_travel/db_classes.py

@@ -25,7 +25,8 @@
 
 
 class EgonEvPool(Base):
-    """Motorized individual travel: EV pool
+    """
+    Class definition of table demand.egon_ev_pool.
 
     Each row is one EV, uniquely defined by either (`ev_id`) or
     (`rs7_id`, `type`, `simbev_id`).
@@ -66,7 +67,8 @@ class EgonEvPool(Base):
 
 
 class EgonEvTrip(Base):
-    """Motorized individual travel: EVs' trips
+    """
+    Class definition of table demand.egon_ev_trip.
 
     Each row is one event of a specific electric vehicle which is
     uniquely defined by `rs7_id`, `ev_id` and `event_id`.
@@ -166,7 +168,12 @@ class EgonEvTrip(Base):
 
 
 class EgonEvCountRegistrationDistrict(Base):
-    """Electric vehicle counts per registration district"""
+    """
+    Class definition of table demand.egon_ev_count_registration_district.
+
+    Contains electric vehicle counts per registration district.
+
+    """
 
     __tablename__ = "egon_ev_count_registration_district"
     __table_args__ = {"schema": "demand"}
@@ -184,7 +191,12 @@ class EgonEvCountRegistrationDistrict(Base):
 
 
 class EgonEvCountMunicipality(Base):
-    """Electric vehicle counts per municipality"""
+    """
+    Class definition of table demand.egon_ev_count_municipality.
+
+    Contains electric vehicle counts per municipality.
+
+    """
 
     __tablename__ = "egon_ev_count_municipality"
     __table_args__ = {"schema": "demand"}
@@ -202,7 +214,12 @@ class EgonEvCountMunicipality(Base):
 
 
 class EgonEvCountMvGridDistrict(Base):
-    """Electric vehicle counts per MV grid district"""
+    """
+    Class definition of table demand.egon_ev_count_mv_grid_district.
+
+    Contains electric vehicle counts per MV grid district.
+
+    """
 
     __tablename__ = "egon_ev_count_mv_grid_district"
     __table_args__ = {"schema": "demand"}
@@ -222,7 +239,12 @@ class EgonEvCountMvGridDistrict(Base):
 
 
 class EgonEvMvGridDistrict(Base):
-    """List of electric vehicles per MV grid district"""
+    """
+    Class definition of table demand.egon_ev_mv_grid_district.
+
+    Contains list of electric vehicles per MV grid district.
+
+    """
 
     __tablename__ = "egon_ev_mv_grid_district"
     __table_args__ = {"schema": "demand"}
@@ -238,7 +260,12 @@ class EgonEvMvGridDistrict(Base):
 
 
 class EgonEvMetadata(Base):
-    """List of EV Pool Metadata"""
+    """
+    Class definition of table demand.egon_ev_metadata.
+
+    Contains EV Pool Metadata.
+
+    """
 
     __tablename__ = "egon_ev_metadata"
     __table_args__ = {"schema": "demand"}

src/egon/data/datasets/loadarea/__init__.py

@@ -81,11 +81,6 @@ class LoadArea(Dataset):
     """
     Creates load area data based on OSM and census data.
 
-    Create and update the `demand.egon_loadarea` table with new data, based on OSM and
-    census data. Among other things, area updates are carried out, smaller load areas
-    are removed, center calculations are performed, and census data are added.
-    Statistics for various OSM sectors are also calculated and inserted.
-
     *Dependencies*
       * :py:class:`OsmLanduse <egon.data.datasets.loadarea.OsmLanduse>`
       * :py:class:`ZensusVg250 <egon.data.datasets.zensus_vg250.ZensusVg250>`
@@ -97,6 +92,12 @@ class LoadArea(Dataset):
     *Resulting tables*
       * :class:`demand.egon_loadarea` is created and filled (no associated Python class)
 
+    Create and update the `demand.egon_loadarea` table with new data, based on OSM and
+    census data. Among other things, area updates are carried out, smaller load areas
+    are removed, center calculations are performed, and census data are added.
+    Statistics for various OSM sectors are also calculated and inserted.
+    See also documentation section :ref:`load-areas-ref` for more information.
+
     Note: industrial demand contains:
       * voltage levels 4-7
       * only demand from ind. sites+osm located in LA!

src/egon/data/datasets/mastr.py

@@ -1,5 +1,5 @@
 """
-Download Marktstammdatenregister (MaStR) datasets unit registry.
+Download Marktstammdatenregister (MaStR) from Zenodo.
 
 """
 
@@ -51,7 +51,10 @@ def download(dataset_name, download_dir):
 
 class mastr_data_setup(Dataset):
     """
-    Download Marktstammdatenregister (MaStR) datasets unit registry.
+    Download Marktstammdatenregister (MaStR) from Zenodo.
+
+    *Dependencies*
+      * :py:func:`Setup <egon.data.datasets.database.setup>`
 
     The downloaded data incorporates two different datasets:
 
@@ -69,8 +72,7 @@ class mastr_data_setup(Dataset):
         <egon.data.datasets.power_plants.mastr>` and :py:class:`PowerPlants
         <egon.data.datasets.power_plants.PowerPlants>`
 
-    *Dependencies*
-      * :py:func:`Setup <egon.data.datasets.database.setup>`
+    See documentation section :ref:`mastr-ref` for more information.
 
     """
 

src/egon/data/datasets/mv_grid_districts.py

@@ -796,72 +796,10 @@ def define_mv_grid_districts():
 
 class mv_grid_districts_setup(Dataset):
     """
-    Maps MV grid districts to federal states and writes it to database.
-
-    Medium-voltage grid districts describe the area supplied by one MV grid.
-
-    Medium-voltage grid districts are defined by one polygon that represents
-    the supply area. Each MV grid district is connected to the HV grid via a
-    single substation.
-
-    The methods used for identifying the MV grid districts are heavily
-    inspired by `Hülk et al. (2017)
-    <https://somaesthetics.aau.dk/index.php/sepm/article/view/1833/1531>`_
-    (section 2.3), but the implementation differs in detail. The main
-    difference is that direct adjacency is preferred over proximity. For
-    polygons of municipalities without a substation inside, it is
-    iteratively checked for direct adjacent other polygons that have a
-    substation inside. Speaking visually, a MV grid district grows around a
-    polygon with a substation inside.
-
-    The grid districts are identified using three data sources
-
-    1. Polygons of municipalities (:class:`Vg250GemClean`)
-    2. HV-MV substations (:class:`EgonHvmvSubstation`)
-    3. HV-MV substation voronoi polygons
-       (:class:`EgonHvmvSubstationVoronoi`)
-
-    Fundamentally, it is assumed that grid districts (supply areas) often go
-    along borders of administrative units, in particular along the borders
-    of municipalities due to the concession levy.
-    Furthermore, it is assumed that one grid district is supplied via a
-    single substation and that locations of substations and grid districts
-    are designed for aiming least lengths of grid line and cables.
-
-    With these assumptions, the three data sources from above are processed
-    as follows:
-
-    * Find the number of substations inside each municipality.
-    * Split municipalities with more than one substation inside.
-
-      * Cut polygons of municipalities with voronoi polygons of respective
-        substations.
-      * Assign resulting municipality polygon fragments to nearest
-        substation.
-    * Assign municipalities without a single substation to nearest
-      substation in the neighborhood.
-    * Merge all municipality polygons and parts of municipality polygons to
-      a single polygon grouped by the assigned substation.
-
-    For finding the nearest substation, as already said, direct adjacency is
-    preferred over closest distance. This means, the nearest substation does
-    not necessarily have to be the closest substation in the sense of
-    beeline distance. But it is the substation definitely located in a
-    neighboring polygon. This prevents the algorithm to find solutions where
-    a MV grid districts consists of multi-polygons with some space in
-    between.
-    Nevertheless, beeline distance still plays an important role, as the
-    algorithm acts in two steps
-
-    1. Iteratively look for neighboring polygons until there are no further
-       polygons.
-    2. Find a polygon to assign to by minimum beeline distance.
-
-    The second step is required in order to cover edge cases, such as
-    islands.
-
-    For understanding how this is implemented into separate functions,
-    please see :func:`define_mv_grid_districts`.
+    Sets up medium-voltage grid districts that describe the area supplied by one
+    MV grid.
+
+    See documentation section :ref:`mv-grid-districts` for more information.
 
     *Dependencies*
       * :py:class:`SubstationVoronoi

src/egon/data/datasets/osm/__init__.py

@@ -311,6 +311,8 @@ class OpenStreetMap(Dataset):
       * openstreetmap.osm_roads is created and filled (table has no associated python class)
       * openstreetmap.osm_ways is created and filled (table has no associated python class)
 
+    See documentation section :ref:`osm-ref` for more information.
+
     """
 
     #:

src/egon/data/datasets/power_plants/pv_rooftop.py

@@ -1,4 +1,4 @@
-"""The module containing all code dealing with pv rooftop distribution.
+"""The module containing all code dealing with pv rooftop distribution to MV grid level.
 """
 from pathlib import Path
 

src/egon/data/datasets/power_plants/pv_rooftop_buildings.py

@@ -2,41 +2,8 @@
 Distribute MaStR PV rooftop capacities to OSM and synthetic buildings. Generate
 new PV rooftop generators for scenarios eGon2035 and eGon100RE.
 
-Data cleaning and inference:
-* Drop duplicates and entries with missing critical data.
-* Determine most plausible capacity from multiple values given in MaStR data.
-* Drop generators which don't have any plausible capacity data
-  (23.5MW > P > 0.1).
-* Randomly and weighted add a start-up date if it is missing.
-* Extract zip and municipality from 'site' given in MaStR data.
-* Geocode unique zip and municipality combinations with Nominatim (1 sec
-  delay). Drop generators for which geocoding failed or which are located
-  outside the municipalities of Germany.
-* Add some visual sanity checks for cleaned data.
-
-Allocation of MaStR data:
-* Allocate each generator to an existing building from OSM.
-* Determine the quantile each generator and building is in depending on the
-  capacity of the generator and the area of the polygon of the building.
-* Randomly distribute generators within each municipality preferably within
-  the same building area quantile as the generators are capacity wise.
-* If not enough buildings exists within a municipality and quantile additional
-  buildings from other quantiles are chosen randomly.
-
-Desegregation of pv rooftop scenarios:
-* The scenario data per federal state is linearly distributed to the mv grid
-  districts according to the pv rooftop potential per mv grid district.
-* The rooftop potential is estimated from the building area given from the OSM
-  buildings.
-* Grid districts, which are located in several federal states, are allocated
-  PV capacity according to their respective roof potential in the individual
-  federal states.
-* The desegregation of PV plants within a grid districts respects existing
-  plants from MaStR, which did not reach their end of life.
-* New PV plants are randomly and weighted generated using a breakdown of MaStR
-  data as generator basis.
-* Plant metadata (e.g. plant orientation) is also added random and weighted
-  from MaStR data as basis.
+See documentation section :ref:`pv-rooftop-ref` for more information.
+
 """
 from __future__ import annotations
 
@@ -368,6 +335,10 @@ def load_mastr_data():
 
 
 class OsmBuildingsFiltered(Base):
+    """
+    Class definition of table openstreetmap.osm_buildings_filtered.
+
+    """
     __tablename__ = "osm_buildings_filtered"
     __table_args__ = {"schema": "openstreetmap"}
 
@@ -978,6 +949,10 @@ def scenario_data(
 
 
 class Vg250Lan(Base):
+    """
+    Class definition of table boundaries.vg250_lan.
+
+    """
     __tablename__ = "vg250_lan"
     __table_args__ = {"schema": "boundaries"}
 
@@ -2087,6 +2062,10 @@ def allocate_scenarios(
 
 
 class EgonPowerPlantPvRoofBuilding(Base):
+    """
+    Class definition of table supply.egon_power_plants_pv_roof_building.
+
+    """
     __tablename__ = "egon_power_plants_pv_roof_building"
     __table_args__ = {"schema": "supply"}