.. _neuronlist_math:

NeuronList math
***************
:class:`~pymaid.CatmaidNeuronList` implement some of the basic arithmetic and comparison operators that you might know from standard ``lists`` or ``numpy.arrays``. Most this should be fairly intuitive (I hope) but there are a few things you should be aware of. The following examples will illustrate that:

As per usual, we need to get some neurons first (I'm assuming you've already imported and setup pymaid):

.. code:: ipython3

    nl = pymaid.get_neurons('annotation:glomerulus DA1 right')
    nl.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></th>
          <th>neuron_name</th>
          <th>skeleton_id</th>
          <th>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branch_nodes</th>
          <th>n_end_nodes</th>
          <th>open_ends</th>
          <th>cable_length</th>
          <th>review_status</th>
          <th>soma</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>PN glomerulus DA1 57316 ML 2863105</td>
          <td>2863104</td>
          <td>5222</td>
          <td>439</td>
          <td>149</td>
          <td>157</td>
          <td>63</td>
          <td>1109.886700</td>
          <td>NA</td>
          <td>True</td>
        </tr>
        <tr>
          <th>1</th>
          <td>PN glomerulus DA1 57382 ML</td>
          <td>57381</td>
          <td>7730</td>
          <td>360</td>
          <td>153</td>
          <td>162</td>
          <td>71</td>
          <td>1215.920600</td>
          <td>NA</td>
          <td>True</td>
        </tr>
        <tr>
          <th>2</th>
          <td>PN glomerulus DA1 61222 AJ</td>
          <td>61221</td>
          <td>7875</td>
          <td>534</td>
          <td>135</td>
          <td>140</td>
          <td>26</td>
          <td>1182.642823</td>
          <td>NA</td>
          <td>True</td>
        </tr>
        <tr>
          <th>3</th>
          <td>PN glomerulus DA1 57354 GA</td>
          <td>57353</td>
          <td>4898</td>
          <td>327</td>
          <td>90</td>
          <td>95</td>
          <td>52</td>
          <td>1113.156682</td>
          <td>NA</td>
          <td>True</td>
        </tr>
        <tr>
          <th>4</th>
          <td>PN glomerulus DA1 57324 LK JSL</td>
          <td>57323</td>
          <td>4585</td>
          <td>438</td>
          <td>120</td>
          <td>127</td>
          <td>59</td>
          <td>1035.099284</td>
          <td>NA</td>
          <td>True</td>
        </tr>
      </tbody>
    </table>
    </div>



Comparisons
-----------
The ``==`` operator compares two elements:

.. code:: ipython3

    1 == 1




.. parsed-literal::

    True



.. code:: ipython3

    2 == 1




.. parsed-literal::

    False



For :class:`~pymaid.CatmaidNeuron` this is done by comparing the neurons' morphologies (somas, root nodes, cable length, ...) and meta data (skeleton ID, name, ...).

.. code:: ipython3

    n1 = nl[0]
    n2 = nl[0]
    n1 == n2




.. parsed-literal::

    True



.. code:: ipython3

    n1 = nl[0]
    n2 = nl[1]
    n1 == n2




.. parsed-literal::

    False



For :class:`~pymaid.CatmaidNeuronList`, we do the same comparison pairwise between neurons in both neuronlists - so order matters!.

.. code:: ipython3

    nl == nl




.. parsed-literal::

    True



.. code:: ipython3

    nl == nl[:-1]




.. parsed-literal::

    False



.. code:: ipython3

    nl[[0, 1, 2]] == nl[[2, 1, 0]]




.. parsed-literal::

    False



This is safe against copying but making any changes to the neurons will cause inequality:

.. code:: ipython3

    n1 = nl[0]
    n2 = n1.copy()
    n1 == n2




.. parsed-literal::

    True



.. code:: ipython3

    n1 = nl[0]
    n2 = n1.reroot(nl[0].tags['ends'][0], inplace=False)
    n1 == n2




