Add tutorial for configuration and visual style

Author: Gomango999

doc/source/gallery.rst

@@ -2,9 +2,9 @@
 
 .. _gallery:
 
-========
+=======
 Gallery
-========
+=======
 
 This page contains short examples showcasing the functionality of |igraph|:
 
@@ -16,6 +16,8 @@ This page contains short examples showcasing the functionality of |igraph|:
  - :ref:`tutorials-maxflow`
  - :ref:`tutorials-shortest-paths`
  - :ref:`tutorials-cliques`
+ - :ref:`tutorials-configuration`
+ - :ref:`tutorials-visual-style`
  - :ref:`tutorials-online-user-actions`
  - :ref:`tutorials-visualize-communities`
 
@@ -32,5 +34,7 @@ This page contains short examples showcasing the functionality of |igraph|:
    tutorials/ring_animation/ring_animation
    tutorials/shortest_paths/shortest_paths
    tutorials/visualize_cliques/visualize_cliques
+   tutorials/configuration/configuration
+   tutorials/visual_style/visual_style
    tutorials/online_user_actions/online_user_actions
    tutorials/visualize_communities/visualize_communities

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

@@ -0,0 +1,25 @@
+import igraph as ig
+import matplotlib.pyplot as plt
+import math
+import random
+
+# Get the configuration instance
+config = ig.Configuration().instance()
+
+# Set configuration variables
+config["general.verbose"] = True
+config["plotting.backend"] = "matplotlib"
+config["plotting.layout"] = "fruchterman_reingold"
+config["plotting.palette"] = "heat"
+
+# Generate a graph
+random.seed(1)
+g = ig.Graph.Barabasi(n=100, m=1)
+
+# Calculate colors between 0-255 for all nodes
+betweenness = g.betweenness()
+colors = [math.floor(i * 255 / 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, ``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
+
+    # Get the configuration instance
+    config = ig.Configuration().instance()
+
+    # Set configuration variables
+    config["general.verbose"] = True
+    config["plotting.backend"] = "matplotlib"
+    config["plotting.layout"] = "fruchterman_reingold"
+    config["plotting.palette"] = "rainbow"
+
+    # Save configuration to ~/.igraphrc
+    config.save()
+
+This script only needs to be run once, and can then be deleted. Afterwards any time you use |igraph|, it will read the config from the saved file and use them as the 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::
+    
+    - Note that you  can specify your own location by passing in a filepath to ``config.save``, e.g. ``config.save("./path/to/config/file")``. You can then load it later using ``ig.Configuration().instance().load("./path/to/config/file")``
+    - If you want an efficient way to set the visual style between individual graphs (such as 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`