.. _neuprint_intro:

neuPrint
--------

`Neuprint <https://www.biorxiv.org/content/10.1101/2020.01.16.909465v1>`_ is a service for presenting and analyzing connectomics data. It is used to host the Janelia EM reconstructions from a Drosophila hemibrain at https://neuprint.janelia.org/.

`neuprint-python <https://github.com/connectome-neuprint/neuprint-python>`_ is a Python library that lets you query data directly from a neuprint server. You can install it from PyPI::

    pip3 install neuprint-python

``navis.interfaces.neuprint`` wraps ``neuprint-python`` and adds a few functions to fetch and convert data into navis objects.

.. code:: ipython3

    # Import navis
    import navis
    
    # Import neuprint wrapper by navis
    import navis.interfaces.neuprint as neu

First set up the connection:
You can either pass your API token directly or store as ``NEUPRINT_APPLICATION_CREDENTIALS`` environment variable. We will use the latter option here:

.. code:: ipython3

    client = neu.Client(
        "https://neuprint.janelia.org/",
        # token="MYLONGTOKEN"  # use this to instead pass your token directly
        dataset="hemibrain:v1.1",
    )

You can use all of neuprint's functions:

.. code:: ipython3

    mbons, roi_info = neu.fetch_neurons(
        neu.SegmentCriteria(instance=".*MBON.*", regex=True)
    )
    mbons.head(3)




