.. _flywire_annotations:

Working with annotations
========================

.. important::

    This tutorial is written for ``fafbseg`` version ``>=3.0.0`` which made
    substantial changes to how annotations are handled. Please make sure your
    ``fafbseg`` version is up to date.

At this point in time, there are three large sources for annotations/meta data for FlyWire
neurons:

1. Free-form community annotations every user can place through the neuroglancer UI
2. Systematic annotations (classes, sides, types, etc) for the entire brain `Schlegel et al <https://www.biorxiv.org/content/10.1101/2023.06.27.546055v1>`_
3. Systematic cell types for the right optic lobe from `Matsliah et al <https://www.biorxiv.org/content/10.1101/2023.10.12.562119v2>`_

In `Codex <https://codex.flywire.ai/app/search>`_, (1) is what you see in
the "Community labels" column while (2) and (3) are used to fill the "Classification"
and "Type" columns.

Currently ``fafbseg`` allows you to query (1) and (2) programmatically. (3) is not yet supported.

.. code:: ipython3

    >>> from fafbseg import flywire
    
    >>> # We'll be demonstrating this using the public release dataset
    >>> flywire.set_default_dataset("public")


.. parsed-literal::

    Default dataset set to "public".


Query community annotations (1) for a single neuron:

.. code:: ipython3

    >>> ann = flywire.search_community_annotations(720575940625431866)
    >>> ann.head()


.. parsed-literal::

    Using materialization version 783.
    Caching community annotations for materialization version "783"... Done.




.. 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>created</th>
          <th>superceded_id</th>
          <th>pt_position_x</th>
          <th>pt_position_y</th>
          <th>pt_position_z</th>
          <th>tag</th>
          <th>user</th>
          <th>user_id</th>
          <th>pt_supervoxel_id</th>
          <th>pt_root_id</th>
          <th>user_name</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>22248</td>
          <td>2022-02-07 05:30:08.054976+00:00</td>
          <td>NaN</td>
          <td>485772</td>
          <td>238836</td>
          <td>49920</td>
          <td>ALad1; right; acetylcholine</td>
          <td>Alexander Bates</td>
          <td>355</td>
          <td>78957304514692633</td>
          <td>720575940625431866</td>
          <td>Alexander Bates</td>
        </tr>
        <tr>
          <th>1</th>
          <td>22249</td>
          <td>2022-02-07 05:30:08.056123+00:00</td>
          <td>NaN</td>
          <td>485772</td>
          <td>238836</td>
          <td>49920</td>
          <td>ALad1; right; acetylcholine</td>
          <td>Lab Members</td>
          <td>1063</td>
          <td>78957304514692633</td>
          <td>720575940625431866</td>
          <td>Lab Members</td>
        </tr>
        <tr>
          <th>2</th>
          <td>49507</td>
          <td>2022-04-27 14:36:19.985327+00:00</td>
          <td>NaN</td>
          <td>485776</td>
          <td>238836</td>
          <td>49920</td>
          <td>ALPN,VM5v_adPN</td>
          <td>Philipp Schlegel</td>
          <td>62</td>
          <td>78957304514685298</td>
          <td>720575940625431866</td>
          <td>Philipp Schlegel</td>
        </tr>
      </tbody>
    </table>
    </div>



Query the hierarchical annotations (2) for the same neuron:

.. code:: ipython3

    >>> ann = flywire.search_annotations(720575940625431866)
    >>> ann.head()


.. parsed-literal::

    Using annotation version "latest commit" (b2bceba) from https://github.com/flyconnectome/flywire_annotations.
    Using materialization version 783.




