.. _rmaid_link:

R and the nat libraries
-----------------------

NAVis is inspired by the excellent `nat <http://jefferislab.github.io>`_ 
(NeuroAnatomy Toolbox) ecosystem by `Greg Jefferis <https://github.com/jefferis>`_ .
While there is parity in major features between the navis ecosystem and the "`natverse`",
it can sometimes be useful to access R functions directly.

Fortunately, Python and R play very nicely together - see this brilliant `blog post <https://blog.jupyter.org/i-python-you-r-we-julia-baf064ca1fb6>`_. Hence, NAVis has functions for converting from/to ``nat`` datatypes and basic wrappers for some of the most useful ``nat`` functions. This section will teach you the basics of how to use R and NAVis. But first, we have to make sure you are all set:

Setting up
==========

Using R from within Python requires `rpy2 <https://rpy2.readthedocs.io>`_.
`rpy2 <https://rpy2.readthedocs.io>`_ is **not** automatically installed
alongside NAVis. That's because it fails to install if R is not already
present on your system. Here is what you need to do:

.. raw:: html

    <ol type="1">
      <li>
        <strong>Install R</strong>.<br>
        You can either install just <a href="https://www.r-project.org">R</a>
        or install it along with <a href="https://www.rstudio.com">R Studio</a>
        (recommended).
      </li>
      <li>
        <strong>Install rpy2</strong><br>
        This should do the trick:
        <pre>pip3 install rpy2</pre>
        Check out rpy2's <a href="https://rpy2.github.io/doc/v2.9.x/html/index.html">documentation</a> if you are running into issues.
      </li>
      <li>
        <strong>Install R packages</strong>.<br>
        NAVis has wrappers for the <a href="http://jefferis.github.io/nat/">nat</a> (NeuroAnatomy Toolbox)
        ecosystem by <a href="https://github.com/jefferis">Greg Jefferis</a>.
        Please make sure to install:
          <ol type="i">
              <li>
                <a href="http://jefferis.github.io/nat/">nat</a> - core package for morphological analysis of neurons
              </li>
              <li>
                <a href="http://jefferislab.github.io/nat.nblast/">nat.nblast</a> - morphological similarity
              </li>
              <li>
                <a href="http://jefferis.github.io/elmr/">elmr</a> - bridging between EM and light level data
              </li>
              <li>
                <a href="http://jefferis.github.io/rcatmaid/">rcatmaid</a> - interface with CATMAID
              </li>
              <li>
                <a href="http://jefferis.github.io/flycircuit/">flycircuit</a> - interface with the
                flycircuit <a href="http://www.flycircuit.tw">database</a> for fly neurons
              </li>
              <li>
                <a href="http://jefferislab.github.io/nat.templatebrains/">nat.templatebrains</a>
                and <a href="http://jefferislab.github.io/nat.flybrains/">nat.flybrains</a>
                - bridging between different light level template brains
              </li>
          </ol>
      </li>
    </ol>


You are ready to go! On a fundamental level, you can now use every single
R function from within Python - check out the rpy2
`documentation <https://rpy2.readthedocs.io>`_.

Quickstart
==========

.. code:: ipython3

    import navis
    
    navis.set_pbars(hide=True, jupyter=False)
    
    from navis.interfaces import r
    
    import matplotlib.pyplot as plt
    
    from rpy2.robjects.packages import importr
    import rpy2.robjects as robjects



.. 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>



Load nat as module

.. code:: ipython3

    nat = importr('nat')

Run one of the nat examples in Python

.. code:: ipython3

    # Get neurons (Drosophila Kenyon cells) shipped with nat
    kcs20 = robjects.r('kcs20')
    
    head = robjects.r('head')
    
    head(kcs20)




