VFB APIs

• 1: Production Database (PDB) API
• 2: Knowledge Base (KB) API
• 3: Owlery API
• 4: SOLR Search API

1 - Production Database (PDB) API

The VFB Production Database (PDB) is the main Neo4j graph database containing integrated neuroanatomical data from multiple sources, including ontology data, expression patterns, image annotations, and connectivity information. It serves as the primary data store for comprehensive queries across VFB’s knowledge graph.

Browser Access

You can explore the PDB interactively using the Neo4j browser:

https://pdb.virtualflybrain.org/browser/

Data Structure Overview

The PDB contains over 1.1 million nodes and 43 million relationships, representing a comprehensive knowledge graph of Drosophila neuroanatomy. Below is an overview of the available node labels, relationship types, and property keys.

Node Labels (Gross Classifications)

The PDB uses hierarchical node labels to classify different types of entities:

Core Ontology Nodes:

• Class, Individual - OWL ontology elements
• Property - Relationships and attributes

Anatomical Classifications:

• Anatomy, Neuron, Glial_cell, Muscle, Sense_organ
• Nervous_system, Synaptic_neuropil, Ganglion, Neuromere
• Neuron_projection_bundle, Template

Cell Types and Lineages:

• Motor_neuron, Sensory_neuron, Neuroblast
• lineage_* (200+ lineage classifications for neural development)

Molecular and Functional:

• Gene, Expression_pattern, Clone, Feature
• Receptor, Channel, Transporter, Enzyme
• Neurotransmitter_receptor (Cholinergic, GABAergic, Glutamatergic, etc.)

Data and Metadata:

• DataSet, Sample, License, Person
• pub (Publications), Site, Template
• VFB, Deprecated, Individual

Dataset-Specific:

• FAFB, FlyCircuit, L1EM, FANC (Different connectome datasets)
• has_image, has_neuron_connectivity, has_region_connectivity

Relationship Types

The PDB defines 200+ relationship types for connecting entities:

Core Ontology Relationships:

• INSTANCEOF, SUBCLASSOF - Class hierarchies
• has_part, part_of - Anatomical composition
• located_in, overlaps - Spatial relationships

Connectivity Relationships:

• synapsed_to - Basic synaptic connections
• has_presynaptic_terminals_in, has_postsynaptic_terminal_in - Detailed synapse locations
• sends_synaptic_output_to_region, receives_synaptic_input_in_region - Functional connectivity
• synapsed_via_type_*_bouton_to - Specific bouton types

Developmental and Temporal:

• develops_from, develops_into - Developmental progression
• happens_during, existence_starts_during - Temporal relationships
• has_member - Group memberships

Functional and Molecular:

• expresses - Gene expression relationships
• has_role, capable_of - Functional classifications
• regulates, positively_regulates, negatively_regulates - Regulatory interactions

Metadata and Attribution:

• has_reference, created_by, has_license - Provenance
• database_cross_reference - External identifiers
• depicts - Image relationships

Property Keys

Properties provide additional metadata and attributes for nodes and relationships:

Identifiers and Labels:

• id, short_form, label, symbol, name
• iri, curie, unique_id

Descriptions and Definitions:

• definition, description, comment
• example_of_usage, elucidation

References and Attribution:

• PMID, PMCID, DOI, FlyBase
• created_by, creation_date, creator
• has_reference, miniref, pub

Spatial and Quantitative:

• center, orientation, volume, voxel
• Tbars, cell_count, cubic_micrometer_overlap
• NBLAST_score, neuronbridge_score

Quality and Status:

• confidence_value, curation_status
• is_obsolete, deprecated, hide_in_terminfo
• has_curation_status, obsolescence_reason

Technical Metadata:

• filename, link_base, thumbnail, nrrd, swc
• dataset_link, license_url, homepage

Query Examples

Note: These are direct Cypher queries for programmatic access to the PDB. The VFB web application typically uses higher-level query chains that combine multiple data sources and reasoning services. For user-friendly querying, use the VFB web interface.

Find all expression patterns for a gene

MATCH (ep:Expression_pattern)-[:expresses]->(gene:Gene {symbol: 'gene_name'})
RETURN ep

Find neurons with presynaptic terminals in a brain region

MATCH (neuron:Neuron)-[:has_presynaptic_terminals_in]->(region:Synaptic_neuropil {label: 'antennal lobe'})
RETURN neuron, region

Find neurons with specific neurotransmitter types

MATCH (neuron:Neuron)-[:INSTANCEOF]->(type:Class)
WHERE type.label CONTAINS 'GABAergic'
RETURN neuron, type

