.. _quickstart:

Quickstart
**********
This tutorial will show you the basics of how to use NAVis. This is not supposed to be comprehensive but rather to give you a flavor of how things work. For inspiriation, explore the :ref:`example gallery <example_gallery>` and for detailed explanations have a look at the :ref:`API documentation <api>`.

Single Neurons
++++++++++++++
NAVis lets you import neurons from a variety of local and remote sources. For demonstration purposes NAVis comes with a bunch of fruit fly neurons from the `Janelia hemibrain <https://neuprint.janelia.org>`_ project:

.. code:: ipython3

    import navis
    
    n = navis.example_neurons(n=1, kind='skeleton')
    n




.. 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>1734350788</td>
        </tr>
        <tr>
          <th>id</th>
          <td>1734350788</td>
        </tr>
        <tr>
          <th>n_nodes</th>
          <td>4465</td>
        </tr>
        <tr>
          <th>n_connectors</th>
          <td>2705</td>
        </tr>
        <tr>
          <th>n_branches</th>
          <td>599</td>
        </tr>
        <tr>
          <th>n_leafs</th>
          <td>618</td>
        </tr>
        <tr>
          <th>cable_length</th>
          <td>266476.875</td>
        </tr>
        <tr>
          <th>soma</th>
          <td>[4177]</td>
        </tr>
        <tr>
          <th>units</th>
          <td>8 nanometer</td>
        </tr>
      </tbody>
    </table>
    </div>



In above code we loaded one of the example neurons. NAVis represents neurons as :class:`~navis.TreeNeuron`, :class:`~navis.MeshNeuron`, :class:`~navis.VoxelNeuron` or :class:`~navis.Dotprops`. In this example we asked for a skeleton, so the neuron returned is a ``TreeNeuron``. This class is essentially a wrapper around the actual neuron data (the SWC table in this case) and has some convenient features.

Node data is stored as ``pandas.DataFrame``:

.. code:: ipython3

    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>node_id</th>
          <th>label</th>
          <th>x</th>
          <th>y</th>
          <th>z</th>
          <th>radius</th>
          <th>parent_id</th>
          <th>type</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>1</td>
          <td>0</td>
          <td>15784.0</td>
          <td>37250.0</td>
          <td>28102.0</td>
          <td>10.0000</td>
          <td>-1</td>
          <td>root</td>
        </tr>
        <tr>
          <th>1</th>
          <td>2</td>
          <td>0</td>
          <td>15764.0</td>
          <td>37230.0</td>
          <td>28102.0</td>
          <td>18.2843</td>
          <td>1</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>2</th>
          <td>3</td>
          <td>0</td>
          <td>15744.0</td>
          <td>37190.0</td>
          <td>28142.0</td>
          <td>34.7214</td>
          <td>2</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>3</th>
          <td>4</td>
          <td>0</td>
          <td>15744.0</td>
          <td>37150.0</td>
          <td>28182.0</td>
          <td>34.7214</td>
          <td>3</td>
          <td>slab</td>
        </tr>
        <tr>
          <th>4</th>
          <td>5</td>
          <td>0</td>
          <td>15704.0</td>
          <td>37130.0</td>
          <td>28242.0</td>
          <td>34.7214</td>
          <td>4</td>
          <td>slab</td>
        </tr>
      </tbody>
    </table>
    </div>



.. note:: Pandas    
   `pandas <https://pandas.pydata.org>`_ is **the** data science library for Python and will help you analyze and visualize your data. **I highly recommend familiarizing yourself with pandas!** There are plenty of good tutorials out there but pandas' own `10 Minutes to pandas <https://pandas.pydata.org/pandas-docs/stable/10min.html>`_ is a good place to start. 

Try typing in "``n.``" and hitting tab: most attributes and functions are accessible via autocompletion. If you don't know what a function does, check out the documentation using ``help()`` or via the :ref:`API documentation <api>`:

.. code:: ipython3

    help(navis.TreeNeuron.root)


.. parsed-literal::

    Help on property:
    
        Root node(s).
    


.. code:: ipython3

    help(navis.TreeNeuron.downsample)


.. parsed-literal::

    Help on function downsample in module navis.core.neurons:
    
    downsample(self, factor=5, inplace=False, **kwargs)
        Downsample the neuron by given factor.
        
        Parameters
        ----------
        factor :                int, optional
                                Factor by which to downsample the neurons.
                                Default = 5.
        inplace :               bool, optional
                                If True, operation will be performed on
                                itself. If False, operation is performed on
                                copy which is then returned.
        **kwargs
                                Additional arguments passed to
                                :func:`~navis.downsample_neuron`.
        
        See Also
        --------
        :func:`~navis.downsample_neuron`
            Base function. See for details and examples.
    


You will notice that many NAVis functions that accept neurons have an ``inplace`` parameter. This is analogous to pandas:

.. code:: ipython3

    # Downsample a copy, leaving the original unchanged
    # (this is the default for almost all functions)
    n_ds = n.downsample(10, inplace=False)
    
    # Downsample the original neuron
    n_ds2 = n.copy()
    n_ds2.downsample(10, inplace=True)
    
    n_ds2




