API Reference

This document organises methods by their function. For a general introduction, please see our QuickStart documentation VFB_connect Quickstart Guide.

Introduction

It is sufficient to initialise a single VfbConnect object to get access to all the functions in VFB_connect acting on our default API endpoints (see code snippet below). VFB Semantic queries returning rich metadata on entities found (see output formats) are available via direct methods on VfbConnect. Semantic queries returning IDs only are available via methods on VfbConnect.oc (a shortcut to vfb_connect.owl.owlery_query_tools.OWLeryConnect.). Queries taking ID lists as input (see IDs_on_VFB) and returning rich metadata or mappings to/from external IDs are available via methods on VFBConnect.neo_query_wrapper (a shortcut to vfb_connect.neo.query_wrapper.QueryWrapper)

Direct queries of our neo4j endpoint are available via methods on vc.nc (a shortcut to vfb_connect.neo.neo4j_tools.Neo4jConnect). A guide to the VFB Neo4J schema and how to query it is in preparation.

from vfb_connect.cross_server_tools import VfbConnect
vc = VfbConnect()

# Semantic queries returning rich metadata on entities found
# methods directly on VfbConnect object.
# e.g.
vc.get_subclasses('DL1_adPN', summary=True)

# Semantic queries returning IDs only
# shortcut to vfb_connect.owl.owlery_query_tools.OWLeryConnect.get_subclasses
# e.g.
vc.oc.get_subclasses('DL1_adPN', summary=True)

# Queries taking ID lists as input and returning rich metadata or mappings
# shortcut to vfb_connect.neo.query_wrapper.QueryWrapper.get_TermInfo
# e.g.
vc.neo_query_wrapper.get_TermInfo(['FBbt_00003680'])

# Direct cypher query of the VFB neo4j database
# shortcut to vfb_connect.neo.neo4j_tools.Neo4jConnect.commit_list
# e.g.
vc.nc.commit_list(['MATCH (n:neuron:Class { symbol: 'DL1_adPN'}) RETURN n'])

Semantic queries for cell and anatomical types

Methods returning extended information about types

vfb_connect.cross_server_tools.VfbConnect.get_subclasses(self, class_expression, query_by_label=True, direct=False, summary=False)

Generate JSON report of all subclasses of class_expression.

Parameters

  • class_expression – A valid OWL class expression, e.g. the name of a class.

  • query_by_label – Optional. If false, class_expression takes IDs instead of labels Default True

  • direct – Return direct subclasses only. Default False

  • summary – Optional. Returns summary reports if true. Default False

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of VFB_json or summary_report_json

vfb_connect.cross_server_tools.VfbConnect.get_superclasses(self, class_expression, query_by_label=True, direct=False, summary=False)

Generate JSON report of all superclasses of class_expression.

Parameters

  • class_expression – A valid OWL class expression, e.g. the name of a class.

  • query_by_label – Optional. If false, class_expression takes IDs instead of labels Default True

  • direct – Return direct superclass only. Default False

  • summary – Optional. Returns summary reports if true. Default False

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of VFB_json or summary_report_json

vfb_connect.cross_server_tools.VfbConnect.get_terms_by_region(self, region, cells_only=False, verbose=False, query_by_label=True, summary=False)

Generate TermInfo reports for all terms relevant to annotating some specific region, optionally limited to cells.

Parameters

  • region – The name (rdfs:label) of brain region (or CURIE style ID if query_by_label is False)

  • cells_only – Optional. Limits query to cell type if True. Defaults to False

  • verbose – Optional.

  • query_by_label – Optional (see region). Default True

  • summary – Optional. Returns summary reports if true. Default False

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of VFB_json or summary_report_json

Methods returning IDs only. These methods are all accessible via VfbConnect.oc

vfb_connect.owl.owlery_query_tools.OWLeryConnect.get_subclasses(self, query, query_by_label=False, direct=False, return_short_forms=False)

Generate list of IDs of all subclasses of class_expression.