.. raw:: html

    
    <span>R/rpy2 DataFrame (6 x 14)</span>
    <table>
      <thead>
        <tr>
    
          <th>gene_name</th>
    
          <th>Name</th>
    
          <th>idid</th>
    
          <th>...</th>
    
          <th>cluster</th>
    
          <th>idx</th>
    
          <th>type</th>
    
        </tr>
      </thead>
      <tbody>
    
      <tr>
    
      <td>
        'FruM...
      </td>
    
      <td>
        'fru-...
      </td>
    
      <td>
        1024.000000
      </td>
    
      <td>
        ...
      </td>
    
      <td>
        9
      </td>
    
      <td>
        156
      </td>
    
      <td>
        gamma
      </td>
    
      </tr>
    
      <tr>
    
      <td>
        'GadM...
      </td>
    
      <td>
        'Gad1...
      </td>
    
      <td>
        10616.000000
      </td>
    
      <td>
        ...
      </td>
    
      <td>
        70
      </td>
    
      <td>
        1,519
      </td>
    
      <td>
        gamma
      </td>
    
      </tr>
    
      <tr>
    
      <td>
        'GadM...
      </td>
    
      <td>
        'Gad1...
      </td>
    
      <td>
        8399.000000
      </td>
    
      <td>
        ...
      </td>
    
      <td>
        57
      </td>
    
      <td>
        1,132
      </td>
    
      <td>
        ab
      </td>
    
      </tr>
    
      <tr>
    
      <td>
        'GadM...
      </td>
    
      <td>
        'Gad1...
      </td>
    
      <td>
        10647.000000
      </td>
    
      <td>
        ...
      </td>
    
      <td>
        71
      </td>
    
      <td>
        1,535
      </td>
    
      <td>
        apbp
      </td>
    
      </tr>
    
      <tr>
    
      <td>
        'FruM...
      </td>
    
      <td>
        'fru-...
      </td>
    
      <td>
        9758.000000
      </td>
    
      <td>
        ...
      </td>
    
      <td>
        64
      </td>
    
      <td>
        1,331
      </td>
    
      <td>
        ab
      </td>
    
      </tr>
    
      <tr>
    
      <td>
        'FruM...
      </td>
    
      <td>
        'fru-...
      </td>
    
      <td>
        6182.000000
      </td>
    
      <td>
        ...
      </td>
    
      <td>
        44
      </td>
    
      <td>
        795
      </td>
    
      <td>
        ab
      </td>
    
      </tr>
    
      </tbody>
    </table>




|
Convert the Kenyon cells to NAVis :class:`~navis.DotProps`

.. code:: ipython3

    kcs20_py = r.dotprops2py(kcs20)
    kcs20_py.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>gene_name</th>
          <th>Name</th>
          <th>idid</th>
          <th>soma_side</th>
          <th>flipped</th>
          <th>Driver</th>
          <th>Gender</th>
          <th>X</th>
          <th>Y</th>
          <th>Z</th>
          <th>exemplar</th>
          <th>cluster</th>
          <th>idx</th>
          <th>type</th>
          <th>points</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>FruMARCM-M001205_seg002</td>
          <td>fru-M-500112</td>
          <td>1024.0</td>
          <td>L</td>
          <td>0</td>
          <td>fru-Gal4</td>
          <td>M</td>
          <td>361.484872</td>
          <td>95.044800</td>
          <td>84.102594</td>
          <td>FruMARCM-M001205_seg002</td>
          <td>9</td>
          <td>156</td>
          <td>gamma</td>
          <td>x           y          z     x_v...</td>
        </tr>
        <tr>
          <th>1</th>
          <td>GadMARCM-F000122_seg001</td>
          <td>Gad1-F-900005</td>
          <td>10616.0</td>
          <td>L</td>
          <td>0</td>
          <td>Gad1-Gal4</td>
          <td>F</td>
          <td>367.833167</td>
          <td>105.867548</td>
          <td>94.734459</td>
          <td>GadMARCM-F000122_seg001</td>
          <td>70</td>
          <td>1519</td>
          <td>gamma</td>
          <td>x           y          z     x_v...</td>
        </tr>
        <tr>
          <th>2</th>
          <td>GadMARCM-F000050_seg001</td>
          <td>Gad1-F-100010</td>
          <td>8399.0</td>
          <td>R</td>
          <td>1</td>
          <td>Gad1-Gal4</td>
          <td>F</td>
          <td>382.827911</td>
          <td>61.732132</td>
          <td>97.280571</td>
          <td>GadMARCM-F000050_seg001</td>
          <td>57</td>
          <td>1132</td>
          <td>ab</td>
          <td>x          y          z     x_ve...</td>
        </tr>
        <tr>
          <th>3</th>
          <td>GadMARCM-F000142_seg002</td>
          <td>Gad1-F-300043</td>
          <td>10647.0</td>
          <td>L</td>
          <td>0</td>
          <td>Gad1-Gal4</td>
          <td>F</td>
          <td>349.591724</td>
          <td>78.189859</td>
          <td>96.692797</td>
          <td>GadMARCM-F000142_seg002</td>
          <td>71</td>
          <td>1535</td>
          <td>apbp</td>
          <td>x          y          z     x_ve...</td>
        </tr>
        <tr>
          <th>4</th>
          <td>FruMARCM-F000270_seg001</td>
          <td>fru-F-400045</td>
          <td>9758.0</td>
          <td>L</td>
          <td>0</td>
          <td>fru-Gal4</td>
          <td>F</td>
          <td>387.523611</td>
          <td>114.803444</td>
          <td>87.841563</td>
          <td>FruMARCM-F000270_seg001</td>
          <td>64</td>
          <td>1331</td>
          <td>ab</td>
          <td>x           y          z     x_v...</td>
        </tr>
      </tbody>
    </table>
    </div>



