cm tutorial

CHANGELOG.md

@@ -5,10 +5,12 @@
 ## Added 
 - Added cm_boundary for connectivity matrixes (wiheto) 
 - Some new gallery examples for connectivity matrices (wiheto)
+- connectivity matrix tutorial (wiheto)
 
 ## Fixed
 - cm_rotate now works when False (wiheto)
 - added dpi to svg export for improved rasterized image resolution (wiheto)
+- minor improvements and fixes to cm_plot (wiheto)
 
 ## [0.3.0]
 

docs/tutorial.md

@@ -3,3 +3,5 @@
 [Tutorial 1: input data](./tutorial1_input/) - In this tutorial, learn about how to specify nodes, edges and templates in different ways. 
 
 [Tutorial 2: viewing angles](./tutorial2_views/) - In this tutorial, learn about different ways to specify viewing angles.
+
+[Tutorial 3: connectivity matrix](./tutorial3_connectivitymatrix/) - In this tutorial, learn how to plot connectivity matrices in your figures and edit them. 

docs/tutorial/tutorial3_connectivitymatrix.py

@@ -0,0 +1,115 @@
+# + [markdown]
+"""
+# Tutorial 3: The connectivity matrix 
+
+Viewing the connectivity matrix is another way of examining the networks within the brain, complementing other methods. 
+
+In these visualizations a node x node matrix shows the connectivity values. 
+
+To view a connectivity matrix for your nextwork, simply set a view argument to "c".
+
+NetPlotBrain enables you to effortlessly generate a connectivity matrix alongside the brain, along with a few extra features.
+"""
+
+# + [markdown]
+""" 
+## Generating data
+
+So let us generate some normally distributed data to use as our connectivity matrix.
+"""
+
+# + 
+import numpy as np
+import itertools
+import pandas as pd
+import netplotbrain
+
+# +
+mu = np.zeros(30)
+sigma = np.eye(30)
+# Set within network connectivity
+i, j = list(zip(*itertools.combinations(np.arange(0, 10), 2)))
+sigma[i, j] = 0.7
+i, j = list(zip(*itertools.combinations(np.arange(10, 20), 2)))
+sigma[i, j] = 0.7
+i, j = list(zip(*itertools.combinations(np.arange(20, 30), 2)))
+sigma[i, j] = 0.6
+# Set between network connectivity
+sigma[20:][:, :20] = -0.2
+sigma[10:20][:, :10] = 0.1
+sigma = sigma + sigma.T
+np.fill_diagonal(sigma, 1)
+# Generate the random data
+np.random.seed(42)
+data = np.random.multivariate_normal(mu, sigma, 1000)
+
+# + 
+# Create connectivity matrix
+cm = pd.DataFrame(data).corr().values
+# Here we see we have created a 30 x 30 matrix
+cm.shape
+
+# +
+# Plot the connectivity matrix
+netplotbrain.plot(edges=cm,
+                  view='c')
+
+# + [markdown]
+""" 
+## Shuffling up the order
+
+Now multiple different options can be specified.
+One such opttion is the order of the nodes. Here the nodes are already ordered, but this is not always the case.
+"""
+random_order = np.random.permutation(np.arange(30))
+cm = cm[random_order][:, random_order]
+netplotbrain.plot(edges=cm, view='c')
+
+## + [markdown]
+# ### cm_order can set the order of nodes. 
+
+# + 
+# cm_order is either a list of indicies or a list of communities
+cm_order = np.argsort(random_order)
+netplotbrain.plot(edges=cm, view='c', 
+                  cm_order=cm_order)
+
+## + [markdown]
+# ### Turning of the rotated option
+
+# + 
+netplotbrain.plot(edges=cm, view='c', 
+                  cm_order=cm_order, 
+                  cm_rotate=False)
+
+## + [markdown]
+# ### ringing in the community with node_color. 
+
+# + 
+# Lets put cm back in its correct order
+cm = cm[cm_order][:, cm_order]
+
+# Load example nodes, take only xyz and first 30 rows
+nodes = pd.read_csv(netplotbrain.__path__[0] + '/example_data/example_nodes.tsv', sep='\t', index_col=0)
+nodes = nodes[['x', 'y', 'z']].iloc[:30]
+# Add new community names
+nodes['community_names'] = ['FP']*10 + ['SM']*10 + ['DMN']*10
+
+# + 
+netplotbrain.plot(edges=cm, view='Sc', 
+                  nodes=nodes, node_color='community_names', 
+                  node_scale=50,
+                  node_cmap='Set2',
+                  title='Brain and connectivity mastrix sharing colors',
+                  subtitles=None,
+                  cm_boundarywidth=4,
+                  cm_bordercolor = 'black',
+                  cm_borderwidth = 2,
+                  edge_color='lightgray',
+                  edge_wights=0.1)
+
+# + [markdown]
+""" 
+The above plot also shows the cm_boundarywidth argument which plots the width of the squares associated with node_color.
+It also show cm_borderwidth and cm_bordercolor which are the outside boundaries. 
+"""