.. parsed-literal::

    False



You can also ask if a neuron is in a given ``CatmaidNeuronList``:

.. code:: ipython3

    n1 = nl[0]
    n1 in nl




.. parsed-literal::

    True



.. code:: ipython3

    n1 in nl[1:]




.. parsed-literal::

    False



This also works with skeleton IDs

.. code:: ipython3

    n1.skeleton_id in nl




.. parsed-literal::

    True



.. code:: ipython3

    n1.skeleton_id in nl[1:]




.. parsed-literal::

    False



Addition
--------
To merge two lists in Python, you can simply add them:

.. code:: ipython3

    a = [1]
    b = [3]
    a + b




.. parsed-literal::

    [1, 3]



:class:`~pymaid.CatmaidNeuronList` works exactly the same:

.. code:: ipython3

    a = nl[0]
    b = nl[[1, 2]]
    a + b




.. 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>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branch_nodes</th>
          <th>n_end_nodes</th>
          <th>open_ends</th>
          <th>cable_length</th>
          <th>review_status</th>
          <th>soma</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>PN glomerulus DA1 57382 ML</td>
          <td>57381</td>
          <td>7729</td>
          <td>360</td>
          <td>153</td>
          <td>162</td>
          <td>71</td>
          <td>1215.920599</td>
          <td>NA</td>
          <td>True</td>
        </tr>
        <tr>
          <th>1</th>
          <td>AL.L(DA1) -{mALT}-&gt; CAL.L-LH.L 2379518 PN022 D...</td>
          <td>2379517</td>
          <td>4657</td>
          <td>411</td>
          <td>86</td>
          <td>90</td>
          <td>31</td>
          <td>836.067253</td>
          <td>NA</td>
          <td>True</td>
        </tr>
        <tr>
          <th>2</th>
          <td>PN glomerulus DA1 57312 LK</td>
          <td>57311</td>
          <td>4882</td>
          <td>429</td>
          <td>157</td>
          <td>164</td>
          <td>105</td>
          <td>1182.102458</td>
          <td>NA</td>
          <td>True</td>
        </tr>
      </tbody>
    </table>
    </div>



This also works on with two single :class:`~pymaid.CatmaidNeuron`! You can use that to combine them into a list:

.. code:: ipython3

    a = nl[0]
    b = nl[1]
    a + b




.. 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>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branch_nodes</th>
          <th>n_end_nodes</th>
          <th>open_ends</th>
          <th>cable_length</th>
          <th>review_status</th>
          <th>soma</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>PN glomerulus DA1 57316 ML 2863105</td>
          <td>2863104</td>
          <td>5222</td>
          <td>439</td>
          <td>149</td>
          <td>157</td>
          <td>63</td>
          <td>1109.88670</td>
          <td>NA</td>
          <td>True</td>
        </tr>
        <tr>
          <th>1</th>
          <td>AL.L(DA1) -{mALT}-&gt; CAL.L-LH.L 2319458 PN036 D...</td>
          <td>2319457</td>
          <td>10209</td>
          <td>964</td>
          <td>431</td>
          <td>458</td>
          <td>90</td>
          <td>1747.51171</td>
          <td>NA</td>
          <td>True</td>
        </tr>
      </tbody>
    </table>
    </div>



.. note::
   If you want to combine two CatmaidNeurons into a single neuron instead of creating a neuronlist, check out :func:`pymaid.stitch_neurons`.

Substraction
------------
To remove an item from a Python list, you would call the ``.pop()`` method:

.. code:: ipython3

    a = [1, 2, 3]
    b = 2
    a.pop(b)
    a




.. parsed-literal::

    [1, 2]



:class:`~pymaid.CatmaidNeuronList` lets you simply use substraction:

.. code:: ipython3

    a = nl[[0, 1, 2]]
    b = nl[2]
    a - b