.. 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>bodyId</th>
          <th>instance</th>
          <th>type</th>
          <th>pre</th>
          <th>post</th>
          <th>downstream</th>
          <th>upstream</th>
          <th>size</th>
          <th>status</th>
          <th>cropped</th>
          <th>statusLabel</th>
          <th>cellBodyFiber</th>
          <th>somaRadius</th>
          <th>somaLocation</th>
          <th>roiInfo</th>
          <th>notes</th>
          <th>inputRois</th>
          <th>outputRois</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>300972942</td>
          <td>MBON14(a3)_R</td>
          <td>MBON14</td>
          <td>543</td>
          <td>13634</td>
          <td>4340</td>
          <td>13634</td>
          <td>1563154937</td>
          <td>Traced</td>
          <td>False</td>
          <td>Roughly traced</td>
          <td>None</td>
          <td>NaN</td>
          <td>None</td>
          <td>{'MB(R)': {'pre': 17, 'post': 13295, 'downstre...</td>
          <td>None</td>
          <td>[MB(+ACA)(R), MB(R), SIP(R), SLP(R), SMP(R), S...</td>
          <td>[MB(+ACA)(R), MB(R), SIP(R), SLP(R), SMP(R), S...</td>
        </tr>
        <tr>
          <th>1</th>
          <td>394225044</td>
          <td>MBON14(a3)_L</td>
          <td>MBON14</td>
          <td>187</td>
          <td>5172</td>
          <td>768</td>
          <td>5172</td>
          <td>355138411</td>
          <td>Traced</td>
          <td>False</td>
          <td>Roughly traced</td>
          <td>None</td>
          <td>NaN</td>
          <td>None</td>
          <td>{'MB(L)': {'pre': 185, 'post': 5143, 'downstre...</td>
          <td>None</td>
          <td>[MB(L), SIP(L), SNP(L), aL(L)]</td>
          <td>[MB(L), SIP(L), SNP(L), aL(L)]</td>
        </tr>
        <tr>
          <th>2</th>
          <td>422725634</td>
          <td>MBON06(B1&gt;a)(AVM07)_L</td>
          <td>MBON06</td>
          <td>1356</td>
          <td>21000</td>
          <td>9584</td>
          <td>21000</td>
          <td>3118470391</td>
          <td>Traced</td>
          <td>False</td>
          <td>Roughly traced</td>
          <td>None</td>
          <td>NaN</td>
          <td>None</td>
          <td>{'MB(R)': {'pre': 777, 'post': 20390, 'downstr...</td>
          <td>None</td>
          <td>[CRE(-ROB,-RUB)(R), CRE(R), INP, MB(+ACA)(R), ...</td>
          <td>[CRE(-ROB,-RUB)(R), CRE(R), INP, MB(+ACA)(R), ...</td>
        </tr>
      </tbody>
    </table>
    </div>



NAVis has added three functions to ``neu``:
  - :func:`navis.interfaces.neuprint.fetch_roi`: returns a :class:`navis.Volume` from a ROI
  - :func:`navis.interfaces.neuprint.fetch_skeletons`: returns fully fledged :class:`navis.TreeNeuron` - nodes, synapses, soma and all
  - :func:`navis.interfaces.neuprint.fetch_mesh_neuron`: returns :class:`navis.MeshNeuron` - including synapses

.. code:: ipython3

    mb = neu.fetch_roi("MB(R)")
    mb




.. parsed-literal::

    <navis.Volume(name=MB(R), color=(0.85, 0.85, 0.85, 0.2), vertices.shape=(57913, 3), faces.shape=(115856, 3))>



.. code:: ipython3

    mbon_skeletons = neu.fetch_skeletons(
        neu.SegmentCriteria(instance=".*MBON.*_R", regex=True), with_synapses=True
    )
    mbon_skeletons.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>type</th>
          <th>name</th>
          <th>id</th>
          <th>n_nodes</th>
          <th>n_connectors</th>
          <th>n_branches</th>
          <th>n_leafs</th>
          <th>cable_length</th>
          <th>soma</th>
          <th>units</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>navis.TreeNeuron</td>
          <td>MBON23(a2sp)_R</td>
          <td>423382015</td>
          <td>14190</td>
          <td>5200</td>
          <td>1195</td>
          <td>1225</td>
          <td>449662.18750</td>
          <td>2364.0</td>
          <td>8 nanometer</td>
        </tr>
        <tr>
          <th>1</th>
          <td>navis.TreeNeuron</td>
          <td>MBON19(a2p3p)_R</td>
          <td>423774471</td>
          <td>6944</td>
          <td>1783</td>
          <td>549</td>
          <td>561</td>
          <td>246499.53125</td>
          <td>1781.0</td>
          <td>8 nanometer</td>
        </tr>
        <tr>
          <th>2</th>
          <td>navis.TreeNeuron</td>
          <td>MBON15-like(a'1a'2)_R</td>
          <td>457175171</td>
          <td>9051</td>
          <td>2299</td>
          <td>548</td>
          <td>561</td>
          <td>325558.90625</td>
          <td>8810.0</td>
          <td>8 nanometer</td>
        </tr>
        <tr>
          <th>3</th>
          <td>navis.TreeNeuron</td>
          <td>MBON16-like(a'3a)_R</td>
          <td>457196643</td>
          <td>9769</td>
          <td>4016</td>
          <td>900</td>
          <td>913</td>
          <td>408057.59375</td>
          <td>5974.0</td>
          <td>8 nanometer</td>
        </tr>
        <tr>
          <th>4</th>
          <td>navis.TreeNeuron</td>
          <td>MBON14(a3)_R</td>
          <td>300972942</td>
          <td>22834</td>
          <td>14177</td>
          <td>2297</td>
          <td>2369</td>
          <td>758249.75000</td>
          <td>NaN</td>
          <td>8 nanometer</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    # Generate a 3D plot
    fig = navis.plot3d([mbon_skeletons[0], mb])

.. raw:: html
   :file: figures/3d_neuprint.html

|
|
|
|

.. code:: ipython3

    mbon_skeletons[0]




.. 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></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>type</th>
          <td>navis.TreeNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>MBON23(a2sp)_R</td>
        </tr>
        <tr>
          <th>id</th>
          <td>423382015</td>
        </tr>
        <tr>
          <th>n_nodes</th>
          <td>14190</td>
        </tr>
        <tr>
          <th>n_connectors</th>
          <td>5200</td>
        </tr>
        <tr>
          <th>n_branches</th>
          <td>1195</td>
        </tr>
        <tr>
          <th>n_leafs</th>
          <td>1225</td>
        </tr>
        <tr>
          <th>cable_length</th>
          <td>449662.1875</td>
        </tr>
        <tr>
          <th>soma</th>
          <td>2364</td>
        </tr>
        <tr>
          <th>units</th>
          <td>8 nanometer</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    # Make a 2d plot
    import matplotlib.pyplot as plt
    
    fig, ax = navis.plot2d(
        [mbon_skeletons[0], mb], c=(0, 0, 0, 0.5), method="3d", connectors=True, lw=0.5
    )
    
    # Rotate to top view
    ax.elev = -90
    plt.show()



.. image:: neuprint_files/neuprint_12_0.png


All navis functions for analysis & visualization should work on these neurons. If not, please open an issue on Github.