fafbseg.flywire.search_annotations

fafbseg.flywire.search_annotations(x, exact=False, case=False, regex=True, clear_cache=False, annotation_version=None, materialization='auto', *, dataset=None)[source]

Search hierarchical annotations (super class, cell class, cell type, etc).

Annotations stem from Schlegel et al 2023 (bioRxiv); ~ corresponds to the “Classification” column in Codex.

This function downloads and caches the supplemental annotation table hosted on Github at https://github.com/flyconnectome/flywire_annotations. If you find any errors with the annotations, please open an issue on Github.

Parameters:

  • x (str | int | Neuron/List | list of ints | NeuronCriteria | None) – Term (str) or root ID(s) to search for. Use None to return all annotations. See examples and NeuronCriteria for details.

  • exact (bool) – Whether term must be an exact match. For example, if exact=False (default), ‘sensory’ will match to e.g. ‘sensory,olfactory’ or ‘AN sensory’.

  • case (bool) – If True (default = False), search for term will be case sensitive.

  • regex (bool) – Whether to interpret term as regex.

  • clear_cache (bool) – If True, will clear the cached annotation table(s).

  • annotation_version (str, optional) –

    Which version of the annotations to use. This should correspond to a tag (e.g. the “v1.1.0” release) or a branch of the annotation repository (see URL above).

    • if None (default), will use in order:

      1. The version set by flywire.set_default_annotation_version()

      2. The version set by environment variable FLYWIRE_DEFAULT_ANNOTATION_VERSION

      3. The latest tagged release available on the “main” branch

    • if latest_commit will use the latest available commit

    • if latest_tag will use the latest available tag (release)

    Please see the online tutorial on annotations for details.

  • materialization ("auto" | "live" | "latest" | int | bool) –

    Which materialization version to search:

    • ”auto”: if x are root ID(s), will try to find a version at which all root IDs co-existed; if x is string will use “latest” (see below)

    • ”latest”: uses the latest available materialization

    • integer: specifies a materialization version

    • ”live”: looks up the most recent root IDs from the supervoxels

  • dataset ("public" | "production", optional) – Against which FlyWire dataset to query. If None will fall back to the default dataset - see set_default_dataset().

Returns:

DataFrame with annotations matching x. Coordinates are in 4x4x40nm voxel space. An explanation for each column can be found here.

Return type:

pandas.DataFrame

See also

get_hierarchical_annotations()

Loads table with all hierarchical annotations.

search_community_annotations()

Searches specifically the community annotations.

NeuronCriteria

Helper to construct more complicated searches. Can also be passed directly to various other functions.

Examples

>>> from fafbseg import flywire

Find info for given root ID(s):

>>> an = flywire.search_annotations(720575940628857210)
Using materialization version 783.
>>> an.iloc[0]
supervoxel_id               78112261444987077
root_id                    720575940628857210
pos_x                                  109306
pos_y                                   50491
pos_z                                    3960
soma_x                               104904.0
soma_y                                47464.0
soma_z                                 5461.0
nucleus_id                          2453924.0
flow                                intrinsic
super_class                           central
cell_class                                NaN
cell_sub_class                            NaN
cell_type                                 NaN
hemibrain_type                          PS180
ito_lee_hemilineage            SMPpv2_ventral
hartenstein_hemilineage           CP1_ventral
morphology_group                          NaN
top_nt                          acetylcholine
top_nt_conf                          0.917977
side                                     left
nerve                                     NaN
vfb_id                               fw138205
fbbt_id                         FBbt_20001935
status                                    NaN
Name: 0, dtype: object

Search a term among all fields (this is a cell type):

>>> ps009 = flywire.search_annotations('PS009', exact=True)
Using materialization version 783.

You can use “colum:value” as shorthand to search a specific field:

>>> phn = flywire.search_annotations('nerve:PhN')
Using materialization version 783.

Use regex to refine search (here we try to find all “PSXXX” hemibrain types):

>>> all_ps = flywire.search_annotations('hemibrain_type:PS[0-9]{3}', regex=True)
Using materialization version 783.

Use NeuronCriteria for more more complicated queries:

>>> from fafbseg.flywire import NeuronCriteria as NC
>>> ann = flywire.search_annotations(NC(type='PS009', side='left'))
Found 1 neuron matching the given criteria.
Using materialization version 783.

Note that type in the above example will search against all *_type fields (e.g. both cell_type and hemibrain_type). See NeuronCriteria for details.