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 downstream_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 upstream 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

Transcriptomics Queries

Methods for retrieving transcriptomics data

vfb_connect.cross_server_tools.VfbConnect.get_transcriptomic_profile(self, cell_type, gene_type=False, return_dataframe=True)

Get gene expression data for a given cell_type.

Returns a DataFrame of gene expression data for clusters of cells annotated as cell_type (or subtypes). Can optionally restrict to a gene_type - these can be retrieved by running get_gene_function_filters. If no data is found, returns False.

Parameters:

cell_type – The ID, name or symbol of a class in the Drosophila Anatomy Ontology (FBbt).
gene_type – Optional. A gene function label - these can be retrieved by running get_gene_function_filters().

Returns:

DataFrame with gene expression data for clusters of cells annotated as cell_type (or subtypes).

Return type:

DataFrame

vfb_connect.cross_server_tools.VfbConnect.get_gene_function_filters(self)

Get list of all gene function labels.

Returns:: List of unique gene function labels in alphabetical order.
Return type:: list

VFB link generation

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.