Find neurons in a specific lineage

MATCH (neuron:Neuron)-[:INSTANCEOF]->(type:Class)-[:has_member]->(lineage)
WHERE lineage:lineage_DL1
RETURN neuron, type, lineage

Find synaptic connections between neurons

MATCH (n1:Neuron)-[syn:synapsed_to]->(n2:Neuron)
WHERE n1:FAFB AND n2:FAFB
RETURN n1, syn, n2
LIMIT 10

Find neurons by morphology similarity (NBLAST)

MATCH (n1:Neuron)-[sim:has_similar_morphology_to]->(n2:Neuron)
WHERE sim.NBLAST_score[0] > 0.8
RETURN n1, n2, sim.NBLAST_score[0] AS score
ORDER BY score DESC
LIMIT 10

Find anatomical parts of a brain region

MATCH (part:Anatomy)-[:part_of]->(region:Anatomy {label: 'adult brain'})
RETURN part

Find genes expressed in a specific cell type

MATCH (gene:Gene)<-[:expresses]-(ep:Expression_pattern)-[:overlaps]->(cell:Neuron)
WHERE cell.label CONTAINS ' Kenyon cell '
RETURN DISTINCT gene, ep

Schema Details

OLS OWL Representation

The core schema follows OLS conventions for representing OWL in Neo4j:

• Classes are represented as nodes with label Class
• Individuals as nodes with label Individual
• Properties as nodes with label Property
• Relationships use Related edges with property labels

Denormalizations

For query performance, the schema includes denormalized named relationships alongside the generic Related edges. This allows efficient pattern matching without attribute filtering.

Expression Data Model

Expression patterns are modeled as:

(ep:Class:Expression_pattern)-[:SUBCLASSOF]->(:Class {label: 'expression pattern'})
(ep)-[:expresses]->(gene:Class)
(ep)<-[:INSTANCEOF]-(individual:Individual)
(ep)-[:overlaps]->(anatomy:Class)

Connectivity Data

Synaptic connections are represented as:

(neuron1:Individual)-[:synapsed_to {count: N}]->(neuron2:Individual)

Or with detailed synapse partonomy using GO terms.

Data Sources

The PDB integrates data from:

• FlyBase (ontology terms, features, annotations)
• VFB Knowledge Base (connectivity data)
• External ontologies (FBbt, GO, etc.)
• Image datasets and annotations
• Third-party connectivity datasets
• Expression pattern data

Updates and Maintenance

The PDB is updated regularly to incorporate new data releases and maintain consistency with upstream sources.

2 - Knowledge Base (KB) API

The VFB Knowledge Base (KB) is a specialized Neo4j database focused on storing large-scale connectivity data. Due to the size and complexity of modern connectomes, most ontology data, expression patterns, and other integrated content has been moved to the Production Database (PDB). The KB now serves as a dedicated repository for synaptic connectivity information and related annotations.

Browser Access

Explore the KB using the Neo4j browser:

https://kb.virtualflybrain.org/browser/

Purpose and Scope

The KB serves as:

1. Connectivity Data Repository: Primary storage for synaptic connectivity information from large-scale connectomes
2. VFB-Specific Annotations: Annotations and metadata related to connectivity data

Note: Ontology data, expression patterns, image annotations, and other integrated content are now stored in the Production Database (PDB) to handle the growing size and complexity of modern connectomes.

Data Types

Connectivity Data

VFB stores connectivity data at multiple levels:

1. Neo4j Graph Storage: Detailed synaptic connectivity in the KB graph database
2. OWL Ontology Files: Connectomic data exported as OWL files for semantic interoperability

OWL Connectivity Files: Available at https://virtualflybrain.org/data/VFB/OWL/raw/ (connectome_*.owl files)

Two levels of representation in Neo4j:

1. Crude Connectivity: Simple triples A synapsed_to B with synapse counts
2. Detailed Synapses: Individual synapse partonomy using GO terms (3 individuals per synapse)

Note: Image annotations, ontology data, and expression patterns are now stored in the Production Database (PDB).

Schema Requirements

The KB schema is designed with specific requirements:

• Updateability: Ontology terms and FlyBase features must be updateable via CI
• ID Stability: Derived class IDs (e.g., expression patterns) must be preserved during updates
• OWL Compatibility: Subset of content convertible to OWL using standard patterns
• Dataset Isolation: Ability to generate OWL files for individual datasets

Expression Patterns

Expression patterns in the KB follow the general semantic specification:

• Definition: Mereological sum of all cells in an anatomical structure expressing a gene/transgene
• Classification: Hierarchical organization via OWL reasoning
• Stability: IDs must remain stable across updates

Pattern Types

• Complete Expression Pattern: All cells in an organism expressing a gene
• Regional Expression Pattern: Subset of expression in specific anatomical regions

Integration with PDB

The KB and PDB work together in VFB’s data architecture:

• KB: Specialized storage for large-scale connectivity data and related annotations
• PDB: Integrated storage for ontology data, expression patterns, image annotations, and cross-referenced information
• Data Flow: Connectivity data from KB is integrated with other data types in PDB for comprehensive queries

Query Patterns

Connectivity Queries

MATCH (neuron1:Individual)-[syn:synapsed_to]->(neuron2:Individual)
RETURN neuron1, syn, neuron2

Synapse Detail Queries

MATCH (neuron:Individual)-[:has_presynaptic_terminal_in]->(region:Class)
RETURN neuron, region

Note: For queries involving ontology data, expression patterns, or image annotations, use the Production Database (PDB).

Maintenance and Updates

The KB is maintained through:

• Manual curation workflows
• Automated data loading pipelines
• Integration with external data sources
• Quality control and validation processes

For more details on the underlying schema, see the VFB Neo4j documentation.

3 - Owlery API

The Owlery API is VFB’s OWL (Web Ontology Language) reasoning service, providing advanced query capabilities over the ontologies used in VFB. It enables Description Logic (DL) queries, SPARQL queries with OWL reasoning, and access to multiple knowledgebases.

API Endpoint

Base URL: https://owl.virtualflybrain.org/kbs/vfb/

Note: VFB provides a single knowledgebase (vfb) containing all VFB ontologies and reasoning data.

DL Queries (Description Logic)

Owlery provides standard OWL DL query operations for reasoning over class hierarchies and relationships.

Subclasses

GET /kbs/vfb/subclasses/{class}

Get all subclasses of a named class or class expression.

Parameters:

• class: Class IRI or expression

Query Parameters:

• direct: true for direct subclasses only (default: false)

Superclasses

GET /kbs/vfb/superclasses/{class}

Get all superclasses of a named class or class expression.

Equivalent Classes

GET /kbs/vfb/equivalent/{class}

Get classes equivalent to the specified class.

Instances

GET /kbs/vfb/instances/{class}

Get all instances (individuals) of a class.

Types

GET /kbs/vfb/types/{individual}

Get all types (classes) of a named individual.

Satisfiability

GET /kbs/vfb/satisfiable/{class}

Check if a class expression is satisfiable (consistent).

SPARQL Services

Owlery provides SPARQL query capabilities with OWL reasoning support.

SPARQL Endpoint

GET /kbs/vfb/sparql?query={sparql_query}
POST /kbs/vfb/sparql

Execute SPARQL queries with OWL reasoning. Supports Owlet-style embedded class expressions.

Query Parameters (GET):

• query: URL-encoded SPARQL query

Request Body (POST):

• Content-Type: application/sparql-query
• Body: SPARQL query text

SPARQL Query Expander

GET /kbs/vfb/expand?query={sparql_query}
POST /kbs/vfb/expand

Expand a SPARQL query by transforming Owlet-style embedded class expressions into FILTER clauses.

VFB Query Integration

Owlery is extensively used in VFB’s high-level query chains. The following table shows how VFB’s named query operations map to Owlery API endpoints:

Common VFB Query Patterns

Find all anatomical subclasses of the adult brain

GET /kbs/vfb/subclasses/FBbt_00003624

Used in: PartsOf, SubclassesOf queries

Find all neurons that are part of a specific type

GET /kbs/vfb/instances/FBbt_00005106

Used in: NeuronsPartHere, neuron classification queries

Find all synaptic neuropils in the brain

GET /kbs/vfb/subclasses/FBbt_00005106?direct=true

Used in: NeuronsSynaptic, connectivity queries

Check if a class expression is valid

GET /kbs/vfb/satisfiable/FBbt_00003624

Used in: Query validation and reasoning checks

Complex Query Examples

Many VFB queries combine Owlery with other services. For example, the “Neurons with presynaptic terminals in antennal lobe” query typically involves:

1. Owlery reasoning: Find anatomical subclasses of the antennal lobe
2. Neo4j lookup: Find neurons with presynaptic terminals in those regions
3. SOLR search: Retrieve associated images and metadata

While these complex queries are handled by VFB’s query orchestration system, the individual Owlery components can be called directly for custom analyses.

