Features/#276 improve simple example

doc/conf.py

@@ -55,6 +55,7 @@
     "sphinx.ext.napoleon",  # enable Napoleon Sphinx v>1.3
     "sphinx.ext.extlinks",  # enables external links with a key
     "sphinx_autodoc_typehints",
+    "nbsphinx",
 ]
 
 # Napoleon settings

doc/examples.rst

@@ -0,0 +1,17 @@
+.. _examples_section_label:
+
+#############
+Examples
+#############
+
+This section provides examples on how to use the eDisGo package.
+It includes a `basic example <https://github.com/openego/eDisGo/blob/dev/examples/edisgo_simple_example.ipynb>`_,
+an `electromobility example <https://github.com/openego/eDisGo/blob/dev/examples/electromobility_example.ipynb>`_
+and a `plot example <https://github.com/openego/eDisGo/blob/dev/examples/plot_example.ipynb>`_.
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   notebooks/edisgo_simple_example.ipynb
+   notebooks/plot_example.ipynb

doc/index.rst

@@ -63,6 +63,7 @@ Contents
    :maxdepth: 2
 
    quickstart
+   examples
    usage_details
    features_in_detail
    dev_notes

doc/notebooks/edisgo_simple_example.ipynb

@@ -0,0 +1 @@
+../../examples/edisgo_simple_example.ipynb

doc/notebooks/plot_example.ipynb

@@ -0,0 +1 @@
+../../examples/plot_example.ipynb

doc/usage_details.rst

@@ -554,8 +554,6 @@ curtailment requirements. It uses the EDisGo object from above.
 Plots
 ----------------
 
-.. todo:: Add plotly plot option
-
 EDisGo provides a bunch of predefined plots to e.g. plot the MV grid topology,
 line loading and node voltages in the MV grid or as a histograms.
 
@@ -567,6 +565,18 @@ line loading and node voltages in the MV grid or as a histograms.
     # plot grid expansion costs for lines in the MV grid and stations on a map
     edisgo.plot_mv_grid_expansion_costs()
 
+    # draw a plotly html figure showing relative loading and voltage deviation
+    # in the MV grid
+    from edisgo.tools.plots import draw_plotly
+    draw_plotly(
+        edisgo=edisgo,
+        line_color="relative_loading",
+        node_color="voltage_deviation",
+    )
+
+    # dash plot allowing to interactively toggle between different plotting options
+    plot_dash(edisgo_objects=edisgo)
+
     # plot voltage histogram
     edisgo.histogram_voltage()
 

edisgo/io/electromobility_import.py

@@ -478,6 +478,26 @@ def distribute_charging_demand(edisgo_obj, **kwargs):
     """
     Distribute charging demand from SimBEV onto potential charging parks from TracBEV.
 
+    The allocation of the charging processes
+    to the charging infrastructure is carried out with the help of the weighting factor
+    of the potential charging parks determined by TracBEV. This involves a random and
+    weighted selection of one charging park per charging process. In the case of private
+    charging infrastructure, a separate charging point is set up for each EV. All
+    charging processes of the respective EV and charging use case are assigned to this
+    charging point. The allocation of private charging processes to charging stations
+    is implemented in
+    :py:func:`~edisgo.io.electromobility_import.distribute_private_charging_demand`.
+
+     For the public charging infrastructure, the allocation is made explicitly per
+     charging process. For each charging process it is determined whether a suitable
+     charging point is already available. For this purpose it is checked if the charging
+     point is occupied by another EV in the corresponding period and whether it can
+     provide the corresponding charging capacity. If no suitable charging point is
+     available, a charging point is determined randomly and weighted in the same way as
+     for private charging. The allocation of public charging processes to charging
+     stations is implemented in
+     :py:func:`~edisgo.io.electromobility_import.distribute_public_charging_demand`.
+
     Parameters
     ----------
     edisgo_obj : :class:`~.EDisGo`

edisgo/tools/plots.py

@@ -919,10 +919,10 @@ def plot_plotly(
     edisgo_obj : :class:`~.EDisGo`
         Selected edisgo_obj to get plotting information from.
 
-    grid : :class:`~.network.grids.Grid`
+    grid : :class:`~.network.grids.Grid`, optional
         Grid to plot. If None, the MVGrid of the edisgo_obj is plotted. Default: None.
 
-    line_color : str or None
+    line_color : str or None, optional
         Defines whereby to choose line colors. Possible options are:
 
         * 'loading'
@@ -934,7 +934,7 @@ def plot_plotly(
         * None
             Line color is black. This is also the fallback, in case other options fail.
 
-    node_color : str or None
+    node_color : str or None, optional
         Defines whereby to choose node colors. Possible options are:
 
         * 'adjacencies'
@@ -945,15 +945,15 @@ def plot_plotly(
         * None
             Line color is black. This is also the fallback, in case other options fail.
 
-    line_result_selection : str
+    line_result_selection : str, optional
         Defines which values are shown for the load of the lines:
 
         * 'min'
             Minimal line load of all time steps.
         * 'max' (default)
             Maximal line load of all time steps.
 
-    node_result_selection : str
+    node_result_selection : str, optional
         Defines which values are shown for the voltage of the nodes:
 
         * 'min'
@@ -962,7 +962,7 @@ def plot_plotly(
             Maximal node voltage of all time steps.
 
     selected_timesteps : :pandas:`pandas.Timestamp<Timestamp>` or \
-        list(:pandas:`pandas.Timestamp<Timestamp>`) or None
+        list(:pandas:`pandas.Timestamp<Timestamp>`) or None, optional
         Selected time steps to show results for.
 
         * None (default)
@@ -971,15 +971,15 @@ def plot_plotly(
             :pandas:`pandas.Timestamp<Timestamp>`
           Selected time steps are used.
 
-    center_coordinates : bool
+    center_coordinates : bool, optional
         Enables the centering of the coordinates. If True the transformer node is set
         to the coordinates x=0 and y=0. Else, the coordinates from the HV/MV-station
         of the MV grid are used. Default: False.
 
-    pseudo_coordinates : bool
+    pseudo_coordinates : bool, optional
         Enable pseudo coordinates for the plotted grid. Default: False.
 
-    node_selection : bool or list(str)
+    node_selection : bool or list(str), optional
         Only plot selected nodes. Default: False.
 
     Returns
@@ -1482,7 +1482,7 @@ def plot_dash_app(
         objects pass a dictionary with the eDisGo objects as values and the respective
         eDisGo object names as keys.
 
-    debug : bool
+    debug : bool, optional
         Debugging for the dash app:
 
         * False (default)