netplotbrain/__version.py

@@ -1 +1 @@
-__version__ = "0.3.1a"
+__version__ = "0.3.1b"

netplotbrain/plotting/plot_cm.py

@@ -12,7 +12,7 @@ def _plot_connectivitymatrix(ax, edges, nodes=None, node_color=None, node_colorb
 
     # Dataframe to array
     if isinstance(nodes, pd.DataFrame):
-        number_of_nodes=len(nodes)+1
+        number_of_nodes=len(nodes)
     else:
         number_of_nodes=edges[['i', 'j']].max().max()+1
 
@@ -29,13 +29,22 @@ def _plot_connectivitymatrix(ax, edges, nodes=None, node_color=None, node_colorb
     #    cm_boundarycolor = 'black'
     #else:
     #    cm_boundarycolor = None
+    # Set cm_order to node_colorby if it is set to auto and node_color is set
+    if cm_order == 'auto' and node_colorby is not None:
+        cm_order = node_colorby
+        if cm_boundary == 'auto': 
+            cm_boundary = True
+    elif cm_order == 'auto':
+        cm_order = None
     if cm_order is not None:
-        if cm_order == 'auto' and node_colorby is not None:
-            cm_order = node_colorby
-            if cm_boundary == 'auto': 
-                cm_boundary = True
-        communities = nodes[cm_order].astype('category').cat.codes.values
-        nodeorder = np.argsort(communities)
+        # Check if cm_order consists of unqiue indicies or are communities/groups
+        if len(np.unique(cm_order))==len(cm_order):
+            nodeorder = cm_order
+        else:
+            communities = nodes[cm_order].astype('category').cat.codes.values
+            nodeorder = np.argsort(communities)
+    else:
+        nodeorder = np.arange(number_of_nodes)
     # If it is still set to auto, set ot None
     if cm_boundary == 'auto':
         cm_boundary = None
@@ -60,15 +69,15 @@ def _plot_connectivitymatrix(ax, edges, nodes=None, node_color=None, node_colorb
 
     # Plot
     # Add squares for different communities to the connectivity plot
+    if cm_border:            
+        ax.plot([0, 0], [0, number_of_nodes], color=cm_bordercolor, linewidth=cm_borderwidth, transform=tr,zorder=5)
+        ax.plot([number_of_nodes, 0], [number_of_nodes, number_of_nodes], color=cm_bordercolor, linewidth=cm_borderwidth, transform=tr,zorder=5)
+        ax.plot([0, number_of_nodes], [0, 0], color=cm_bordercolor, linewidth=cm_borderwidth, transform=tr,zorder=5)
+        ax.plot([number_of_nodes, number_of_nodes], [0, number_of_nodes], color=cm_bordercolor, linewidth=cm_borderwidth, transform=tr,zorder=5)
     if cm_boundary:
         for coms in np.unique(communities):
             no = np.where(communities[nodeorder] == coms)[0]
             ax.plot([no[0], no[0]], [no[0], no[-1]+1], color=node_color[nodeorder[no[0]]], linewidth=cm_boundarywidth, transform=tr,zorder=10)
             ax.plot([no[-1]+1, no[0]], [no[-1]+1, no[-1]+1], color=node_color[nodeorder[no[0]]], linewidth=cm_boundarywidth, transform=tr,zorder=10)
             ax.plot([no[0], no[-1]+1], [no[0], no[0]], color=node_color[nodeorder[no[0]]], linewidth=cm_boundarywidth, transform=tr,zorder=10)
             ax.plot([no[-1]+1, no[-1]+1], [no[0], no[-1]+1], color=node_color[nodeorder[no[0]]], linewidth=cm_boundarywidth, transform=tr,zorder=10)
-    if cm_border:            
-        ax.plot([0, 0], [0, len(nodes)], color=cm_bordercolor, linewidth=cm_borderwidth, transform=tr,zorder=5)
-        ax.plot([len(nodes), 0], [len(nodes), len(nodes)], color=cm_bordercolor, linewidth=cm_borderwidth, transform=tr,zorder=5)
-        ax.plot([0, len(nodes)], [0, 0], color=cm_bordercolor, linewidth=cm_borderwidth, transform=tr,zorder=5)
-        ax.plot([len(nodes), len(nodes)], [0, len(nodes)], color=cm_bordercolor, linewidth=cm_borderwidth, transform=tr,zorder=150)