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

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

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

(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

Transcriptomics Queries

Methods for retrieving transcriptomics data

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.