.. 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>supervoxel_id</th>
          <th>root_id</th>
          <th>pos_x</th>
          <th>pos_y</th>
          <th>pos_z</th>
          <th>soma_x</th>
          <th>soma_y</th>
          <th>soma_z</th>
          <th>nucleus_id</th>
          <th>flow</th>
          <th>...</th>
          <th>morphology_group</th>
          <th>top_nt</th>
          <th>top_nt_conf</th>
          <th>known_nt</th>
          <th>known_nt_source</th>
          <th>side</th>
          <th>nerve</th>
          <th>vfb_id</th>
          <th>fbbt_id</th>
          <th>status</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>78957304514685298</td>
          <td>720575940625431866</td>
          <td>121444</td>
          <td>59709</td>
          <td>1248</td>
          <td>125088.0</td>
          <td>52048.0</td>
          <td>782.0</td>
          <td>4518783.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALad1__1</td>
          <td>acetylcholine</td>
          <td>0.957189</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw036274</td>
          <td>FBbt_00100386</td>
          <td>NaN</td>
        </tr>
      </tbody>
    </table>
    <p>1 rows × 27 columns</p>
    </div>



For the hierarchical annotations we expect to get only one row per neuron. Let's
inspect that first row:

.. code:: ipython3

    >>> ann.iloc[0]




.. parsed-literal::

    supervoxel_id                78957304514685298
    root_id                     720575940625431866
    pos_x                                   121444
    pos_y                                    59709
    pos_z                                     1248
    soma_x                                125088.0
    soma_y                                 52048.0
    soma_z                                   782.0
    nucleus_id                           4518783.0
    flow                                 intrinsic
    super_class                            central
    cell_class                                ALPN
    cell_sub_class                   uniglomerular
    cell_type                                  NaN
    hemibrain_type                       VM5v_adPN
    ito_lee_hemilineage                      ALad1
    hartenstein_hemilineage                  BAmv3
    morphology_group                      ALad1__1
    top_nt                           acetylcholine
    top_nt_conf                           0.957189
    known_nt                         acetylcholine
    known_nt_source            Tanaka et al., 2012
    side                                      left
    nerve                                      NaN
    vfb_id                                fw036274
    fbbt_id                          FBbt_00100386
    status                                     NaN
    Name: 0, dtype: object



OK, we get a bunch of useful meta data for our neuron of interest.

What if we're looking for e.g. a specific cell type instead? Easy:

.. code:: ipython3

    >>> # Search community annotations for a given tag
    >>> ann = flywire.search_community_annotations("VM5v_adPN")
    >>> ann.head()


.. parsed-literal::

    Caching community annotations for materialization version "783"... Done.




.. 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>created</th>
          <th>superceded_id</th>
          <th>pos_x</th>
          <th>pos_y</th>
          <th>pos_z</th>
          <th>tag</th>
          <th>user</th>
          <th>user_id</th>
          <th>supervoxel_id</th>
          <th>root_id</th>
          <th>user_name</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>48935</td>
          <td>2022-04-27 14:21:54.766389+00:00</td>
          <td>NaN</td>
          <td>142332</td>
          <td>61350</td>
          <td>928</td>
          <td>ALPN,VM5v_adPN</td>
          <td>Philipp Schlegel</td>
          <td>62</td>
          <td>80435185514499960</td>
          <td>720575940622287142</td>
          <td>Philipp Schlegel</td>
        </tr>
        <tr>
          <th>1</th>
          <td>49092</td>
          <td>2022-04-27 14:26:00.639112+00:00</td>
          <td>NaN</td>
          <td>120504</td>
          <td>60065</td>
          <td>1194</td>
          <td>ALPN,VM5v_adPN</td>
          <td>Philipp Schlegel</td>
          <td>62</td>
          <td>78887004489925320</td>
          <td>720575940620189790</td>
          <td>Philipp Schlegel</td>
        </tr>
        <tr>
          <th>2</th>
          <td>49429</td>
          <td>2022-04-27 14:34:21.735996+00:00</td>
          <td>NaN</td>
          <td>142744</td>
          <td>62078</td>
          <td>944</td>
          <td>ALPN,VM5v_adPN</td>
          <td>Philipp Schlegel</td>
          <td>62</td>
          <td>80435185514524409</td>
          <td>720575940619637780</td>
          <td>Philipp Schlegel</td>
        </tr>
        <tr>
          <th>3</th>
          <td>49507</td>
          <td>2022-04-27 14:36:19.985327+00:00</td>
          <td>NaN</td>
          <td>121444</td>
          <td>59709</td>
          <td>1248</td>
          <td>ALPN,VM5v_adPN</td>
          <td>Philipp Schlegel</td>
          <td>62</td>
          <td>78957304514685298</td>
          <td>720575940625431866</td>
          <td>Philipp Schlegel</td>
        </tr>
        <tr>
          <th>4</th>
          <td>49495</td>
          <td>2022-04-27 14:36:02.233129+00:00</td>
          <td>NaN</td>
          <td>121284</td>
          <td>59660</td>
          <td>1036</td>
          <td>ALPN,VM5v_adPN</td>
          <td>Philipp Schlegel</td>
          <td>62</td>
          <td>78957304447921539</td>
          <td>720575940610505170</td>
          <td>Philipp Schlegel</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    >>> # Look for a specific string among the hierarchical annotations
    >>> ann = flywire.search_annotations("VM5v_adPN")
    >>> ann.head()