Usage Examples

Note: VFB supports both full IRIs (e.g., http://purl.obolibrary.org/obo/FBbt_00003624) and short forms (e.g., FBbt_00003624) for class identifiers.

Basic Ontology Queries

Find all parts of the adult brain

GET /kbs/vfb/subclasses/FBbt_00003624
# or using full IRI:
GET /kbs/vfb/subclasses/http://purl.obolibrary.org/obo/FBbt_00003624

Find all neurons in the antennal lobe

GET /kbs/vfb/instances/FBbt_00007484

Find all synaptic neuropil subclasses

GET /kbs/vfb/subclasses/FBbt_00005106

SPARQL Reasoning Examples

Find GABAergic neurons using OWL reasoning

PREFIX owl: <http://www.w3.org/2002/07/owl#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT ?neuron ?label
WHERE {
  ?neuron rdfs:subClassOf <http://purl.obolibrary.org/obo/FBbt_00005106> .
  ?neuron rdfs:label ?label .
  FILTER(CONTAINS(?label, "GABA"))
}

Find anatomical parts with expression data

PREFIX owl: <http://www.w3.org/2002/07/owl#>
SELECT ?part ?expression
WHERE {
  ?part rdfs:subClassOf <http://purl.obolibrary.org/obo/FBbt_00003624> .
  ?expression <http://purl.obolibrary.org/obo/RO_0002292> ?part .
}

Response Formats

Owlery returns results in JSON format by default. Available formats include:

• application/json (default)
• text/plain
• application/rdf+xml
• text/turtle

Specify format using the Accept header or format query parameter.

Error Handling

Owlery returns standard HTTP status codes:

• 200: Success
• 400: Bad request (invalid query/parameters)
• 404: Knowledgebase or resource not found
• 500: Server error

Error responses include JSON with error details:

{
  "error": "Error message",
  "details": "Additional information"
}

Integration with VFB

Owlery is a core component of VFB’s query system, providing the reasoning capabilities that power complex anatomical and connectivity queries. It’s used in combination with the PDB (Neo4j) and SOLR search services to deliver comprehensive results to users.

4 - SOLR Search API

The SOLR Search API powers VFB’s search and autocomplete functionality, providing fast text-based queries across all VFB entities including anatomical terms, neurons, datasets, publications, and more.

Note: Search and autocomplete functionality is also built into VFBconnect by default. The vfb.term() method will automatically attempt to match partial terms and provide autocomplete suggestions. See the VFBconnect documentation for programmatic access.

API Endpoint

Base URL: https://solr.virtualflybrain.org/solr/ontology/select

Note: VFB uses JSON-formatted parameter requests for complex queries.

Search Parameters

Core Search Parameters

Query Field Boosting (qf)

VFB uses sophisticated field boosting for optimal search results:

• label^110 - Primary labels get highest boost
• synonym^100 - Synonyms get high boost
• label_autosuggest - Autosuggest-optimized labels
• synonym_autosuggest - Autosuggest-optimized synonyms
• shortform_autosuggest - Autosuggest-optimized short forms

Query Expansion

VFB automatically expands search terms for better matching:

• Original term: medulla
• Expanded to: (medulla OR medulla* OR *medulla OR *medulla*)

This catches prefix, suffix, and infix matches.

Filter Queries (fq)

VFB applies specific filter queries to focus results on relevant entities:

fq=(short_form:VFB* OR short_form:FB* OR facets_annotation:DataSet OR facets_annotation:pub) AND NOT short_form:VFBc_*

This filter includes:

• VFB entities (VFB*) including anatomical individuals (VFB_*), expression patterns (VFBexp*), and extension ontology terms (VFBext*)
• FlyBase entities (FB*)
• Datasets (facets_annotation:DataSet)
• Publications (facets_annotation:pub)

And excludes:

• VFB image channel node entries (VFBc_*) - as opposed to anatomical individuals (VFB_*)

Boost Parameters (bq)

VFB uses boost queries to prioritize certain types of results:

bq=short_form:VFBexp*^10.0 short_form:VFB*^100.0 short_form:FBbt*^100.0 short_form:FBbt_00003982^2 facets_annotation:Deprecated^0.001 facets_annotation:DataSet^500.0 facets_annotation:pub^100.0

Boost Priorities:

• Expression patterns (VFBexp*): 10x boost
• VFB entities (VFB*): 100x boost
• Anatomy terms (FBbt*): 100x boost
• Adult brain (FBbt_00003982): 2x boost
• Datasets: 500x boost
• Publications: 100x boost
• Deprecated items: 0.001x (demoted)

Additional Parameters

Response Format

JSON Response Structure

{
  "responseHeader": {
    "status": 0,
    "QTime": 15,
    "params": {...}
  },
  "response": {
    "numFound": 1234,
    "start": 0,
    "docs": [
      {
        "short_form": "FBbt_00007484",
        "label": "antennal lobe",
        "synonym": ["antennal lobe"],
        "id": "http://purl.obolibrary.org/obo/FBbt_00007484",
        "facets_annotation": ["Adult", "Nervous_system"],
        "unique_facets": ["adult antennal lobe", "nervous system"]
      }
    ]
  }
}

Field Descriptions

Search Examples

JSON Parameter Format (VFB Standard)

VFB uses JSON-formatted parameter requests for complex queries:

GET /solr/ontology/select?json={"params":{"q":"(medulla OR medulla* OR *medulla OR *medulla*)","q.op":"OR","defType":"edismax","mm":"45%","qf":"label^110 synonym^100 label_autosuggest synonym_autosuggest shortform_autosuggest","indent":"true","fl":"short_form,label,synonym,id,facets_annotation,unique_facets","start":"0","pf":"true","fq":["(short_form:VFB* OR short_form:FB* OR facets_annotation:DataSet OR facets_annotation:pub) AND NOT short_form:VFBc_*"],"rows":"150","wt":"json","bq":"short_form:VFBexp*^10.0 short_form:VFB*^100.0 short_form:FBbt*^100.0 short_form:FBbt_00003982^2 facets_annotation:Deprecated^0.001 facets_annotation:DataSet^500.0 facets_annotation:pub^100.0"}}

URL-Encoded Parameters (Alternative)

For simpler queries, you can use traditional URL parameters:

GET /solr/ontology/select?q=medulla&fl=short_form,label,synonym,id&rows=10&wt=json

Autocomplete Query Example

The medulla autocomplete query expands to match various forms:

Query Breakdown:

• q: (medulla OR medulla* OR *medulla OR *medulla*) - Matches medulla at start, middle, or end
• defType: edismax - Extended dismax query parser for complex queries
• mm: 45% - At least 45% of query terms must match
• qf: Field boosting for optimal relevance
• fq: Filters to include relevant entities only
• bq: Boosts for prioritizing certain result types

Simple Search Examples

Basic term search

GET /solr/ontology/select?q=antennal&rows=10&wt=json&fl=short_form,label

Dataset search

GET /solr/ontology/select?q=dataset&fq=facets_annotation:DataSet&rows=20&wt=json

Publication search

GET /solr/ontology/select?q=connectome&fq=facets_annotation:pub&rows=10&wt=json

Autocomplete Usage

VFB’s autocomplete functionality uses this SOLR API with specific parameters optimized for fast, relevant suggestions:

Autocomplete Query

GET /solr/vfb_olympiad/select?q=antennal&fl=short_form,label,synonym,id,facets_annotation,unique_facets&start=0&rows=150&wt=json&pf=true&fq=(short_form:VFB*%20OR%20short_form:FB*%20OR%20facets_annotation:DataSet%20OR%20facets_annotation:pub)%20AND%20NOT%20short_form:VFBc_*&bq=short_form:VFBexp*^10.0%20short_form:VFB*^100.0%20short_form:FBbt*^100.0%20short_form:FBbt_00003982^2%20facets_annotation:Deprecated^0.001%20facets_annotation:DataSet^500.0%20facets_annotation:pub^100.0

Integration with VFB

The SOLR API is a core component of VFB’s search infrastructure:

1. Web Interface: Powers the main search box and autocomplete
2. Query Chains: Used in combination with PDB and Owlery queries
3. Result Ranking: Complex sorting logic prioritizes relevant results
4. Facet Filtering: Enables filtering by categories like “Adult”, “Larva”, etc.

Result Processing

VFB applies additional client-side processing to SOLR results:

• Sorting: Custom ranking based on match quality and entity type
• Deduplication: Removes duplicate entries
• Facet Processing: Converts facet annotations to user-friendly labels

Performance Notes

• Caching: VFB implements caching for frequently searched terms
• Pagination: Use start and rows for large result sets
• Query Optimization: Complex queries may benefit from the pf (phrase fields) parameter
• Rate Limiting: Consider implementing delays between rapid autocomplete requests

Error Handling

SOLR returns standard HTTP status codes:

• 200: Success
• 400: Bad request (malformed query)
• 500: Server error

Error responses include details in the response header.