.. 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>TreeNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>neuron_38885</td>
        </tr>
        <tr>
          <th>n_nodes</th>
          <td>867</td>
        </tr>
        <tr>
          <th>n_connectors</th>
          <td>0</td>
        </tr>
        <tr>
          <th>n_branches</th>
          <td>235</td>
        </tr>
        <tr>
          <th>n_leafs</th>
          <td>243</td>
        </tr>
        <tr>
          <th>cable_length</th>
          <td>1.02046e+06</td>
        </tr>
        <tr>
          <th>soma</th>
          <td>[3490]</td>
        </tr>
      </tbody>
    </table>
    </div>



:class:`~navis.TreeNeuron` functions such as ``.downsample()`` are shorthands for calling the actual NAVis functions. So above code is equivalent to:

.. code:: ipython3

    n_ds = navis.downsample_neuron(n, downsampling_factor=10, inplace=False)
    n_ds




.. 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>TreeNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>neuron_38885</td>
        </tr>
        <tr>
          <th>n_nodes</th>
          <td>867</td>
        </tr>
        <tr>
          <th>n_connectors</th>
          <td>0</td>
        </tr>
        <tr>
          <th>n_branches</th>
          <td>235</td>
        </tr>
        <tr>
          <th>n_leafs</th>
          <td>243</td>
        </tr>
        <tr>
          <th>cable_length</th>
          <td>1.02046e+06</td>
        </tr>
        <tr>
          <th>soma</th>
          <td>[3490]</td>
        </tr>
      </tbody>
    </table>
    </div>



Lists of Neurons
++++++++++++++++

For multiple neurons, NAVis uses :class:`~navis.NeuronList`:

.. code:: ipython3

    nl = navis.example_neurons(n=3, kind='skeleton')
    nl




.. raw:: html

    &lt;class 'navis.core.neuronlist.NeuronList'&gt; containing 3 neurons (875.1KiB)<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>1734350788</td>
          <td>1734350788</td>
          <td>4465</td>
          <td>2705</td>
          <td>599</td>
          <td>618</td>
          <td>266476.87500</td>
          <td>[4177]</td>
          <td>8 nanometer</td>
        </tr>
        <tr>
          <th>1</th>
          <td>navis.TreeNeuron</td>
          <td>1734350908</td>
          <td>1734350908</td>
          <td>4847</td>
          <td>3042</td>
          <td>735</td>
          <td>761</td>
          <td>304332.65625</td>
          <td>[6]</td>
          <td>8 nanometer</td>
        </tr>
        <tr>
          <th>2</th>
          <td>navis.TreeNeuron</td>
          <td>722817260</td>
          <td>722817260</td>
          <td>4332</td>
          <td>3136</td>
          <td>633</td>
          <td>656</td>
          <td>274703.37500</td>
          <td>None</td>
          <td>8 nanometer</td>
        </tr>
      </tbody>
    </table>
    </div>



:class:`~navis.NeuronList` is a container and behaves like a glorified ``list``:

.. code:: ipython3

    nl[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>TreeNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>neuron_38885</td>
        </tr>
        <tr>
          <th>n_nodes</th>
          <td>6365</td>
        </tr>
        <tr>
          <th>n_connectors</th>
          <td>0</td>
        </tr>
        <tr>
          <th>n_branches</th>
          <td>235</td>
        </tr>
        <tr>
          <th>n_leafs</th>
          <td>243</td>
        </tr>
        <tr>
          <th>cable_length</th>
          <td>1.21335e+06</td>
        </tr>
        <tr>
          <th>soma</th>
          <td>[3490]</td>
        </tr>
      </tbody>
    </table>
    </div>



:class:`~navis.NeuronList` lets you run/access all functions (methods) and properties of the neurons it contrains:

.. code:: ipython3

    nl.cable_length




.. parsed-literal::

    array([266458.00615559, 304277.01267831, 274910.5606301 ])



.. code:: ipython3

    nl_ds = nl.downsample(10, inplace=False)
    
    nl_ds








.. 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>TreeNeuron</td>
          <td>1734350788</td>
          <td>1734350788</td>
          <td>1309</td>
          <td>None</td>
          <td>603</td>
          <td>619</td>
          <td>247375.660645</td>
          <td>[4176]</td>
          <td>8 nanometer</td>
        </tr>
        <tr>
          <th>1</th>
          <td>TreeNeuron</td>
          <td>1734350908</td>
          <td>1734350908</td>
          <td>1555</td>
          <td>None</td>
          <td>733</td>
          <td>760</td>
          <td>282432.973650</td>
          <td>[6]</td>
          <td>8 nanometer</td>
        </tr>
        <tr>
          <th>2</th>
          <td>TreeNeuron</td>
          <td>722817260</td>
          <td>722817260</td>
          <td>1350</td>
          <td>None</td>
          <td>635</td>
          <td>658</td>
          <td>254958.940182</td>
          <td>None</td>
          <td>8 nanometer</td>
        </tr>
      </tbody>
    </table>
    </div>



Let's finish this primer with some eye candy

.. code:: ipython3

    fig = nl.plot3d()

.. raw:: html
   :file: figures/quickstart_3d_plot.html
   
|
|
|
|

For more advanced stuff (plotting, pruning, cutting, NBLAST, etc.) have a look at the :ref:`example gallery <example_gallery>`.