.. parsed-literal::

    Using materialization version 783.




.. 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>supervoxel_id</th>
          <th>root_id</th>
          <th>pos_x</th>
          <th>pos_y</th>
          <th>pos_z</th>
          <th>soma_x</th>
          <th>soma_y</th>
          <th>soma_z</th>
          <th>nucleus_id</th>
          <th>flow</th>
          <th>...</th>
          <th>morphology_group</th>
          <th>top_nt</th>
          <th>top_nt_conf</th>
          <th>known_nt</th>
          <th>known_nt_source</th>
          <th>side</th>
          <th>nerve</th>
          <th>vfb_id</th>
          <th>fbbt_id</th>
          <th>status</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>80435185514499960</td>
          <td>720575940622287142</td>
          <td>142332</td>
          <td>61350</td>
          <td>928</td>
          <td>139912.0</td>
          <td>51768.0</td>
          <td>698.0</td>
          <td>5057638.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALad1__1</td>
          <td>acetylcholine</td>
          <td>0.943605</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>right</td>
          <td>NaN</td>
          <td>fw000568</td>
          <td>FBbt_00100386</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>1</th>
          <td>78887004489925320</td>
          <td>720575940620189790</td>
          <td>120504</td>
          <td>60065</td>
          <td>1194</td>
          <td>124824.0</td>
          <td>49920.0</td>
          <td>998.0</td>
          <td>4518437.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALad1__1</td>
          <td>acetylcholine</td>
          <td>0.950719</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw012119</td>
          <td>FBbt_00100386</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>2</th>
          <td>80435185514524409</td>
          <td>720575940619637780</td>
          <td>142744</td>
          <td>62078</td>
          <td>944</td>
          <td>140752.0</td>
          <td>52368.0</td>
          <td>374.0</td>
          <td>5739285.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALad1__1</td>
          <td>acetylcholine</td>
          <td>0.920976</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>right</td>
          <td>NaN</td>
          <td>fw034817</td>
          <td>FBbt_00100386</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>3</th>
          <td>78957304447921539</td>
          <td>720575940610505170</td>
          <td>121284</td>
          <td>59660</td>
          <td>1036</td>
          <td>124040.0</td>
          <td>49616.0</td>
          <td>906.0</td>
          <td>4515954.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALad1__1</td>
          <td>acetylcholine</td>
          <td>0.951816</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw036072</td>
          <td>FBbt_00100386</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>4</th>
          <td>78957304514685298</td>
          <td>720575940625431866</td>
          <td>121444</td>
          <td>59709</td>
          <td>1248</td>
          <td>125088.0</td>
          <td>52048.0</td>
          <td>782.0</td>
          <td>4518783.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALad1__1</td>
          <td>acetylcholine</td>
          <td>0.957189</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw036274</td>
          <td>FBbt_00100386</td>
          <td>NaN</td>
        </tr>
      </tbody>
    </table>
    <p>5 rows × 27 columns</p>
    </div>



For the hierarchical annotations we can also run queries against specific fields:

.. code:: ipython3

    >>> # Fetch all gustatory sensory neurons
    >>> gust = flywire.search_annotations("cell_class:gustatory")
    >>> gust.head()


.. parsed-literal::

    Using materialization version 783.




