Merge pull request #1138 from openego/documentation/rli_datasets

This PR adds dataset documentation for all RLI datasets.

docs/conf.py

@@ -47,3 +47,8 @@
 
 add_module_names = False
 modindex_common_prefix = ["egon.data.", "egon.data.datasets."]
+
+autodoc_type_aliases = {
+    "Dependencies": "egon.data.datasets.Dependencies",
+    "Tasks": "egon.data.datasets.Tasks"
+}

docs/data.rst

@@ -1,22 +1,22 @@
 ****
 Data
 ****
-The description of the methods, input data and results of the eGon-data pipeline is given in the following section. 
+The description of the methods, input data and results of the eGon-data pipeline is given in the following section.
 References to datasets and functions are integrated if more detailed information is required.
 
 Main input data and their processing
 ====================================
 
 All methods in the eGon-data workflow rely on public and freely available data from different external sources. The most important data sources
-and their processing within the eGon-data pipeline are described here. 
+and their processing within the eGon-data pipeline are described here.
 
 .. include:: data/input_data.rst
 
 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.
-In addition, sector coupling necessitates the representation of the gas grid infrastructure, which is also described in this section. 
+In addition, sector coupling necessitates the representation of the gas grid infrastructure, which is also described in this section.
 
 Electricity grid
 ----------------
@@ -31,8 +31,8 @@ Gas grid
 Demand
 ======
 
-Electricity, heat and gas demands from different consumption sectors are taken into account in eGon-data. The related methods to distribute and 
-process the demand data are described in the following chapters for the different consumption sectors separately. 
+Electricity, heat and gas demands from different consumption sectors are taken into account in eGon-data. The related methods to distribute and
+process the demand data are described in the following chapters for the different consumption sectors separately.
 
 .. _electricity-demand-ref:
 
@@ -51,6 +51,8 @@ Gas
 
 .. include:: data/gas_demand.rst
 
+.. _mobility-demand-ref:
+
 Mobility
 --------
 
@@ -60,8 +62,8 @@ Mobility
 Supply
 ======
 
-The distribution and assignment of supply capacities or potentials are carried out technology-specific. The different methods are described in the 
-following chapters. 
+The distribution and assignment of supply capacities or potentials are carried out technology-specific. The different methods are described in the
+following chapters.
 
 Electricity
 -----------
@@ -81,9 +83,9 @@ Gas
 Flexibility options
 ===================
 
-Different flexibility options are part of the model and can be utilized in the optimization of the energy system. Therefore detailed information about 
-flexibility potentials and their distribution are needed. The considered technologies described in the following chapters range from different storage units, 
-through dynamic line rating to Demand-Side-Management measures. 
+Different flexibility options are part of the model and can be utilized in the optimization of the energy system. Therefore detailed information about
+flexibility potentials and their distribution are needed. The considered technologies described in the following chapters range from different storage units,
+through dynamic line rating to Demand-Side-Management measures.
 
 Demand-Side-Management
 ----------------------

docs/data/electricity_supply.rst

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

docs/data/mobility_demand.rst

@@ -1,3 +1,5 @@
+.. _mobility-demand-mit-ref:
+
 Motorized individual travel
 ++++++++++++++++++++++++++++
 

docs/reference/egon.data.datasets.emobility.rst

@@ -2,5 +2,14 @@
 
 emobility
 =========
+.. toctree::
+   :maxdepth: 1
 
-.. py:module:: egon.data.datasets.emobility
+   egon.data.datasets.emobility.heavy_duty_transport
+   egon.data.datasets.emobility.motorized_individual_travel
+   egon.data.datasets.emobility.motorized_individual_travel_charging_infrastructure
+
+.. automodule:: egon.data.datasets.emobility
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/egon.data.datasets.rst

@@ -40,6 +40,7 @@ datasets
    egon.data.datasets.district_heating_areas
    egon.data.datasets.electricity_demand
    egon.data.datasets.electricity_demand_timeseries
+   egon.data.datasets.emobility
    egon.data.datasets.gas_neighbours
    egon.data.datasets.heat_demand
    egon.data.datasets.heat_demand_timeseries

src/egon/data/airflow/dags/pipeline.py

@@ -274,7 +274,7 @@
         ]
     )
 
