Merge pull request #485 from Gomango999/tutorial-config

Configuration Instance + Visual Style Tutorials

Author: iosonofabio

doc/source/gallery.rst

@@ -2,43 +2,47 @@
 
 .. _gallery:
 
-========
+=======
 Gallery
-========
+=======
 
 This page contains short examples showcasing the functionality of |igraph|:
 
  - :ref:`tutorials-quickstart`
+ - :ref:`tutorials-articulation-points`
  - :ref:`tutorials-betweenness`
  - :ref:`tutorials-bipartite-matching`
  - :ref:`tutorials-bipartite-matching-maxflow`
+ - :ref:`tutorials-bridges`
  - :ref:`tutorials-cliques`
+ - :ref:`tutorials-configuration`
  - :ref:`tutorials-maxflow`
  - :ref:`tutorials-random`
  - :ref:`tutorials-ring-animation`
  - :ref:`tutorials-shortest-paths`
  - :ref:`tutorials-online-user-actions`
  - :ref:`tutorials-topological-sort`
+ - :ref:`tutorials-visual-style`
  - :ref:`tutorials-visualize-communities`
- - :ref:`tutorials-articulation-points`
- - :ref:`tutorials-bridges`
 
 
 .. toctree::
  :maxdepth: 2
  :hidden:
 
  tutorials/quickstart/quickstart
+ tutorials/articulation_points/articulation_points
  tutorials/betweenness/betweenness
  tutorials/bipartite_matching/bipartite_matching
  tutorials/bipartite_matching_maxflow/bipartite_matching_maxflow
+ tutorials/bridges/bridges
+ tutorials/configuration/configuration
  tutorials/erdos_renyi/erdos_renyi
  tutorials/maxflow/maxflow
+ tutorials/online_user_actions/online_user_actions
  tutorials/ring_animation/ring_animation
  tutorials/shortest_paths/shortest_paths
  tutorials/topological_sort/topological_sort
- tutorials/online_user_actions/online_user_actions
+ tutorials/visual_style/visual_style
  tutorials/visualize_cliques/visualize_cliques
  tutorials/visualize_communities/visualize_communities
- tutorials/articulation_points/articulation_points
- tutorials/bridges/bridges

doc/source/tutorials/configuration/assets/configuration1.py

@@ -0,0 +1,11 @@
+import igraph as ig
+
+# Set configuration variables
+ig.config["plotting.backend"] = "matplotlib"
+ig.config["plotting.layout"] = "fruchterman_reingold"
+ig.config["plotting.palette"] = "rainbow"
+
+# Save configuration to ~/.igraphrc
+ig.config.save()
+
+

doc/source/tutorials/configuration/assets/configuration2.py

@@ -0,0 +1,15 @@
+import igraph as ig
+import matplotlib.pyplot as plt
+import random
+
+# Generate a graph
+random.seed(1)
+g = ig.Graph.Barabasi(n=100, m=1)
+
+# Calculate a color value between 0-200 for all nodes
+betweenness = g.betweenness()
+colors = [int(i * 200 / max(betweenness)) for i in betweenness]
+
+# Plot the graph
+ig.plot(g, vertex_color=colors, vertex_size=1, edge_width=0.3)
+plt.show()

doc/source/tutorials/configuration/configuration.rst

@@ -0,0 +1,62 @@
+.. include:: ../../include/global.rst
+
+.. _tutorials-configuration:
+
+======================
+Configuration Instance
+======================
+
+This example shows how to use |igraph|'s `configuration instance <https://igraph.org/python/doc/api/igraph.configuration.Configuration.html>`_ to set default |igraph| settings. This is useful for setting global settings so that they don't need to be explicitly stated at the beginning of every |igraph| project you work on.
+
+First we define the default plotting backend, layout, and color palette, and save them. By default, ``ig.config.save()`` will save files to ``~/.igraphrc`` on Linux and Max OS X systems, or in ``C:\Documents and Settings\username\.igraphrc`` for Windows systems.
+
+.. code-block:: python
+
+ import igraph as ig
+
+ # Set configuration variables
+ ig.config["plotting.backend"] = "matplotlib"
+ ig.config["plotting.layout"] = "fruchterman_reingold"
+ ig.config["plotting.palette"] = "rainbow"
+
+ # Save configuration to ~/.igraphrc
+ ig.config.save()
+
+This script only needs to be run once (to store the new config options into the ``.igraphrc`` file). Whenever you use |igraph| and this file exists, |igraph| will read its content and use those options as defaults. For example:
+
+.. code-block:: python
+
+ import igraph as ig
+ import matplotlib.pyplot as plt
+ import random
+
+ # Generate a graph
+ random.seed(1)
+ g = ig.Graph.Barabasi(n=100, m=1)
+
+ # Calculate a color value between 0-200 for all nodes
+ betweenness = g.betweenness()
+ colors = [int(i * 200 / max(betweenness)) for i in betweenness]
+
+ # Plot the graph
+ ig.plot(g, vertex_color=colors, vertex_size=1, edge_width=0.3)
+ plt.show()
+
+Note that we do not never explicitly state the backend, layout or palette, yet the final plots look like this:
+
+.. figure:: ./figures/configuration.png
+ :alt: A 100 node graph colored to show betweenness
+ :align: center
+
+ Graph colored based on each node's betweenness centrality measure.
+
+The full list of config settings can be found `here <https://igraph.org/python/doc/api/igraph.configuration.Configuration.html>`_. 
+
+.. note::
+ 
+ You can have multiple config files: specify each location via ``ig.config.save("./path/to/config/file")``. To load a specific config, import igraph and then call ``ig.config.load("./path/to/config/file")``
+
+
+.. note::
+
+ To use a consistent style between individual plots (e.g. vertex sizes, colors, layout etc.) check out :ref:`tutorials-visual-style`. 

