docs and tutorials for plotly plots

MDiesing · Apr 24, 2017 · 91d86c0 · 91d86c0
1 parent 269e30e
commit 91d86c0
Show file tree

Hide file tree

Showing 27 changed files with 65,709 additions and 72,058 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,8 @@ build/
 dist/
 .cache/
 .idea
+.DS_Store
+doc/.DS_Store
 pandapower.egg-info/
 doc/api/
 doc/.build/*
@@ -15,4 +17,6 @@ tutorials/.ipynb_checkpoints
 *.pyproj
 *.user
 *.sln
-*.bak
+*.bak
+
+
diff --git a/doc/getting_started/tutorials.rst b/doc/getting_started/tutorials.rst
@@ -33,10 +33,14 @@ Running topological searches:
     - `topologic searches <https://github.com/panda-power/pandapower/blob/master/tutorials/topology.ipynb>`_
 
 Plotting pandapower networks:
-    - `basic plotting <https://github.com/panda-power/pandapower/blob/master/tutorials/plotting_basic.ipynb>`_
-    - `plotting with colormaps <https://github.com/panda-power/pandapower/blob/master/tutorials/plotting_colormaps.ipynb>`_
-    - `plotting without geographical data <https://github.com/panda-power/pandapower/blob/master/tutorials/plotting_structural.ipynb>`_
-
+    * matplotlib
+        - `basic plotting <https://github.com/panda-power/pandapower/blob/master/tutorials/plotting_basic.ipynb>`_
+        - `plotting with colormaps <https://github.com/panda-power/pandapower/blob/master/tutorials/plotting_colormaps.ipynb>`_
+        - `plotting without geographical data <https://github.com/panda-power/pandapower/blob/master/tutorials/plotting_structural.ipynb>`_
+    * plotly
+        - `built-in plots <http://nbviewer.jupyter.org/github/lthurner/pandapower/blob/develop/tutorials/plotly_built-in.ipynb>`_
+        - `custom plots plots <http://nbviewer.jupyter.org/github/lthurner/pandapower/blob/develop/tutorials/plotly_traces.ipynb>`_
+        - `map plots <http://nbviewer.jupyter.org/github/lthurner/pandapower/blob/develop/tutorials/plotly_maps.ipynb>`_
 
 To run the tutorials interactively (jupyter module is needed):
 

diff --git a/doc/pics/.DS_Store b/doc/pics/.DS_Store
diff --git a/doc/pics/pf_res_plotly_map_mvoberr_sample.png b/doc/pics/pf_res_plotly_map_mvoberr_sample.png
diff --git a/doc/pics/pf_res_plotly_mvoberr_sample.png b/doc/pics/pf_res_plotly_mvoberr_sample.png
diff --git a/doc/pics/simple_plotly_map_mvoberr_sample.png b/doc/pics/simple_plotly_map_mvoberr_sample.png
diff --git a/doc/pics/simple_plotly_mapsatelite_mvoberr_sample.png b/doc/pics/simple_plotly_mapsatelite_mvoberr_sample.png
diff --git a/doc/pics/simple_plotly_mvoberr_sample.png b/doc/pics/simple_plotly_mvoberr_sample.png
diff --git a/doc/pics/simple_plotly_mvoberrhein.png b/doc/pics/simple_plotly_mvoberrhein.png
diff --git a/doc/pics/vlevel_plotly_mvoberr_sample.png b/doc/pics/vlevel_plotly_mvoberr_sample.png
diff --git a/doc/plotting.rst b/doc/plotting.rst
@@ -2,19 +2,15 @@
 Plotting Networks
 #############################
 
-pandapower provides the functionality to translate pandapower network elements into matplotlib collections. The different collections for lines, buses or transformers can than be drawn with pyplot.
+pandapower includes enables plotting networks with two plotting packages:
+* `Matplotlib <https://matplotlib.org/>`_
+* `Plotly <https://plot.ly/python/>`_ - interactive plots and plots on maps provided geocoordinates and mapbox account are available.
 
-If no coordinates are available for the buses, pandapower provides possibility to create generic coordinates through the igraph package. If no geocoordinates are available for the lines, they
-can be plotted as direct connections between the buses.
 
 .. toctree:: 
     :maxdepth: 1
 
-    plotting/simple_plot
-    plotting/create_collections
-    plotting/create_colormaps
-    plotting/draw
-    plotting/generic
-
+    plotting/matplotlib/matplotlib
+    plotting/plotly/plotly
 
 
diff --git a/doc/plotting/create_collections.rst → ...lotting/matplotlib/create_collections.rst b/doc/plotting/create_collections.rst → ...lotting/matplotlib/create_collections.rst
diff --git a/doc/plotting/create_colormaps.rst → doc/plotting/matplotlib/create_colormaps.rst b/doc/plotting/create_colormaps.rst → doc/plotting/matplotlib/create_colormaps.rst
diff --git a/doc/plotting/draw.rst → doc/plotting/matplotlib/draw.rst b/doc/plotting/draw.rst → doc/plotting/matplotlib/draw.rst
diff --git a/doc/plotting/generic.rst → doc/plotting/matplotlib/generic.rst b/doc/plotting/generic.rst → doc/plotting/matplotlib/generic.rst
diff --git a/doc/plotting/matplotlib/matplotlib.rst b/doc/plotting/matplotlib/matplotlib.rst
@@ -0,0 +1,17 @@
+#############################
+Matplotlib Network Plots
+#############################
+
+pandapower provides the functionality to translate pandapower network elements into matplotlib collections. The different collections for lines, buses or transformers can than be drawn with pyplot.
+
+If no coordinates are available for the buses, pandapower provides possibility to create generic coordinates through the igraph package. If no geocoordinates are available for the lines, they
+can be plotted as direct connections between the buses.
+
+.. toctree::
+    :maxdepth: 1
+
+    simple_plot
+    create_collections
+    create_colormaps
+    draw
+    generic
diff --git a/doc/plotting/simple_plot.rst → doc/plotting/matplotlib/simple_plot.rst b/doc/plotting/simple_plot.rst → doc/plotting/matplotlib/simple_plot.rst
diff --git a/doc/plotting/plotly/built-in_plots.rst b/doc/plotting/plotly/built-in_plots.rst
@@ -0,0 +1,72 @@
+#############################
+Built-in plot functions
+#############################
+
+=============================
+Simple Plotting
+=============================
+
+The function simple_plotly() can be used for simple plotting. For advanced possibilities see the tutorials.
+
+.. _simple_plotly:
+
+.. autofunction:: pandapower.plotting.plotly.simple_plotly
+
+Example plot with mv_oberrhein network from the pandapower.networks package:
+
+.. image:: /pics/simple_plotly_mvoberr_sample.png
+	:width: 30em
+	:align: center
+
+Examples plot on a map:
+
+.. image:: /pics/simple_plotly_map_mvoberr_sample.png
+	:width: 30em
+	:align: center
+
+.. image:: /pics/simple_plotly_mapsatelite_mvoberr_sample.png
+	:width: 30em
+	:align: center
+
+
+
+===============================================
+Network coloring according to voltage levels
+===============================================
+
+The function vlevel_plotly() is used to plot a network colored and labeled according to voltage levels. For advanced possibilities see the tutorials.
+
+.. _vlevel_plotly:
+
+.. autofunction:: pandapower.plotting.plotly.vlevel_plotly
+
+Example plot with mv_oberrhein network from the pandapower.networks package:
+
+.. image:: /pics/vlevel_plotly_mvoberr_sample.png
+	:width: 30em
+	:align: center
+
+
+=============================
+Power Flow results
+=============================
+
+The function pf_res_plotly() is used to plot a network according to power flow results where a colormap is used to represent line loading and voltage magnitudes. For advanced possibilities see the tutorials.
+
+.. _pf_res_plotly:
+
+.. autofunction:: pandapower.plotting.plotly.pf_res_plotly
+
+Example plot with mv_oberrhein network from the pandapower.networks package:
+
+.. image:: /pics/pf_res_plotly_mvoberr_sample.png
+	:width: 30em
+	:align: center
+
+A map plot:
+
+.. image:: /pics/pf_res_plotly_map_mvoberr_sample.png
+	:width: 30em
+	:align: center
+
+
diff --git a/doc/plotting/plotly/create_collections.rst b/doc/plotting/plotly/create_collections.rst
@@ -0,0 +1,19 @@
+==============================
+Create Traces
+==============================
+
+Plotly traces can be created from pandapower networks with the following functions:
+
+Bus Traces
+==============================
+
+.. autofunction:: pandapower.plotting.plotly.create_bus_trace
+
+
+
+Branch Traces
+==============================
+
+.. autofunction:: pandapower.plotting.plotly.create_line_trace
+
+.. autofunction:: pandapower.plotting.plotly.create_trafo_trace
diff --git a/doc/plotting/plotly/geo_data_to_latlong.rst b/doc/plotting/plotly/geo_data_to_latlong.rst
@@ -0,0 +1,8 @@
+============================================================
+Transforming network geodata from any projection to lat/long
+============================================================
+
+In case network geodata are not in The World Geodetic System (WGS84), that is latitude/longitude format, but in some of the map-projections, it may be converted to lat/long by providing name of the projection (in the form ``'epsg:projection_number'`` according to `spatialreference <http://spatialreference.org/ref/epsg/>`_).
+A sample of converting geodata from mv_oberrhein network can be found in the tutorial.
+
+.. autofunction:: pandapower.plotting.plotly.geo_data_to_latlong
diff --git a/doc/plotting/plotly/plotly.rst b/doc/plotting/plotly/plotly.rst
@@ -0,0 +1,24 @@
+#############################
+Plotly Network Plots
+#############################
+
+pandapower provides interactive network plots using `Plotly <https://plot.ly/python/>`_.
+These plots are built with arguments and functionalities to be as much as possible analogous with pandapower's
+matlpotlib plotting library.
+There is a functionality to translate pandapower network elements into plotly collections (traces).
+The different collections for lines, buses or transformers can than be drawn.
+
+If a network has geocoordinates, there is a possibility to represent interactive plots on `Mapbox <https://www.mapbox.com/>`_ maps.
+
+.. note::
+
+    Plots on Mapbox maps are available only considering you have a Mapbox account and a `Mapbox Access Token <https://www.mapbox.com/studio>`_ which you can add to your pandapower.plotting settings.
+
+
+
+.. toctree::
+    :maxdepth: 1
+
+    built-in_plots
+    create_collections
+    geo_data_to_latlong
diff --git a/pandapower/plotting/__init__.py b/pandapower/plotting/__init__.py
@@ -3,4 +3,7 @@
 from pandapower.plotting.generic_geodata import *
 from pandapower.plotting.powerflow_results import *
 from pandapower.plotting.simple_plot import *
-from pandapower.plotting.plotly import *
+try:
+    from pandapower.plotting.plotly import *
+except:
+    pass
diff --git a/pandapower/plotting/plotly.py b/pandapower/plotting/plotly.py
@@ -65,6 +65,8 @@ def get_cmap_matplotlib_for_plotly(values, cmap_name='jet', cmin=None, cmax=None
 except:
     import logging
 
+logger = logging.getLogger(__name__)
+
 try:
     import seaborn
     import matplotlib.colors as colors_mbl
@@ -76,9 +78,8 @@ def get_cmap_matplotlib_for_plotly(values, cmap_name='jet', cmin=None, cmax=None
     color_yellow = seaborn_to_plotly_color(seaborn.xkcd_palette(["amber"])[0])
     # color_yellow = colors_bright[4]
 except:
-    colors = ["b", "g", "r", "c", "y"]
-
-logger = logging.getLogger(__name__)
+    colors = ["blue", "green", "red", "cyan", "yellow"]
+    color_yellow = "yellow"
 
 
 
@@ -111,10 +112,16 @@ def _on_map_test(x, y):
 
 def geo_data_to_latlong(net, projection):
     """
-    
-    :param net: 
-    :param projection: 
-    :return: 
+    Transforms network's geodata (in `net.bus_geodata` and `net.line_geodata`) from specified projection to lat/long (WGS84).
+
+    INPUT:      
+        **net** (pandapowerNet) - The pandapower network
+        
+        **projection** (String) - projection from which geodata are transformed to lat/long. some examples  
+        
+                - "epsg:31467" - 3-degree Gauss-Kruger zone 3
+                - "epsg:2032" - NAD27(CGQ77) / UTM zone 18N
+                - "epsg:2190" - Azores Oriental 1940 / UTM zone 26N
     """
     try:
         from pyproj import Proj, transform
@@ -159,7 +166,7 @@ def create_bus_trace(net, buses=None, size=5, patch_type="circle", color="blue",
     """
     Creates a plotly trace of pandapower buses.
 
-    Input:
+    INPUT:
         **net** (pandapowerNet) - The pandapower network
 
     OPTIONAL:
@@ -291,7 +298,7 @@ def create_line_trace(net, lines=None, use_line_geodata=True,
     """
         Creates a plotly trace of pandapower lines.
 
-        Input:
+        INPUT:
             **net** (pandapowerNet) - The pandapower network
 
         OPTIONAL:
@@ -451,7 +458,7 @@ def create_trafo_trace(net, trafos=None, color ='green', width = 5,
     """
         Creates a plotly trace of pandapower trafos.
 
-        Input:
+        INPUT:
             **net** (pandapowerNet) - The pandapower network
 
         OPTIONAL:
@@ -667,6 +674,7 @@ def draw_traces(traces, on_map = False, map_style='basic', showlegend = True, fi
     else:
         from plotly.offline import plot as plot
 
+
     plot(fig)
 
 
@@ -676,7 +684,7 @@ def simple_plotly(net=None, respect_switches=True, use_line_geodata=None,
                   line_width=1, bus_size=10, ext_grid_size=20.0,
                   bus_color=colors[0], line_color='grey', trafo_color='green', ext_grid_color=color_yellow):
     """
-    Plots a pandapower network as simple as possible in plotly (https://plot.ly/python/).
+    Plots a pandapower network as simple as possible in plotly.
     If no geodata is available, artificial geodata is generated. For advanced plotting see the tutorial
 
     INPUT:
@@ -793,7 +801,7 @@ def vlevel_plotly(net, respect_switches=True, use_line_geodata=None,
                   figsize=1, aspectratio='auto',
                   line_width=2, bus_size=10):
     """
-    Plots a pandapower network in plotly (https://plot.ly/python/)
+    Plots a pandapower network in plotly 
     using lines/buses colors according to the voltage level they belong to.
     If no geodata is available, artificial geodata is generated. For advanced plotting see the tutorial
 
@@ -916,7 +924,7 @@ def pf_res_plotly(net, cmap='Jet', use_line_geodata = None,
                   figsize=1, aspectratio='auto',
                   line_width=2, bus_size=10):
     """
-    Plots a pandapower network in plotly (https://plot.ly/python/)
+    Plots a pandapower network in plotly
     using colormap for coloring lines according to line loading and buses according to voltage in p.u.
     If no geodata is available, artificial geodata is generated. For advanced plotting see the tutorial
 

diff --git a/tutorials/plotly_built-in.ipynb b/tutorials/plotly_built-in.ipynb
diff --git a/tutorials/plotly_maps.ipynb b/tutorials/plotly_maps.ipynb
diff --git a/tutorials/plotly_traces.ipynb b/tutorials/plotly_traces.ipynb
diff --git a/tutorials/plotting_plotly.ipynb b/tutorials/plotting_plotly.ipynb