.. 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>supervoxel_id</th>
          <th>root_id</th>
          <th>pos_x</th>
          <th>pos_y</th>
          <th>pos_z</th>
          <th>soma_x</th>
          <th>soma_y</th>
          <th>soma_z</th>
          <th>nucleus_id</th>
          <th>flow</th>
          <th>...</th>
          <th>morphology_group</th>
          <th>top_nt</th>
          <th>top_nt_conf</th>
          <th>known_nt</th>
          <th>known_nt_source</th>
          <th>side</th>
          <th>nerve</th>
          <th>vfb_id</th>
          <th>fbbt_id</th>
          <th>status</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>79098797984212565</td>
          <td>720575940628673474</td>
          <td>123538</td>
          <td>70948</td>
          <td>1630</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>afferent</td>
          <td>...</td>
          <td>NaN</td>
          <td>acetylcholine</td>
          <td>0.701929</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>left</td>
          <td>PhN</td>
          <td>fw039687</td>
          <td>NaN</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>1</th>
          <td>79240016576488341</td>
          <td>720575940621375231</td>
          <td>125710</td>
          <td>77813</td>
          <td>2496</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>afferent</td>
          <td>...</td>
          <td>NaN</td>
          <td>acetylcholine</td>
          <td>0.623311</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>left</td>
          <td>MxLbN</td>
          <td>fw043484</td>
          <td>NaN</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>2</th>
          <td>78888585171909593</td>
          <td>720575940625507870</td>
          <td>120188</td>
          <td>83973</td>
          <td>2069</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>afferent</td>
          <td>...</td>
          <td>NaN</td>
          <td>acetylcholine</td>
          <td>0.716926</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>left</td>
          <td>MxLbN</td>
          <td>fw043485</td>
          <td>NaN</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>3</th>
          <td>78888516385974174</td>
          <td>720575940635791167</td>
          <td>120512</td>
          <td>82676</td>
          <td>2063</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>afferent</td>
          <td>...</td>
          <td>NaN</td>
          <td>acetylcholine</td>
          <td>0.747361</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>left</td>
          <td>MxLbN</td>
          <td>fw043486</td>
          <td>NaN</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>4</th>
          <td>78747710244640262</td>
          <td>720575940629270339</td>
          <td>118458</td>
          <td>82316</td>
          <td>2109</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>afferent</td>
          <td>...</td>
          <td>NaN</td>
          <td>acetylcholine</td>
          <td>0.727190</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>left</td>
          <td>MxLbN</td>
          <td>fw043487</td>
          <td>NaN</td>
          <td>NaN</td>
        </tr>
      </tbody>
    </table>
    <p>5 rows × 27 columns</p>
    </div>



What if you have some more complicated query in mind? No problem, you can use
:class:`~fafbseg.flywire.NeuronCriteria` to build up your query:

.. code:: ipython3

    >>> # Fetch all DA1 projection neurons on the left side
    >>> NC = flywire.NeuronCriteria
    >>> da1 = flywire.search_annotations(NC(type='DA1_lPN', side='left'))
    >>> da1


.. parsed-literal::

    Found 8 neurons matching the given criteria.
    Using materialization version 783.