|
Plot them

.. code:: ipython3

    fig, ax = navis.plot2d(kcs20_py, linewidth=1.5)


.. parsed-literal::

                                                        


.. image:: r_doc_files/r_doc_9_1.png


Data conversion
===============
:mod:`navis.interfaces.r` provides functions to convert data from Python to R:

1. :func:`navis.interfaces.r.data2py` converts general data from R to Python
2. :func:`navis.interfaces.r.neuron2py` converts R neuron or neuronlist objects to Python :class:`navis.TreeNeuron` and :class:`navis.NeuronList`, respectively
3. :func:`navis.interfaces.r.neuron2r` converts :class:`navis.TreeNeuron` or :class:`navis.NeuronList` to R neuron or neuronlist objects
4. :func:`navis.interfaces.r.dotprops2py` converts R dotprop objects to pandas DataFrame that can be passed to :func:`navis.plot.plot3d`

R NBLAST
========
NAVis has a native (i.e. pure Python) implementation of NBLAST (see this :ref:`Tutorial <nblast_intro>`) that matches the one in ``nat``. While I recommend that you use the Python implementation, you can also use the ``nat`` interface to run the R NBLAST:

.. autosummary::
    :toctree: generated/

	navis.interfaces.r.nblast
	navis.interfaces.r.nblast_allbyall
    navis.interfaces.r.NBLASTresults
    
All-by-all nblast
=================
Comparing neurons which are already in the same brain space is straight forward:

.. code:: ipython3

    nl = navis.example_neurons()
    
    # Note that we are converting to microns as NBLAST is optimized for that resolution
    nbl = r.nblast_allbyall(nl, micron_conversion=1/1000, resample=1)

.. code:: ipython3

    fig = nbl.plot_matrix()


.. parsed-literal::

    INFO  : Use matplotlib.pyplot.show() to render figure. (navis)



.. image:: r_doc_files/r_doc_12_1.png


NBLAST against databases
========================
In this example we will nblast one of our example *Drosophila* neurons against the flycircuit database of single cell clones.

This is a two step process in which the neuron is first transformed from it's original brain space (``FAFB14``) into the flycircuit template space (``FCWB``) and then blasted against the entire database of skeletonized flycircuit clones.

This requires you to have the R `flycircuit <https://github.com/jefferis/flycircuit>`_ and `nat.templatebrains <https://github.com/jefferis/nat.templatebrains>`_ packages installed.

.. code:: ipython3

    n = navis.example_neurons(1)
    
    # Get the flycircuit database
    datadir = robjects.r('getOption("flycircuit.datadir")')[0]
    fc = robjects.r(f'read.neuronlistfh("{datadir}/dpscanon.rds")')
    
    nbl = r.nblast(n, db=fc, xform='FAFB14->FCWB', resample=1, mirror=True)


.. parsed-literal::

    INFO  : Blasting neuron... (navis)
    INFO  : Blasting done in 67.3 seconds (navis)


|
Show the top results

.. code:: ipython3

    nbl.results.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>gene_name</th>
          <th>forward_score</th>
          <th>reverse_score</th>
          <th>mu_score</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>DvGlutMARCM-F002430_seg001</td>
          <td>0.614162</td>
          <td>0.632155</td>
          <td>0.623158</td>
        </tr>
        <tr>
          <th>1</th>
          <td>FruMARCM-M002373_seg002</td>
          <td>0.603885</td>
          <td>0.681603</td>
          <td>0.642744</td>
        </tr>
        <tr>
          <th>2</th>
          <td>dTdc2MARCM-F000115_seg001</td>
          <td>0.588686</td>
          <td>-0.498178</td>
          <td>0.045254</td>
        </tr>
        <tr>
          <th>3</th>
          <td>ChaMARCM-F000725_seg001</td>
          <td>0.566431</td>
          <td>0.676217</td>
          <td>0.621324</td>
        </tr>
        <tr>
          <th>4</th>
          <td>GadMARCM-F000709_seg001</td>
          <td>0.565479</td>
          <td>0.566549</td>
          <td>0.566014</td>
        </tr>
      </tbody>
    </table>
    </div>



|
Plot the top 2 hits ontop of the query neuron (black).

.. code:: ipython3

    fig = nbl.plot3d(hits=2, width=1000)

.. raw:: html
   :file: figures/3d_nblast_results.html
   
|
|
|
|