.. 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>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branch_nodes</th>
          <th>n_end_nodes</th>
          <th>open_ends</th>
          <th>cable_length</th>
          <th>review_status</th>
          <th>soma</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>PN glomerulus DA1 57382 ML</td>
          <td>57381</td>
          <td>7729</td>
          <td>360</td>
          <td>153</td>
          <td>162</td>
          <td>71</td>
          <td>1215.920599</td>
          <td>NA</td>
          <td>True</td>
        </tr>
        <tr>
          <th>1</th>
          <td>AL.L(DA1) -{mALT}-&gt; CAL.L-LH.L 2379518 PN022 D...</td>
          <td>2379517</td>
          <td>4657</td>
          <td>411</td>
          <td>86</td>
          <td>90</td>
          <td>31</td>
          <td>836.067253</td>
          <td>NA</td>
          <td>True</td>
        </tr>
      </tbody>
    </table>
    </div>



Bitwise AND
-----------
To find the intersection between two lists, you would use ``sets`` and the ``&`` operator:

.. code:: ipython3

    a = set([0, 1, 2])
    b = set([2, 3, 4])
    a & b




.. parsed-literal::

    {2}



:class:`~pymaid.CatmaidNeuronList` work similarly:

.. code:: ipython3

    a = nl[[0, 1, 2]]
    b = nl[[2, 3, 4]]
    a & b




.. 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>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branch_nodes</th>
          <th>n_end_nodes</th>
          <th>open_ends</th>
          <th>cable_length</th>
          <th>review_status</th>
          <th>soma</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>PN glomerulus DA1 57312 LK</td>
          <td>57311</td>
          <td>4882</td>
          <td>429</td>
          <td>157</td>
          <td>164</td>
          <td>105</td>
          <td>1182.102458</td>
          <td>NA</td>
          <td>True</td>
        </tr>
      </tbody>
    </table>
    </div>



All of the above also work with skeleton IDs as one of the operators

.. code:: ipython3

    a = nl[[0, 1, 2]]
    b = nl[[2, 3, 4]]
    a & b.skeleton_id




.. 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>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branch_nodes</th>
          <th>n_end_nodes</th>
          <th>open_ends</th>
          <th>cable_length</th>
          <th>review_status</th>
          <th>soma</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>PN glomerulus DA1 57312 LK</td>
          <td>57311</td>
          <td>4882</td>
          <td>429</td>
          <td>157</td>
          <td>164</td>
          <td>105</td>
          <td>1182.102458</td>
          <td>NA</td>
          <td>True</td>
        </tr>
      </tbody>
    </table>
    </div>



Multiplication and Division
---------------------------
So far, all operations have led to changes in the structure of the :class:`~pymaid.CatmaidNeuronList`. Multiplication and division are **different**! If you multiply/divide a :class:`~pymaid.CatmaidNeuron` or :class:`~pymaid.CatmaidNeuronList` by a number, you will change the *coordinates* of nodes and connectors (plus node radii):