Parameters

  • class_expression – A valid OWL class expression, e.g. the name of a class.

  • query_by_label – Optional. If False`, class_expression takes CURIEs instead of labels. Default False

  • direct – Return direct subclasses only. Default False

  • return_short_forms – Optional. If True, returns short_forms instead of IRIs.

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of IRIs or short_forms (depending on return_short_form option)

vfb_connect.owl.owlery_query_tools.OWLeryConnect.get_superclasses(self, query, query_by_label=False, direct=False, return_short_forms=False)

Generate list of IDs of all superclasses of class_expression.

Parameters

  • class_expression – A valid OWL class expression, e.g. the name (or CURIE) of a class.

  • query_by_label – Optional. If False`, class_expression takes CURIEs instead of labels. Default False

  • direct – Return direct instances only. Default False

  • return_short_forms – Optional. If True, returns short_forms instead of IRIs.

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of IRIs or short_forms (depending on return_short_form option)

Semantic queries for individual neurons

Methods returning extended information about types

vfb_connect.cross_server_tools.VfbConnect.get_instances(self, class_expression, query_by_label=True, summary=False)

Generate JSON report of all instances of class_expression. Instances are specific examples of a type/class, e.g. a neuron of type DA1 adPN from the FAFB_catmaid database.

Parameters

  • class_expression – A valid OWL class expression, e.g. the name of a class.

  • query_by_label – Optional. If false, class_expression takes IDs instead of labels Default True

  • summary – Optional. Returns summary reports if true. Default False

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of VFB_json or summary_report_json

vfb_connect.cross_server_tools.VfbConnect.get_instances_by_dataset(self, dataset, summary=False)

Get JSON report of all individuals in a dataset

Parameters

  • dataset – dataset ID

  • summary – Optional. Returns summary reports if true. Default False

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of VFB_json or summary_report_json

vfb_connect.cross_server_tools.VfbConnect.get_similar_neurons(self, neuron, similarity_score='NBLAST_score', return_dataframe=True)

Get JSON report of individual neurons similar to input neuron

Parameters

  • neuron –

  • similarity_score – Optionally specify similarity score to chose

  • return_dataframe – Returns pandas dataframe if true, otherwise returns list of dicts.

Returns

list of similar neurons (id, label, tags, source (db) id, accession_in_source) + similarity score.

Return type

pandas.DataFrame or list of dicts

Methods returning IDs only. These methods are accessible via VfbConnect.oc

vfb_connect.owl.owlery_query_tools.OWLeryConnect.get_instances(self, query, query_by_label=False, direct=False, return_short_forms=False)

Generate list of IDs of all instances of class_expression.