.. 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>supervoxel_id</th>
          <th>root_id</th>
          <th>pos_x</th>
          <th>pos_y</th>
          <th>pos_z</th>
          <th>soma_x</th>
          <th>soma_y</th>
          <th>soma_z</th>
          <th>nucleus_id</th>
          <th>flow</th>
          <th>...</th>
          <th>morphology_group</th>
          <th>top_nt</th>
          <th>top_nt_conf</th>
          <th>known_nt</th>
          <th>known_nt_source</th>
          <th>side</th>
          <th>nerve</th>
          <th>vfb_id</th>
          <th>fbbt_id</th>
          <th>status</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>78253479633951114</td>
          <td>720575940614309535</td>
          <td>111226</td>
          <td>57542</td>
          <td>1253</td>
          <td>101328.0</td>
          <td>57432.0</td>
          <td>1311.0</td>
          <td>2469243.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALl1_ventral__7</td>
          <td>acetylcholine</td>
          <td>0.929829</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw012440</td>
          <td>FBbt_00067363</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>1</th>
          <td>78323710939184200</td>
          <td>720575940619385765</td>
          <td>111620</td>
          <td>55558</td>
          <td>1239</td>
          <td>101816.0</td>
          <td>55568.0</td>
          <td>1655.0</td>
          <td>2469812.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALl1_ventral__7</td>
          <td>acetylcholine</td>
          <td>0.909374</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw032945</td>
          <td>FBbt_00067363</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>2</th>
          <td>78323848378217543</td>
          <td>720575940626034819</td>
          <td>111774</td>
          <td>57252</td>
          <td>1326</td>
          <td>100824.0</td>
          <td>56608.0</td>
          <td>1386.0</td>
          <td>2468760.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALl1_ventral__7</td>
          <td>acetylcholine</td>
          <td>0.894545</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw033427</td>
          <td>FBbt_00067363</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>3</th>
          <td>78464860744572652</td>
          <td>720575940621185050</td>
          <td>113815</td>
          <td>61631</td>
          <td>1390</td>
          <td>102688.0</td>
          <td>55800.0</td>
          <td>1508.0</td>
          <td>2471407.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALl1_ventral__7</td>
          <td>acetylcholine</td>
          <td>0.930650</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw033526</td>
          <td>FBbt_00067363</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>4</th>
          <td>78323779658725881</td>
          <td>720575940613345442</td>
          <td>111894</td>
          <td>56379</td>
          <td>1297</td>
          <td>101168.0</td>
          <td>54536.0</td>
          <td>1584.0</td>
          <td>2468972.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALl1_ventral__7</td>
          <td>acetylcholine</td>
          <td>0.916676</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw034548</td>
          <td>FBbt_00067363</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>5</th>
          <td>78605529513349676</td>
          <td>720575940637208718</td>
          <td>115991</td>
          <td>60386</td>
          <td>1314</td>
          <td>105608.0</td>
          <td>55088.0</td>
          <td>1687.0</td>
          <td>2476421.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALl1_ventral__7</td>
          <td>acetylcholine</td>
          <td>0.928285</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw035057</td>
          <td>FBbt_00067363</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>6</th>
          <td>78323779658618911</td>
          <td>720575940603231916</td>
          <td>112038</td>
          <td>56471</td>
          <td>1216</td>
          <td>100672.0</td>
          <td>54976.0</td>
          <td>1388.0</td>
          <td>2468593.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALl1_ventral__7</td>
          <td>acetylcholine</td>
          <td>0.938961</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw035224</td>
          <td>FBbt_00067363</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>7</th>
          <td>78464654585926444</td>
          <td>720575940605102694</td>
          <td>113795</td>
          <td>58276</td>
          <td>1223</td>
          <td>103744.0</td>
          <td>60904.0</td>
          <td>1295.0</td>
          <td>2532594.0</td>
          <td>intrinsic</td>
          <td>...</td>
          <td>ALl1_ventral__7</td>
          <td>acetylcholine</td>
          <td>0.899551</td>
          <td>acetylcholine</td>
          <td>Tanaka et al., 2012</td>
          <td>left</td>
          <td>NaN</td>
          <td>fw036329</td>
          <td>FBbt_00067363</td>
          <td>NaN</td>
        </tr>
      </tbody>
    </table>
    <p>8 rows × 27 columns</p>
    </div>



.. note::

    In above example we constructed a query against ``type``. This is a special
    argument that searches against all ``*_type`` fields in the annotations
    (i.e. currently against both ``cell_type`` and ``hemibrain_type``).

:class:`~fafbseg.flywire.NeuronCriteria` can also be passed to many other functions
that previously accepted only straight root IDs. For example, we can use it to
fetch all downstream partners of our neuron of interest:

.. code:: ipython3

    >>> ds = flywire.get_connectivity(NC(type='DA1_lPN', side='left'),
    ...                               upstream=False,
    ...                               downstream=True)
    >>> ds.head()


.. parsed-literal::

    Found 8 neurons matching the given criteria.
    Using materialization version 783.