.. code:: ipython3

    n = nl[0]
    n.nodes.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></th>
          <th>treenode_id</th>
          <th>parent_id</th>
          <th>creator_id</th>
          <th>x</th>
          <th>y</th>
          <th>z</th>
          <th>radius</th>
          <th>confidence</th>
          <th>type</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>3046710</td>
          <td>32963981</td>
          <td>53</td>
          <td>442883</td>
          <td>212802</td>
          <td>44240</td>
          <td>-1</td>
          <td>5</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>1</th>
          <td>32963981</td>
          <td>3046707</td>
          <td>150</td>
          <td>442931</td>
          <td>212892</td>
          <td>44040</td>
          <td>-1</td>
          <td>5</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>2</th>
          <td>652935</td>
          <td>652934</td>
          <td>22</td>
          <td>444126</td>
          <td>151826</td>
          <td>216240</td>
          <td>-1</td>
          <td>5</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>3</th>
          <td>3245741</td>
          <td>3245737</td>
          <td>61</td>
          <td>414617</td>
          <td>243177</td>
          <td>52400</td>
          <td>3451</td>
          <td>5</td>
          <td>end</td>
        </tr>
        <tr>
          <th>4</th>
          <td>3042776</td>
          <td>27298300</td>
          <td>53</td>
          <td>436753</td>
          <td>225519</td>
          <td>38000</td>
          <td>-1</td>
          <td>5</td>
          <td>slab</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    n2 = n / 1000
    n2.nodes.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></th>
          <th>treenode_id</th>
          <th>parent_id</th>
          <th>creator_id</th>
          <th>x</th>
          <th>y</th>
          <th>z</th>
          <th>radius</th>
          <th>confidence</th>
          <th>type</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>3046710</td>
          <td>32963981</td>
          <td>53</td>
          <td>442.883</td>
          <td>212.802</td>
          <td>44.24</td>
          <td>-0.001</td>
          <td>5</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>1</th>
          <td>32963981</td>
          <td>3046707</td>
          <td>150</td>
          <td>442.931</td>
          <td>212.892</td>
          <td>44.04</td>
          <td>-0.001</td>
          <td>5</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>2</th>
          <td>652935</td>
          <td>652934</td>
          <td>22</td>
          <td>444.126</td>
          <td>151.826</td>
          <td>216.24</td>
          <td>-0.001</td>
          <td>5</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>3</th>
          <td>3245741</td>
          <td>3245737</td>
          <td>61</td>
          <td>414.617</td>
          <td>243.177</td>
          <td>52.40</td>
          <td>3.451</td>
          <td>5</td>
          <td>end</td>
        </tr>
        <tr>
          <th>4</th>
          <td>3042776</td>
          <td>27298300</td>
          <td>53</td>
          <td>436.753</td>
          <td>225.519</td>
          <td>38.00</td>
          <td>-0.001</td>
          <td>5</td>
          <td>slab</td>
        </tr>
      </tbody>
    </table>
    </div>



The main use of this is to convert units from e.g. nm to um.

Dealing with unequal neuron objects
-----------------------------------

As we demonstrated earlier, making changes to ``CatmaidNeuron/Lists`` will cause comparisons to fail. This also propagates into substractions and bitwise comparisons:

.. code:: ipython3

    n1 = nl[0]
    n1 in nl




.. parsed-literal::

    True



.. code:: ipython3

    n2 = n1.reroot(nl[0].tags['ends'][0], inplace=False)
    n2 in nl




.. parsed-literal::

    False



.. code:: ipython3

    nl & n1




.. 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>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branch_nodes</th>
          <th>n_end_nodes</th>
          <th>open_ends</th>
          <th>cable_length</th>
          <th>review_status</th>
          <th>soma</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>PN glomerulus DA1 57316 ML 2863105</td>
          <td>2863104</td>
          <td>5222</td>
          <td>439</td>
          <td>149</td>
          <td>157</td>
          <td>63</td>
          <td>1109.8867</td>
          <td>NA</td>
          <td>True</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    nl & n2


.. parsed-literal::

    WARNING : Skeleton IDs overlap but neuron not identical! Bitwise cancelled! Try using .skeleton_id instead. (pymaid)


See how the comparison fails because we've made changes? The same happens if you tried ``nl - n2``. 

As mentioned in the warning, the workaround is to use the skeleton ID instead:

.. code:: ipython3

    n2.skeleton_id in nl




.. parsed-literal::

    True



.. code:: ipython3

    nl & n2.skeleton_id




.. 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>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branch_nodes</th>
          <th>n_end_nodes</th>
          <th>open_ends</th>
          <th>cable_length</th>
          <th>review_status</th>
          <th>soma</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>PN glomerulus DA1 57316 ML 2863105</td>
          <td>2863104</td>
          <td>5222</td>
          <td>439</td>
          <td>149</td>
          <td>157</td>
          <td>63</td>
          <td>1109.8867</td>
          <td>NA</td>
          <td>True</td>
        </tr>
      </tbody>
    </table>
    </div>