.. _cn_tut:

Basic connectivity analyses
+++++++++++++++++++++++++++

Getting connectivity information for a set of neurons is pretty straight forward. You can get connectivity tables, edges between neurons, connectors between neurons. Make sure to check out the :ref:`API <api_con>`.

In this example, we will focus on fetching and visualising basic connectivity data. Check out the advanced tutorial for e.g. compartmentalizing connectivity.

.. code:: ipython3

    import pymaid
    
    # Initialize connection
    rm = pymaid.connect_catmaid()



.. raw:: html

    <script type="text/javascript">
    window.PlotlyConfig = {MathJaxConfig: 'local'};
    if (window.MathJax) {MathJax.Hub.Config({SVG: {font: "STIX-Web"}});}
    if (typeof require !== 'undefined') {
    require.undef("plotly");
    requirejs.config({
        paths: {
            'plotly': ['https://cdn.plot.ly/plotly-latest.min']
        }
    });
    require(['plotly'], function(Plotly) {
        window._Plotly = Plotly;
    });
    }
    </script>



.. parsed-literal::

    INFO  : Global CATMAID instance set. Caching is ON. (pymaid)


Let's start by fetching a connectivity table for some olfactory projection neurons:

.. code:: ipython3

    pns = pymaid.get_skids_by_annotation('glomerulus DA1 right excitatory')
    
    cn_table = pymaid.get_partners(pns)
    cn_table.head()


.. parsed-literal::

    INFO  : Fetching connectivity table for 8 neurons (pymaid)
    INFO  : Done. Found 134 pre-, 710 postsynaptic and 0 gap junction-connected neurons (pymaid)




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>neuron_name</th>
          <th>skeleton_id</th>
          <th>num_nodes</th>
          <th>relation</th>
          <th>2863104</th>
          <th>57381</th>
          <th>61221</th>
          <th>57353</th>
          <th>57323</th>
          <th>755022</th>
          <th>27295</th>
          <th>57311</th>
          <th>total</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>AV4 [LH.R] 1803749 CH RJVR Vegito - check</td>
          <td>1803748</td>
          <td>6394</td>
          <td>upstream</td>
          <td>10</td>
          <td>3</td>
          <td>8</td>
          <td>4</td>
          <td>21</td>
          <td>17</td>
          <td>7</td>
          <td>8</td>
          <td>78.0</td>
        </tr>
        <tr>
          <th>1</th>
          <td>LHAV4a4#2 1853424 Accursed RJVR - check FML</td>
          <td>1853423</td>
          <td>10266</td>
          <td>upstream</td>
          <td>7</td>
          <td>6</td>
          <td>6</td>
          <td>4</td>
          <td>12</td>
          <td>18</td>
          <td>6</td>
          <td>8</td>
          <td>67.0</td>
        </tr>
        <tr>
          <th>2</th>
          <td>AV4 [LH.R] 1095415 ARH RJVR Static</td>
          <td>1095414</td>
          <td>3983</td>
          <td>upstream</td>
          <td>5</td>
          <td>2</td>
          <td>9</td>
          <td>1</td>
          <td>9</td>
          <td>16</td>
          <td>12</td>
          <td>9</td>
          <td>63.0</td>
        </tr>
        <tr>
          <th>3</th>
          <td>LHAV4a4#1 1911125 FML PS RJVR</td>
          <td>1911124</td>
          <td>6969</td>
          <td>upstream</td>
          <td>8</td>
          <td>0</td>
          <td>4</td>
          <td>2</td>
          <td>4</td>
          <td>4</td>
          <td>7</td>
          <td>3</td>
          <td>32.0</td>
        </tr>
        <tr>
          <th>4</th>
          <td>APL 203841 MR JSL</td>
          <td>203840</td>
          <td>144725</td>
          <td>upstream</td>
          <td>4</td>
          <td>0</td>
          <td>6</td>
          <td>2</td>
          <td>2</td>
          <td>3</td>
          <td>2</td>
          <td>4</td>
          <td>23.0</td>
        </tr>
      </tbody>
    </table>
    </div>



This table is similar to the connectivity table in CATMAID: each number-column (e.g. ``755022``) represents connections from/to the neuron with that skeleton ID.

Since this is a pandas DataFrame, we can work pandas magic to subset it:

.. code:: ipython3

    downstream_only = cn_table[cn_table.relation == 'downstream']
    
    strong_only = cn_table[cn_table.total >= 10]
    
    large_only = cn_table[cn_table.num_nodes >= 2000]
    
    connected_to_all = cn_table[cn_table[['755022', '2863104', '27295', '61221', '57353', '57323', '57381', '57311']].min(axis=1) != 0]

Make sure to also check out :func:`pymaid.get_partners` documenation too.

Quick visualizations
====================

As example for a quick visualization, we will use the excellent library `seaborn <http://seaborn.pydata.org/>`_ to plot a heatmap of an adjacency matrix.

First, get the adjacency matrix between our projection neurons and their strong downstream partners:

.. code:: ipython3

    adj_mat = pymaid.adjacency_matrix(pns, downstream_only[downstream_only.total >= 10])
    adj_mat.head()




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th>targets</th>
          <th>1811442</th>
          <th>1911124</th>
          <th>1870230</th>
          <th>1803748</th>
          <th>488055</th>
          <th>1853423</th>
          <th>6762450</th>
          <th>1812558</th>
          <th>1095414</th>
          <th>1796364</th>
          <th>...</th>
          <th>1812057</th>
          <th>9719560</th>
          <th>60445</th>
          <th>1415926</th>
          <th>9271871</th>
          <th>424553</th>
          <th>3828811</th>
          <th>10331589</th>
          <th>4205169</th>
          <th>55153</th>
        </tr>
        <tr>
          <th>sources</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>2863104</th>
          <td>30.0</td>
          <td>23.0</td>
          <td>5.0</td>
          <td>15.0</td>
          <td>15.0</td>
          <td>12.0</td>
          <td>18.0</td>
          <td>6.0</td>
          <td>8.0</td>
          <td>0.0</td>
          <td>...</td>
          <td>1.0</td>
          <td>0.0</td>
          <td>2.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>10.0</td>
          <td>10.0</td>
        </tr>
        <tr>
          <th>57381</th>
          <td>4.0</td>
          <td>9.0</td>
          <td>28.0</td>
          <td>7.0</td>
          <td>0.0</td>
          <td>3.0</td>
          <td>0.0</td>
          <td>3.0</td>
          <td>1.0</td>
          <td>36.0</td>
          <td>...</td>
          <td>1.0</td>
          <td>0.0</td>
          <td>1.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>10.0</td>
          <td>0.0</td>
          <td>0.0</td>
        </tr>
        <tr>
          <th>61221</th>
          <td>26.0</td>
          <td>13.0</td>
          <td>7.0</td>
          <td>13.0</td>
          <td>15.0</td>
          <td>15.0</td>
          <td>4.0</td>
          <td>4.0</td>
          <td>16.0</td>
          <td>0.0</td>
          <td>...</td>
          <td>1.0</td>
          <td>0.0</td>
          <td>1.0</td>
          <td>1.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
        </tr>
        <tr>
          <th>57353</th>
          <td>3.0</td>
          <td>6.0</td>
          <td>23.0</td>
          <td>3.0</td>
          <td>3.0</td>
          <td>5.0</td>
          <td>4.0</td>
          <td>5.0</td>
          <td>5.0</td>
          <td>0.0</td>
          <td>...</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>5.0</td>
          <td>0.0</td>
          <td>10.0</td>
          <td>10.0</td>
          <td>10.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
        </tr>
        <tr>
          <th>57323</th>
          <td>20.0</td>
          <td>15.0</td>
          <td>7.0</td>
          <td>22.0</td>
          <td>11.0</td>
          <td>19.0</td>
          <td>15.0</td>
          <td>18.0</td>
          <td>9.0</td>
          <td>26.0</td>
          <td>...</td>
          <td>3.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>2.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
          <td>0.0</td>
        </tr>
      </tbody>
    </table>
    <p>5 rows × 176 columns</p>
    </div>



Now we will use seaborn's `clustermap <https://seaborn.pydata.org/generated/seaborn.clustermap.html>`_ to visualize this adjacency matrix:

.. code:: ipython3

    import seaborn as sns
    import matplotlib.pyplot as plt
    
    cm = sns.clustermap(adj_mat,
                        cmap='Greys')
    
    plt.show()



.. image:: connectivity_basics_files/connectivity_basics_9_0.png


Network analyses
================
``pymaid`` and ``navis`` come with a few tools to analyse connectivity, like :func:`navis:navis.cluster_by_connectivity` or :func:`pymaid.predict_connectivity`. If you are looking to run some proper network analyses, there is no need to reinvent the wheel though: `networkX <https://networkx.github.io/>`_ will most likely do the trick.

.. code:: ipython3

    import networkx as nx
    import navis
    
    # Turn the adjacency matrix into a networkX Graph
    g = navis.network2nx(adj_mat)
    
    # As example: get the degree centrality for each node
    dc = nx.degree_centrality(g)
    print('Node centrality for some of the nodes in the network:', dc[755022], dc[2863104], dc[27295])


.. parsed-literal::

    Node centrality for some of the nodes in the network: 0.9617486338797814 0.9617486338797814 0.9617486338797814


Have a look at the available `algorithms <https://networkx.github.io/documentation/stable/reference/algorithms/index.html>`_ in networkX.

Exporting connectivity
======================

There are several excellent tools out there to visualize and analyze connectivity graphs outside of the Python ecosystem. Here, we will demonstrate how to export connectivity to formats that you can import somewhere else.

We can use ``g``, the networkX Graph we created above, to export the graph to all kinds of different `formats <https://networkx.github.io/documentation/stable/reference/readwrite/index.html>`_. 

For demonstration, let's export to the GraphML format which is widely used.

.. code:: ipython3

    nx.write_graphml(g, 'graph.graphml')