fafbseg.flywire.NeuronCriteria

class fafbseg.flywire.NeuronCriteria(*, regex=False, case=False, verbose=True, dataset=None, annotation_version=None, materialization=None, **criteria)[source]

Parses filter queries into root IDs.

This class is typically passed as an argument to a function and will then be automatically converted into a list of root IDs.

Filtering for multiple criteria is done using a logical AND, i.e. only neurons that match all criteria will be selected.

Not providing any criteria will return all neurons in the hierarchical annotations table.

Parameters:

  • root_id (int | list of int) – List of root IDs to select. Note that root IDs are not checked for whether they actually existed at the requested materialization.

  • type (str | list of str) – Cell type(s) to select. Importantly this will search all *_type columns (e.g. cell_type, hemibrain_type). Note that you can also search against specific type columns directly (see examples).

  • side (str | list of str) – Side(s) to select.

  • nerve (str | list of str) – Nerve(s) to select.

  • flow (str | list of str) – Flow(s) to select.

  • super_class (str | list of str) – Super class(es) to select.

  • cell_class (str | list of str) – Cell class(es) to select.

  • cell_sub_class (str | list of str) – Cell sub class(es) to select.

  • ito_lee_hemilineage (str | list of str) – Hemilineage(s) to select.

  • morphology_group (str | list of str) – Morphology group(s) to select.

  • fbbt_id (str | list of str) – Virtual Fly Brain ID(s) to select.

  • community_annotation (str | list of str) – Community annotation(s) to select. It is recommended to use regex=True to search for partial matches (e.g. “.*Mi1.*”).

  • regex (bool) – Whether to interpret string criteria as regex.

  • case (bool) – Whether to interpret string criteria as case sensitive.

  • 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 ("live" | "latest" | int | bool, optional) – Which materialization version to search. By default, this is set to None and will get automatically adjusted to reflect the materialization version requested by the function the NeuronCriteria is passed to.

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

  • verbose (bool) – Whether to print information on which annotations were used.

Examples

>>> from fafbseg import flywire
>>> from fafbseg.flywire import NeuronCriteria as NC

Check which fields can be queried:

>>> NC.available_fields()
array(['root_id', 'flow', 'super_class', 'cell_class', 'cell_sub_class',
       'cell_type', 'hemibrain_type', 'ito_lee_hemilineage',
       'hartenstein_hemilineage', 'morphology_group', 'top_nt',
       'known_nt', 'side', 'nerve', 'fbbt_id', 'status', 'type',
       'community_annotation'], dtype='<U23')

Fetch all types for DA1 projection neurons (this searches all type columns):

>>> filter = NC(type='DA1_lPN')

Search specifically for a hemibrain type:

>>> filter = NC(hemibrain_type='DA1_lPN')

Search for multiple cell types:

>>> filter = NC(type=['DA1_lPN', 'DA1_vPN'])

Search for all ORNs:

>>> filter = NC(type='ORN_.*', regex=True)

Search for all ORNs on the left side of the brain:

>>> filter = NC(type='ORN_.*', side='left', regex=True)

Search for all neurons with a given community annotation:

>>> filter = NC(community_annotation='.*Mi1.*', regex=True)

Note that for community annotations you likely want to use regex to search for partial matches.

NeuronCriteria can also be passed directly to functions that accept multiple root IDs:

>>> cn = flywire.get_connectivity(NC(hemibrain_type='DA1_lPN'))
Using annotation version "latest tagged release" (327ae7b from 2024-01-10) from https://github.com/flyconnectome/flywire_annotations.
Found 15 neurons matching the given criteria.
Using materialization version 783.
>>> cn.head()
                pre                post  weight
0  720575940635945919  720575940605102694     106
1  720575940635945919  720575940637208718     106
2  720575940614956072  720575940630066007     104
3  720575940614956072  720575940621239679      89
4  720575940635945919  720575940619385765      87
__init__(*, regex=False, case=False, verbose=True, dataset=None, annotation_version=None, materialization=None, **criteria)[source]

Methods

__init__(*[, regex, case, verbose, dataset, ...])

available_fields()

Return all available fields for selection.

get_roots()

Return all root IDs matching the given criteria.

Attributes

annotations

Return hierarchical annotations.

community_annotations

Return community annotations for the given materialization.

is_empty

Returns True if no criteria are specified.