.. 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>pre</th>
          <th>post</th>
          <th>weight</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>720575940605102694</td>
          <td>720575940646122804</td>
          <td>64</td>
        </tr>
        <tr>
          <th>1</th>
          <td>720575940603231916</td>
          <td>720575940629163931</td>
          <td>50</td>
        </tr>
        <tr>
          <th>2</th>
          <td>720575940603231916</td>
          <td>720575940635945919</td>
          <td>46</td>
        </tr>
        <tr>
          <th>3</th>
          <td>720575940603231916</td>
          <td>720575940646122804</td>
          <td>42</td>
        </tr>
        <tr>
          <th>4</th>
          <td>720575940614309535</td>
          <td>720575940635945919</td>
          <td>39</td>
        </tr>
      </tbody>
    </table>
    </div>



Or we can use it to fetch skeletons for all neurons of this type:

.. code:: ipython3

    >>> sk = flywire.get_skeletons(NC(type='DA1_lPN',
    ...                               side='left',
    ...                               materialization=783))
    >>> sk


.. parsed-literal::

    Found 8 neurons matching the given criteria.








.. raw:: html

    &lt;class 'navis.core.neuronlist.NeuronList'&gt; containing 8 neurons (827.5KiB)<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>skeleton</td>
          <td>720575940603231916</td>
          <td>3588</td>
          <td>None</td>
          <td>586</td>
          <td>645</td>
          <td>2050971.75</td>
          <td>[141, 458, 460, 462, 464, 466, 467, 469, 470, ...</td>
          <td>1 nanometer</td>
        </tr>
        <tr>
          <th>1</th>
          <td>navis.TreeNeuron</td>
          <td>skeleton</td>
          <td>720575940605102694</td>
          <td>4596</td>
          <td>None</td>
          <td>856</td>
          <td>971</td>
          <td>2598267.50</td>
          <td>[121, 125, 128, 130, 131, 149, 161, 173, 183, ...</td>
          <td>1 nanometer</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>6</th>
          <td>navis.TreeNeuron</td>
          <td>skeleton</td>
          <td>720575940626034819</td>
          <td>3519</td>
          <td>None</td>
          <td>522</td>
          <td>570</td>
          <td>1986607.75</td>
          <td>[15, 19, 21, 22, 239, 242, 384, 385, 387, 389,...</td>
          <td>1 nanometer</td>
        </tr>
        <tr>
          <th>7</th>
          <td>navis.TreeNeuron</td>
          <td>skeleton</td>
          <td>720575940637208718</td>
          <td>4143</td>
          <td>None</td>
          <td>688</td>
          <td>750</td>
          <td>2318905.00</td>
          <td>[280, 535, 656, 692, 729, 751, 829, 1355, 1396...</td>
          <td>1 nanometer</td>
        </tr>
      </tbody>
    </table>
    </div>



Please see the :ref:`API reference <api_annotations>` for a full list
of annotation-related functions.

A couple final notes
--------------------
Community annotations are pulled straight from CAVE and then cached for the duration
of your Python session.

The systematic annotations are downloaded from the Github repository for the
Schlegel *et al* annotation paper at `flyconnectome/flywire_annotations <https://github.com/flyconnectome/flywire_annotations>`_
(see `Supplemental_file1_neuron_annotations.tsv`) and subsequently cached on disk.

At the time of writing, the repository already contains 3 versions of the annotations
(`v1.0.0`, `v1.1.0` and `v2.0.0`; see "Releases" on the repository) and we're
planning to release new versions with updated labels in the future. By default,
``fafbseg`` will use the latest available data but you can also specify which
version you want to use (see :func:`~fafbseg.flywire.set_default_annotation_version`).

These annotation versions are _technically_ independent of the segmentation since
we can update the root IDs to match any materialization version - ``fafbseg``
is doing that for you under the hood. In practice, however, these labels were generated
using the segmentation at a specific point in time. For example, `v2.0.0` of
the annotations is based on materialization `783`. If you use them in conjunction
with a different materialization, you might find incorrect labels - in particular
if you use an earlier, less proofread materialization!

We would love to incorporate contributions from the community! If you find anything
wrong/missing or you would like to add e.g. your own cell types, please get in
touch either via email or via an issue in the Github repository.