-    # Get household electrical demands for cencus cells
+    # Get household electrical demands for census cells
     household_electricity_demand_annual = HouseholdElectricityDemand(
         dependencies=[
             tasks[
@@ -285,7 +285,7 @@
         ]
     )
 
-    # Distribute electrical CTS demands to zensus grid
+    # Distribute electrical CTS demands to census grid
     cts_electricity_demand_annual = CtsElectricityDemand(
         dependencies=[
             demandregio,

src/egon/data/datasets/__init__.py

@@ -98,6 +98,10 @@ class Model(Base):
 #: a :class:`tuple` of :class:`TaskGraphs <TaskGraph>` will be executed
 #: sequentially in the given order.
 TaskGraph = Union[Task, Set["TaskGraph"], Tuple["TaskGraph", ...]]
+#: A type alias to help specifying that something can be an explicit
+#: :class:`Tasks_` object or a :class:`TaskGraph`, i.e. something that
+#: can be converted to :class:`Tasks_`.
+Tasks = Union["Tasks_", TaskGraph]
 
 
 def prefix(o):
@@ -107,15 +111,15 @@ def prefix(o):
 
 
 @dataclass
-class Tasks(dict):
+class Tasks_(dict):
     first: Set[Task]
     last: Set[Task]
     graph: TaskGraph = ()
 
     def __init__(self, graph: TaskGraph):
         """Connect multiple tasks into a potentially complex graph.
 
-        Parses a :class:`TaskGraph` into a :class:`Tasks` object.
+        Parses a :class:`TaskGraph` into a :class:`Tasks_` object.
         """
         if isinstance(graph, Callable):
             graph = PythonOperator(
@@ -131,14 +135,14 @@ def __init__(self, graph: TaskGraph):
             self.first = {}
             self.last = {}
         elif isinstance(graph, abc.Set):
-            results = [Tasks(subtasks) for subtasks in graph]
+            results = [Tasks_(subtasks) for subtasks in graph]
             self.first = {task for result in results for task in result.first}
             self.last = {task for result in results for task in result.last}
             self.update(reduce(lambda d1, d2: dict(d1, **d2), results, {}))
             self.graph = set(tasks.graph for tasks in results)
         elif isinstance(graph, tuple):
-            results = [Tasks(subtasks) for subtasks in graph]
-            for (left, right) in zip(results[:-1], results[1:]):
+            results = [Tasks_(subtasks) for subtasks in graph]
+            for left, right in zip(results[:-1], results[1:]):
                 for last in left.last:
                     for first in right.first:
                         last.set_downstream(first)
@@ -149,13 +153,17 @@ def __init__(self, graph: TaskGraph):
         else:
             raise (
                 TypeError(
-                    "`egon.data.datasets.Tasks` got an argument of type:\n\n"
+                    "`egon.data.datasets.Tasks_` got an argument of type:\n\n"
                     f"  {type(graph)}\n\n"
                     "where only `Task`s, `Set`s and `Tuple`s are allowed."
                 )
             )
 
 
+#: A dataset can depend on other datasets or the tasks of other datasets.
+Dependencies = Iterable[Union["Dataset", Task]]
+
+
 @dataclass
 class Dataset:
     #: The name of the Dataset
@@ -172,10 +180,10 @@ class Dataset:
     #: downstream of any of the listed dependencies. In case of bare
     #: :class:`Task`, a direct link will be created whereas for a
     #: :class:`Dataset` the link will be made to all of its last tasks.
-    dependencies: Iterable[Union[Dataset, Task]] = ()
+    dependencies: Dependencies = ()
     #: The tasks of this :class:`Dataset`. A :class:`TaskGraph` will
-    #: automatically be converted to :class:`Tasks`.
-    tasks: Union[Tasks, TaskGraph] = ()
+    #: automatically be converted to :class:`Tasks_`.
+    tasks: Tasks = ()
 
     def check_version(self, after_execution=()):
         def skip_task(task, *xs, **ks):
@@ -224,8 +232,8 @@ def update(self, session):
 
     def __post_init__(self):
         self.dependencies = list(self.dependencies)
-        if not isinstance(self.tasks, Tasks):
-            self.tasks = Tasks(self.tasks)
+        if not isinstance(self.tasks, Tasks_):
+            self.tasks = Tasks_(self.tasks)
         if len(self.tasks.last) > 1:
             # Explicitly create single final task, because we can't know
             # which of the multiple tasks finishes last.
@@ -236,7 +244,7 @@ def __post_init__(self):
                 # Do nothing, because updating will be added later.
                 python_callable=lambda *xs, **ks: None,
             )
-            self.tasks = Tasks((self.tasks.graph, update_version))
+            self.tasks = Tasks_((self.tasks.graph, update_version))
         # Due to the `if`-block above, there'll now always be exactly
         # one task in `self.tasks.last` which the next line just
         # selects.