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=True, return_dataframe=True)

Generate JSON report of all subclasses of a given class expression.

Parameters:

class_expression – A valid OWL class expression, e.g., the name of a class.
query_by_label – Optional. Query using class labels if True, or IDs if False. Default True.
direct – Optional. Return only direct subclasses if True. Default False.
summary – Optional. Returns summary reports if True. Default True.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns a list of dicts. Default True.

Returns:

A DataFrame or list of terms as nested Python data structures following VFB_json or summary_report_json.

Return type:

pandas.DataFrame or list of dicts

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

Generate JSON report of all superclasses of a given class expression.

Parameters:

class_expression – A valid OWL class expression, e.g., the name of a class.
query_by_label – Optional. Query using class labels if True, or IDs if False. Default True.
direct – Optional. Return only direct superclasses if True. Default False.
summary – Optional. Returns summary reports if True. Default True.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns a list of dicts. Default True.

Returns:

A DataFrame or list of terms as nested Python data structures following VFB_json or summary_report_json.

Return type:

pandas.DataFrame or list of dicts

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

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

Parameters:

region – The name (rdfs:label) of the brain region (or CURIE style ID if query_by_label is False).
cells_only – Optional. Limits query to cell types if True. Default False.
verbose – Optional. If True, prints the running query and found terms. Default False.
query_by_label – Optional. Query using region labels if True, or IDs if False. Default True.
summary – Optional. Returns summary reports if True. Default True.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns a list of dicts. Default True.

Returns:

A DataFrame or list of terms as nested Python data structures following VFB_json or summary_report_json.

Return type:

pandas.DataFrame or list of dicts

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=True, direct=False, return_short_forms=True)

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. Default True

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=True, direct=False, return_short_forms=True)

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. Default True

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=True, return_dataframe=True)

Generate JSON report of all instances of a given 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. Query using class labels if True, or IDs if False. Default True.
summary – Optional. Returns summary reports if True. Default True.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns a list of dicts. Default True.

Returns:

A DataFrame or list of terms as nested Python data structures following VFB_json or summary_report_json.

Return type:

pandas.DataFrame or list of dicts

vfb_connect.cross_server_tools.VfbConnect.get_instances_by_dataset(self, dataset, summary=True, return_dataframe=True)

Get JSON report of all individuals in a specified dataset.

Parameters:

dataset – The dataset ID.
summary – Optional. Returns summary reports if True. Default True.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns a list of dicts. Default True.

Returns:

A DataFrame or list of terms as nested Python data structures following VFB_json or summary_report_json.

Return type:

pandas.DataFrame or list of dicts

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 the input neuron.

Parameters:

neuron – The neuron to find similar neurons to.
similarity_score – Optional. Specify the similarity score to use (e.g., ‘NBLAST_score’). Default ‘NBLAST_score’.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns list of dicts. Default True.

Returns:

A DataFrame or 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=True, direct=False, return_short_forms=True)

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. Default True

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.

Parameters:

class_expression – A valid OWL class expression, e.g., the name or symbol of a type of neuron (MBON01).
template – The template name.
image_folder – The folder to save image files and manifest to.
image_type – The image file extension (e.g., ‘swc’).
query_by_label – Optional. Query using class labels if True, or IDs if False. Default True.
direct – Optional. Return only direct instances if True. Default False.
stomp – Optional. Overwrite the image folder if it already exists. Default False.

Returns:

A manifest of downloaded images as a pandas DataFrame.

Return type:

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.

Parameters:

upstream_type – The upstream neuron type (e.g., ‘GABAergic neuron’).
downstream_type – The downstream neuron type (e.g., ‘Descending neuron’).
query_by_label – Optional. Specify neuron type by label if True (default) or by short_form ID if False.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns list of dicts. Default True.

Returns:

A DataFrame or list of synaptic connections between specified neuron types.

Return type:

pandas.DataFrame or 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 a specified neuron.

Parameters:

neuron – The name or ID of a particular neuron (dependent on query_by_label setting).
weight – Limit returned neurons to those connected by >= weight synapses.
classification – Optional. Restrict downstream neurons by classification.
query_by_label – Optional. Query neuron by label if True, or by ID if False. Default True.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns list of dicts. Default True.

Returns:

A DataFrame or list of neurons downstream of the specified neuron.

Return type:

pandas.DataFrame or list of dicts

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 a specified neuron.

Parameters:

neuron – The name or ID of a particular neuron (dependent on query_by_label setting).
weight – Limit returned neurons to those connected by >= weight synapses.
classification – Optional. Restrict upstream neurons by classification.
query_by_label – Optional. Query neuron by label if True, or by ID if False. Default True.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns list of dicts. Default True.

Returns:

A DataFrame or list of neurons upstream of the specified neuron.

Return type:

pandas.DataFrame or list of dicts

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 the specified cell type (or subtypes). Optionally restricts to a gene type, which can be retrieved using 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 retrieved using get_gene_function_filters.
return_dataframe – Optional. Returns pandas DataFrame if True, otherwise returns list of dicts. Default True.

Returns:

A DataFrame with gene expression data for clusters of cells annotated as the specified cell type.

Return type:

pandas.DataFrame or list of dicts

Raises:

KeyError – If the cell_type or gene_type is invalid.

vfb_connect.cross_server_tools.VfbConnect.get_gene_function_filters(self)

Get a 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, summary=True, cache=True, return_dataframe=True)

Generate a JSON report or summary for terms specified by a list of VFB IDs.

This method retrieves term information for a list of specified VFB IDs (short_forms). It can return either full metadata or a summary of the terms. The results can be returned as a pandas DataFrame if return_dataframe is set to True.

Parameters:

short_forms (iter) – An iterable (e.g., a list) of VFB IDs (short_forms).
summary – Optional. If True, returns a summary report instead of full metadata. Default is True.
cache – Optional. If True, attempts to retrieve cached results before querying. Default is True.
return_dataframe – Optional. If True, returns the results as a pandas DataFrame. Default is True.

Returns:

A list of term metadata as VFB_json or summary_report_json, or a pandas DataFrame if return_dataframe is True.

Return type:

list of dicts or pandas.DataFrame

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='', summary=True, return_dataframe=True)

Generate a JSON report for terms specified by a list of cross-reference IDs (xrefs).

This method maps external database IDs (xrefs) to VFB (Virtual Fly Brain) IDs and then retrieves detailed term information for those VFB IDs. The information can be returned either as a summary or as full term metadata.

Parameters:

acc – An iterable (e.g., a list) of external cross-reference IDs.
db – Optional. Specify the VFB ID (short_form) of an external database to map to. (Use get_dbs() to find options).
id_type – Optional. Specify an external ID type to filter the mapping results.
summary – Optional. Returns summary reports if True. Default is True.
return_dataframe – Optional. Includes related datasets in the report if True. Default is True.

Returns:

A list of term metadata as VFB_json or summary_report_json.

Return type:

list of dicts

Raises:

Warning – If no VFB ID is found for a given xref.

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

vfb_connect.neo.query_wrapper.QueryWrapper.get_template_TermInfo(self, short_forms, summary=True, return_dataframe=True)

Generate JSON reports for templates 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 templates
summary – Optional. Returns summary reports if True. Default True

Return type:

list of VFB_json or summary_report_json

vfb_connect.neo.query_wrapper.QueryWrapper.get_type_TermInfo(self, short_forms, summary=True, return_dataframe=True)

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 True

Return type:

list of VFB_json or summary_report_json

vfb_connect.neo.query_wrapper.QueryWrapper.get_anatomical_individual_TermInfo(self, short_forms, summary=True, return_dataframe=True)

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 True

Return type:

list of VFB_json or summary_report_json

vfb_connect.neo.query_wrapper.QueryWrapper.get_DataSet_TermInfo(self, short_forms, summary=True, return_dataframe=True)

Generate JSON reports for datasets 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 datasets
summary – Optional. Returns summary reports if True. Default True

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=True, return_dataframe=True)

Generate a report of all datasets available in the system.

This method retrieves all datasets and returns their information as either full JSON data structures or summaries. The results can be returned as a list of dictionaries or as a pandas DataFrame, depending on the return_dataframe flag.

Parameters:

summary – Optional. If True, returns summary reports instead of full metadata. Default is True.
return_dataframe – Optional. If True and summary is also True, returns the results as a pandas DataFrame. Default is True.

Returns:

A list of terms as nested Python data structures (VFB_json or summary_report_json), or a pandas DataFrame if return_dataframe is True and summary is True.

Return type:

list of dicts or pandas.DataFrame

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=True, return_dataframe=True)

Generate JSON report of all available templates.

Parameters:: summary – Optional. Returns summary reports if True. Default True
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.