Parameters

  • class_expression – A valid OWL class expression, e.g. the name of a class.

  • query_by_label – Optional. If False`, class_expression takes CURIEs instead of labels. Default False

  • direct – Return direct instances only. Default False

  • return_short_forms – Optional. If True, returns short_forms instead of IRIs.

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of IRIs or short_forms (depending on return_short_form option)

Queries for images

Semantic queries for images

vfb_connect.cross_server_tools.VfbConnect.get_images_by_type(self, class_expression, template, image_folder, image_type='swc', query_by_label=True, direct=False, stomp=False)

Download all images of individuals specified by a class expression, e.g. all images of the nodulus or of MBON01.

Parameters

  • class_expression – A valid OWL class expression, e.g. the name or symbol of a type of neuron (MBON01)

  • template – template name

  • image_folder – folder to save image files & manifest to.

  • image_type – image type (file extension)

  • stomp – Overwrite image_folder if already exists.

Returns

Manifest as Pandas DataFrame

(Note, this method can be accessed from VfbConnect.neo_query_wrapper)

vfb_connect.neo.query_wrapper.QueryWrapper.get_images(self, short_forms, template, image_folder, image_type='swc', stomp=False)

Given an iterable of short_forms for instances, find all images of specified image_type registered to template. Save these to image_folder along with a manifest.tsv. Return manifest as pandas DataFrame.

Parameters

  • short_forms (iter) – iterable (e.g. list) of VFB IDs of Individuals with images

  • template – template name

  • image_folder – folder to save image files & manifest to.

  • image_type – image type (file extension)

  • stomp – Overwrite image_folder if already exists.

Returns

Manifest as Pandas DataFrame

Connectivity queries

Methods for finding synaptic connections

vfb_connect.cross_server_tools.VfbConnect.get_connected_neurons_by_type(self, upstream_type, downstream_type, weight, query_by_label=True, return_dataframe=True)

Get all synaptic connections between individual neurons of upstream_type and dowstream_type where synapse count >= weight. Warning: Does not support Class Expressions.

Parm upstream_type

The upstream neuron type (e.g. ‘GABAeric neuron’).

Parameters

  • downstream_type – The upstream neuron type (e.g. ‘Descending neuron’).

  • query_by_label – specify neuron type by label if True (default) or by short_form id if False

  • return_dataframe – Returns pandas dataframe if true, otherwise returns list of dicts.

vfb_connect.cross_server_tools.VfbConnect.get_neurons_downstream_of(self, neuron, weight, classification=None, query_by_label=True, return_dataframe=True)

Get all neurons downstream of individual neuron

Parameters

  • neuron – the name or id of a particular neuron (dependent on query_by_label setting)

  • weight – limit returned neurons to those with connected by >= weight synapses

  • query_by_label – query neuron may be specified with a label if true

  • return_dataframe – Returns pandas dataframe if true, otherwise returns list of dicts.

Classification

optionally specify classification of downstream neuron using a class expression e.g. MBON

vfb_connect.cross_server_tools.VfbConnect.get_neurons_upstream_of(self, neuron, weight, classification=None, query_by_label=True, return_dataframe=True)

“Get all neurons downstream of individual neuron

Parameters

  • neuron – the name or id of a particular neuron (dependent on query_by_label setting)

  • weight – limit returned neurons to those with connected by >= weight synapses

  • query_by_label – query neuron may be specified with a label if true

  • return_dataframe – Returns pandas dataframe if true, otherwise returns list of dicts.

Classification

optionally specify classification of upstream neuron using a class expression e.g. MBON

ID conversion

Methods for converting between VFB_ids and external IDs, and vice versa (Note these methods can be accessed from VfbConnect.neo_query_wrapper For more information on IDs on VFB see IDs_on_VFB.

vfb_connect.neo.query_wrapper.QueryWrapper.vfb_id_2_xrefs(self, vfb_id, db='', id_type='', reverse_return=False)

Map a list of short_form IDs in VFB to external DB IDs

Parameters

  • vfb_id (iter) – An iterable (e.g. a list) of VFB short_form IDs.

  • db – optional specify the VFB id (short_form) of an external DB to map to. (use get_dbs to find options)

  • id_type – optionally specify an external id_type

  • reverse_return – Boolean: Optional (see return)

Returns

if reverse_return is False:

dict { VFB_id : [{ db: <db> : acc : <acc> }

Return if reverse_return is True:

dict { acc : [{ db: <db> : vfb_id : <VFB_id> }

vfb_connect.neo.query_wrapper.QueryWrapper.xref_2_vfb_id(self, acc=None, db='', id_type='', reverse_return=False)

Map a list external DB IDs to VFB IDs

Parameters

  • acc – An iterable (e.g. a list) of external IDs (e.g. neuprint bodyIDs).

  • db – optional specify the VFB id (short_form) of an external DB to map to. (use get_dbs to find options)

  • id_type – optionally specify an external id_type

  • reverse_return – Boolean: Optional (see return)

Returns

if reverse_return is False:

dict { acc : [{ db: <db> : vfb_id : <VFB_id> }

Return if reverse_return is True:

dict { VFB_id : [{ db: <db> : acc : <acc> }

Retrieving Term Information by ID

The methods can all be accessed from `VfbConnect.neo_query_wrapper`

Function for any type of VFB entity (slow for long lists)

vfb_connect.neo.query_wrapper.QueryWrapper.get_TermInfo(self, short_forms)

Generate JSON report for terms specified by a list of IDs

Parameters

  • short_forms (iter) – An iterable (e.g. a list) of VFB IDs (short_forms)

  • db – optionally specify the VFB id (short_form) of external DB.

  • id_type – optionally specify an external id_type

Returns

list of term metadata as VFB_json

Function for any type of VFB entity using an external ID

vfb_connect.neo.query_wrapper.QueryWrapper.get_terms_by_xref(self, acc, db='', id_type='')

Generate JSON report for terms specified by a list of IDs

Parameters

short_forms – An iterable (e.g. a list) of VFB IDs (short_forms)

Returns

list of term metadata as VFB_json

Functions by type (these are faster then the generic queries)

vfb_connect.neo.query_wrapper.QueryWrapper.get_template_TermInfo(self, short_forms)

Generate JSON reports for types from a list of VFB IDs (short_forms) of templates.

Parameters

  • short_forms – An iterable (e.g. a list) of VFB IDs (short_forms) of types

  • summary – Optional. Returns summary reports if True. Default False

Return type

list of VFB_json or summary_report_json

vfb_connect.neo.query_wrapper.QueryWrapper.get_type_TermInfo(self, short_forms, summary=False)

Generate JSON reports for types from a list of VFB IDs (short_forms) of classes/types.

Parameters

  • short_forms – An iterable (e.g. a list) of VFB IDs (short_forms) of types

  • summary – Optional. Returns summary reports if True. Default False

Return type

list of VFB_json or summary_report_json

vfb_connect.neo.query_wrapper.QueryWrapper.get_anatomical_individual_TermInfo(self, short_forms, summary=False)

Generate JSON reports for anatomical individuals from a list of VFB IDs (short_forms)

Parameters

  • short_forms – An iterable (e.g. a list) of VFB IDs (short_forms) of anatomical individuals

  • summary – Optional. Returns summary reports if True. Default False

Return type

list of VFB_json or summary_report_json

vfb_connect.neo.query_wrapper.QueryWrapper.get_DataSet_TermInfo(self, short_forms, summary=False)

Generate JSON reports for types from a list of VFB IDs (short_forms) of DataSets.

Parameters

  • short_forms – An iterable (e.g. a list) of VFB IDs (short_forms) of types

  • summary – Optional. Returns summary reports if True. Default False

Return type

list of VFB_json or summary_report_json

Retrieving all IDs for some specific type

vfb_connect.neo.query_wrapper.QueryWrapper.get_datasets(self, summary=False)

Generate JSON report of all datsets.

Parameters

summary – Optional. Returns summary reports if True. Default False

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of VFB_json or summary_report_json

vfb_connect.neo.query_wrapper.QueryWrapper.get_dbs(self)

Get a list of available database IDs

Returns

list of VFB IDs.

vfb_connect.neo.query_wrapper.QueryWrapper.get_templates(self, summary=False)

Generate JSON report of all available templates.

Parameters

summary – Optional. Returns summary reports if True. Default False

Returns

Returns a list of terms as nested python data structures following VFB_json or a summary_report_json

Return type

list of VFB_json or summary_report_json

Directly querying the VFB neo4j database

These functions are accessible under VFBConnect.nc

vfb_connect.neo.neo4j_tools.Neo4jConnect.commit_list(self, statements, return_graphs=False)

Commit a list of statements to neo4J DB via REST API. Errors prompt warnings (STDERR), not exceptions, and cause return = FALSE.

Param

statements: A list of cypher statements.

Param

return_graphs: Optional. Boolean. Returns graphs under ‘graph’ key if True. Default: False

Return

List of results or False if any errors are encountered.

vfb_connect.neo.neo4j_tools.Neo4jConnect.commit_list_in_chunks(self, statements, verbose=False, chunk_length=1000)

Commit multiple (chunked) commit of statements to neo4J DB via REST API. Errors prompt warnings (STDOUT), not exceptions, and cause return = FALSE.

Param

statements: A list of cypher statements.

Param

verbose: Boolean. Optionally print periodic reports of progress to STDOUT

Param

chunk_length. Int. Optional. Set chunk size. Default = 1000.

Return

List of results or False if any errors are encountered. Chunking is not reflected in results.