VFBquery

VFBquery is the query layer of Virtual Fly Brain (VFB) — the Drosophila nervous-system atlas. It turns the identifiers VFB users work with (FBbt_... anatomy classes, VFB_... individuals) into the rich, cross-referenced reports the VFB website shows: term metadata, aligned images, connectivity, transcriptomics, similar neurons, stocks and publications. It is both a Python package and the HTTP backend that serves those results to the VFB site and to third-party tools.

How it works

VFBquery sits in front of the VFB data stores and does the fan-out for you:

• Solr holds pre-built term_info documents and powers free-text search — most lookups are answered from here in milliseconds.
• Neo4j (the VFB knowledge graph) answers the relational questions: connectivity, cross-references, images by template, dataset membership.
• Owlery (an OWL reasoner) answers the ontology queries that need reasoning rather than lookup.
• A Solr-backed result cache stores computed results with a three-month TTL and version-based invalidation, so repeated queries are effectively instant — see CACHING.md.

The same functions are exposed two ways: imported as a Python package, or served over HTTP by the bundled high-availability server (vfbquery.ha_api), which adds request coalescing, queueing, backpressure and its own short-lived result cache. The VFB website's term-information panels are drawn from this service.

Install

pip install --upgrade vfbquery

Python 3.8+. Installing pulls the full server dependency set; if you only want to call a deployed HTTP API, the lightweight vfbquery-client needs just requests and pandas.

Quick start

import vfbquery as vfb

# Term information for an anatomy class or an individual neuron:
vfb.get_term_info('FBbt_00003748')            # medulla
vfb.get_term_info('VFB_00101567')             # JRC2018Unisex template

# The queries the website offers for a term, runnable directly, e.g.:
vfb.get_instances('FBbt_00003748', return_dataframe=False)

# Connectivity between neuron types:
vfb.query_connectivity(upstream_type='LPLC2', downstream_type='giant fiber neuron')

# Pass-through to the VFB-hosted CATMAID servers (FAFB, FANC, L1EM, ...),
# addressing neurons by skid or VFB id interchangeably:
from vfbquery import catmaid
catmaid('fafb').connectivity(ids=['VFB_001011rj'])
catmaid('fafb').swc(id='VFB_001011rj', aligned='JRC2018Unisex')

Every function is documented, with runnable examples, in the interactive API documentation described below, and in the Python client guide.

The HTTP API

python -m vfbquery.ha_api starts the server (default port 8080). Its root page is interactive API documentation in the style of the VFB-hosted CATMAID /apis/ pages: every endpoint with its parameters, pre-filled runnable examples, and live results — open / on any deployment, for example the production instance at https://v3-cached.virtualflybrain.org/. The machine-readable version is at /docs.json.

The endpoint surface mirrors the Python package: /get_term_info, /run_query, /search, /xref, /combine, /query_connectivity, /get_hierarchy, the FlyBase stock and combination resolvers, and the /catmaid/... pass-through. The full HTTP reference lives at vfbquery.readthedocs.io.

Documentation

• https://vfbquery.readthedocs.io — the documentation site: getting started, the Python client, the HTTP API, and the /combine reference.
• VFB_QUERIES_REFERENCE.md — every named query, its Cypher/Owlery source and its result schema.
• schema.md — the term_info result schema.
• CACHING.md — cache behaviour, configuration and invalidation.
• RELEASING.md — how releases and versioning work.
• performance.md — live performance figures, regenerated by CI.

Development

Tests live in src/test/ (package-level, run against the live VFB backend) and tests/ (HA-API unit tests). The canonical worked examples are a real test, src/test/test_example_queries.py: CI runs them against production and compares each result's shape to the recording in src/test/example_expected/, so the examples cannot rot; when a schema change is intentional, python -m src.test.test_example_queries --record refreshes the recordings. pip install -r requirements.txt -r tests/requirements.txt, then pytest.

Licence

GPL-3.0. Please cite Court et al. (2023), Virtual Fly Brain — an interactive atlas of the Drosophila nervous system when VFB data or services contribute to a publication.