.. _insectbraindb_tut:

Insect Brain DB
***************

The insect brain database (`link <https://insectbraindb.org>`_) is an online repository for neuron morphologies, brain regions and experimental data across various insect species. At the time of writing Insect Brain DB features close to 400 neuronal cell types from well over 30 insect species. Check out `Heinze et al. (2021) <https://elifesciences.org/articles/65376>`_ for details! While the website features a comprehensive search and some nifty analyses, it can be useful to download these data to run your own analyses or compare to other data sets.

For that purpose, `navis` provides an interface to Insect Brain DB that wraps parts of their API.

.. code:: ipython3

    # Import navis
    import navis
    
    # Import the actual Insect Brain DB interface
    import navis.interfaces.insectbrain_db as ibdb

Fetching meta data
------------------
First, fetch a list of available species:

.. code:: ipython3

    species = ibdb.get_available_species()
    species.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>id</th>
          <th>scientific_name</th>
          <th>common_name</th>
          <th>uuid</th>
          <th>date_created</th>
          <th>date_modified</th>
          <th>persistent_records</th>
          <th>description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>24</td>
          <td>Aedes aegypti</td>
          <td>Yellow fever mosquito</td>
          <td>628dbce3-20f4-4af8-8c78-f9d3bc0c6654</td>
          <td>2019-03-04T22:28:27.697821Z</td>
          <td>2022-05-19T16:01:37.298876Z</td>
          <td>[20.500.12158/SIN-0000024.2, 20.500.12158/SIN-...</td>
          <td>Aedes aegypti, the yellow fever mosquito, is t...</td>
        </tr>
        <tr>
          <th>1</th>
          <td>2</td>
          <td>Agrotis infusa</td>
          <td>Bogong moth</td>
          <td>a6d4eadd-2e82-4393-96ab-fdfedaf42536</td>
          <td>2016-07-10T08:37:09.361502Z</td>
          <td>2022-05-19T16:02:16.115941Z</td>
          <td>[20.500.12158/SIN-0000002.1, 20.500.12158/SIN-...</td>
          <td>"The nocturnal Bogong moth (Agrotis infusa) is...</td>
        </tr>
        <tr>
          <th>2</th>
          <td>21</td>
          <td>Agrotis segetum</td>
          <td>Turnip moth</td>
          <td>ae12170d-d655-4794-9f38-54ca4f1b3c50</td>
          <td>2017-04-26T10:55:52.000344Z</td>
          <td>2022-05-19T16:02:49.110675Z</td>
          <td>[20.500.12158/SIN-0000021.1, 20.500.12158/SIN-...</td>
          <td>The turnip moth, Agrotis segetum Denis and Sch...</td>
        </tr>
        <tr>
          <th>3</th>
          <td>7</td>
          <td>Apis mellifera</td>
          <td>Honeybee</td>
          <td>8881609d-1929-410a-be38-ca47da5718d5</td>
          <td>2016-07-10T08:37:09.372889Z</td>
          <td>2022-05-19T16:10:37.640885Z</td>
          <td>[20.500.12158/SIN-0000007.1, 20.500.12158/SIN-...</td>
          <td>The western honey bee or European honey bee (A...</td>
        </tr>
        <tr>
          <th>4</th>
          <td>10</td>
          <td>Bombus terrestris</td>
          <td>Bumble Bee</td>
          <td>718388b3-8fbe-4b49-82c5-44493347bb30</td>
          <td>2016-07-10T08:37:09.383142Z</td>
          <td>2022-05-19T16:18:26.774832Z</td>
          <td>[20.500.12158/SIN-0000010.1, 20.500.12158/SIN-...</td>
          <td>Bombus terrestris, the buff-tailed bumblebee o...</td>
        </tr>
      </tbody>
    </table>
    </div>



Fetch info for a given species (you can use the scientific or common name, or an ID):

.. code:: ipython3

    spec_info = ibdb.get_species_info('Schistocerca gregaria')
    spec_info




.. parsed-literal::

    id                                                                        9
    uuid                                   795f4fd5-cad7-4de0-853f-89406a64aa98
    images                    [{'id': 925, 'tag': 'SPECIES_IMAGE', 'hash': N...
    prefix                                                                   sg
    public                                                                 True
    approved                                                               True
    curators                  [{'uuid': 'c51a2d7e-6314-487a-9b8b-384db7ff79e...
    host_lab                                    Uwe Homberg, Marburg University
    created_by                {'uuid': '89c53715-561d-4942-81ab-aa4a02237fdd...
    searchable                                                             True
    structures                [{'id': 1, 'name': 'Antennal Lobe', 'type': 's...
    common_name                                                   Desert Locust
    description               The desert locust (Schistocerca gregaria) is a...
    experiments                                                              []
    date_created                                    2016-07-10T08:37:09.454013Z
    date_modified                                   2021-07-20T06:55:06.812019Z
    confocal_stacks                                                          []
    reconstructions           [{'id': 66, 'sex': 'UNKNOWN', 'uuid': '8b10333...
    scientific_name                                       Schistocerca gregaria
    neuron_publications       [{'id': 340, 'doi': 'https://doi.org/10.1002/c...
    species_publications      [{'id': 327, 'doi': '10.3389/fnbeh.2015.00346'...
    semi_schematic_default                                                 None
    dtype: object



Fetching meshes
---------------

Fetch neuropil meshes for the Locust brain:

.. code:: ipython3

    # `combine=True` would produce a single combined mesh but here we want a list of individual neuropils
    locust_brain = ibdb.get_brain_meshes('Desert Locust', combine=False)
    locust_brain[:2]


.. parsed-literal::

    INFO  : 1 reconstruction(s) from 1 brain(s) found (navis)












.. parsed-literal::

    [<navis.Volume(name=Anterior lobula (left), color=(1.0, 0.4, 0.0, 0.5), vertices.shape=(2502, 3), faces.shape=(5000, 3))>,
     <navis.Volume(name=Upper lateral accessory lobe (right), color=(0.4392156862745098, 0.8, 0.1607843137254902, 0.5), vertices.shape=(5002, 3), faces.shape=(10000, 3))>]



.. code:: ipython3

    # Plot neuropils
    fig = navis.plot3d(locust_brain, width=1200, volume_legend=True)

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

Fetch neurons
-------------

First we need to know what neurons are available. Just like on the website you can set all kinds of different search parameters. Here we will stick with our Locust:

.. code:: ipython3

    locust_neurons = ibdb.search_neurons(species='Desert Locust')
    locust_neurons.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>id</th>
          <th>name</th>
          <th>full_name</th>
          <th>short_name</th>
          <th>persistent_records</th>
          <th>uploaded_by</th>
          <th>nin</th>
          <th>date_uploaded</th>
          <th>reconstruction_creator</th>
          <th>group_head</th>
          <th>...</th>
          <th>public</th>
          <th>hemisphere</th>
          <th>archived</th>
          <th>archived_notes</th>
          <th>species</th>
          <th>template_type</th>
          <th>superseding_record</th>
          <th>super_type</th>
          <th>neuron_family</th>
          <th>neuron_class</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>426</td>
          <td>CL1a-L1</td>
          <td>sg-CL1a-L1(L)</td>
          <td>CL1a-L1</td>
          <td>[20.500.12158/NIN-0000426.1]</td>
          <td>{'id': 41, 'first_name': 'Frederick', 'last_na...</td>
          <td>NIN-0000426</td>
          <td>2021-07-01T00:00:00Z</td>
          <td></td>
          <td>Uwe Homberg</td>
          <td>...</td>
          <td>True</td>
          <td>LEFT</td>
          <td>False</td>
          <td>None</td>
          <td>9</td>
          <td>1</td>
          <td>None</td>
          <td>31.0</td>
          <td>8.0</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>1</th>
          <td>429</td>
          <td>CL1a-L3</td>
          <td>sg-CL1a-L3(L)</td>
          <td>CL1a-L3</td>
          <td>[20.500.12158/NIN-0000429.1]</td>
          <td>{'id': 41, 'first_name': 'Frederick', 'last_na...</td>
          <td>NIN-0000429</td>
          <td>2021-07-01T00:00:00Z</td>
          <td></td>
          <td>Uwe Homberg</td>
          <td>...</td>
          <td>True</td>
          <td>LEFT</td>
          <td>False</td>
          <td>None</td>
          <td>9</td>
          <td>1</td>
          <td>None</td>
          <td>31.0</td>
          <td>8.0</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>2</th>
          <td>440</td>
          <td>CL1a-L4</td>
          <td>sg-CL1a-L4(L)</td>
          <td>CL1a-L4</td>
          <td>[20.500.12158/NIN-0000440.1]</td>
          <td>{'id': 41, 'first_name': 'Frederick', 'last_na...</td>
          <td>NIN-0000440</td>
          <td>2021-07-01T00:00:00Z</td>
          <td></td>
          <td>Uwe Homberg</td>
          <td>...</td>
          <td>True</td>
          <td>LEFT</td>
          <td>False</td>
          <td>None</td>
          <td>9</td>
          <td>1</td>
          <td>None</td>
          <td>31.0</td>
          <td>8.0</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>3</th>
          <td>425</td>
          <td>CL1a-L5</td>
          <td>sg-CL1a-L5(L)</td>
          <td>CL1a-L5</td>
          <td>[20.500.12158/NIN-0000425.1]</td>
          <td>{'id': 41, 'first_name': 'Frederick', 'last_na...</td>
          <td>NIN-0000425</td>
          <td>2021-07-01T00:00:00Z</td>
          <td></td>
          <td>Uwe Homberg</td>
          <td>...</td>
          <td>True</td>
          <td>LEFT</td>
          <td>False</td>
          <td>None</td>
          <td>9</td>
          <td>1</td>
          <td>None</td>
          <td>31.0</td>
          <td>8.0</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>4</th>
          <td>423</td>
          <td>CL1a-R2</td>
          <td>sg-CL1a-R2(R)</td>
          <td>CL1a</td>
          <td>[20.500.12158/NIN-0000423.1]</td>
          <td>{'id': 71, 'first_name': 'Ronja', 'last_name':...</td>
          <td>NIN-0000423</td>
          <td>2021-06-19T00:00:00Z</td>
          <td>Stefanie Jahn</td>
          <td>Uwe Homberg</td>
          <td>...</td>
          <td>True</td>
          <td>RIGHT</td>
          <td>False</td>
          <td>None</td>
          <td>9</td>
          <td>1</td>
          <td>None</td>
          <td>6.0</td>
          <td>8.0</td>
          <td>1.0</td>
        </tr>
      </tbody>
    </table>
    <p>5 rows × 21 columns</p>
    </div>



Let's fetch skeletons ("reconstructions") for some of the above neurons. Note that not all neurons have skeletons (see the "reconstruction_creator" column)!

.. code:: ipython3

    # You can use IDs or names, or a combination thereof to fetch skeletons
    skeleton = ibdb.get_skeletons('CL1a-R2')
    skeleton




.. raw:: html

    &lt;class 'navis.core.neuronlist.NeuronList'&gt; containing 1 neurons (4.2MiB)<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>CL1190516SkeletonTreeRight.swc</td>
          <td>423</td>
          <td>78559</td>
          <td>None</td>
          <td>330</td>
          <td>340</td>
          <td>9918.345885</td>
          <td>None</td>
          <td>1 micrometer</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    # Plot the neuron - note that most neurons appear to have radii information 
    fig = skeleton.plot3d(radius=True)

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

Check out the :ref:`API reference<api_interfaces.insectdb>` for further details.