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 imagestemplate – 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.