doc/source/tutorials/configuration/figures/configuration.png

@@ -0,0 +1,30 @@
+import igraph as ig
+import matplotlib.pyplot as plt
+import math
+import random
+
+# Configure visual style
+visual_style = {
+ "edge_width": 0.3,
+ "vertex_size": 1,
+ "palette": "heat",
+ "layout": "fruchterman_reingold"
+}
+
+# Generate graphs
+random.seed(1)
+g1 = ig.Graph.Barabasi(n=100, m=1)
+g2 = ig.Graph.Barabasi(n=100, m=1)
+
+# Calculate colors between 0-255 for all nodes
+betweenness1 = g1.betweenness()
+betweenness2 = g2.betweenness()
+colors1 = [int(i * 255 / max(betweenness1)) for i in betweenness1]
+colors2 = [int(i * 255 / max(betweenness2)) for i in betweenness2]
+
+# Plot the graphs
+fig, axs = plt.subplots(1, 2)
+ig.plot(g1, target=axs[0], vertex_color=colors1, **visual_style)
+ig.plot(g2, target=axs[1], vertex_color=colors2, **visual_style)
+plt.show()
+

doc/source/tutorials/visual_style/assets/visual_style.py

@@ -0,0 +1,52 @@
+.. include:: ../../include/global.rst
+
+.. _tutorials-visual-style:
+
+=================================================
+Making Multiple Graphs with the Same Visual Style
+=================================================
+
+This example shows how to use dictionary unpacking in order to easily use the same visual style across multiple graphs. This is a quick and easy way to quickly share a single visual style across multiple graphs, without having to copy and paste each of the individual attributes over and over again for each graph you plot.
+
+.. code-block:: python
+
+ import igraph as ig
+ import matplotlib.pyplot as plt
+ import math
+ import random
+
+ # Configure visual style for use in both graphs
+ visual_style = {
+ "edge_width": 0.3,
+ "vertex_size": 1,
+ "palette": "heat",
+ "layout": "fruchterman_reingold"
+ }
+
+ # Generate graphs
+ random.seed(1)
+ g1 = ig.Graph.Barabasi(n=100, m=1)
+ g2 = ig.Graph.Barabasi(n=100, m=1)
+
+ # Calculate colors between 0-255 for all nodes
+ betweenness1 = g1.betweenness()
+ betweenness2 = g2.betweenness()
+ colors1 = [int(i * 255 / max(betweenness1)) for i in betweenness1]
+ colors2 = [int(i * 255 / max(betweenness2)) for i in betweenness2]
+
+ # Plot the graphs, using the same predefined visual style for both
+ fig, axs = plt.subplots(1, 2)
+ ig.plot(g1, target=axs[0], vertex_color=colors1, **visual_style)
+ ig.plot(g2, target=axs[1], vertex_color=colors2, **visual_style)
+ plt.show()
+
+The plots looks like this:
+
+.. figure:: ./figures/visual_style.png
+ :alt: Two graphs plotted using the same palette and layout algorithm
+ :align: center
+
+ Two graphs using the same palette and layout algorithm.
+
+.. note::
+ If you would like to set global defaults, for example, always using the Matplotlib plotting backend, or using a particular color palette by default, you can use |igraph|'s `configuration instance <https://igraph.org/python/doc/api/igraph.configuration.Configuration.html>`_. A quick example on how to use it can be found here: :ref:`tutorials-configuration`