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_infodocuments 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
/combinereference. - VFB_QUERIES_REFERENCE.md — every named query, its Cypher/Owlery source and its result schema.
- schema.md — the
term_inforesult 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.
Metadata
Release files for vfbquery 1.22.46
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vfbquery-1.22.46.tar.gz | 419.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vfbquery-1.22.46-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 809.8 kB
Release files / vfbquery-1.22.46.tar.gz
| Download URL | vfbquery-1.22.46.tar.gz |
|---|---|
| Size | 419.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3529eeffb01f8b721ffaded995a16b55e384668f346f5b9eafd422fdb5328233
|
|
BLAKE2b-256 checksum How to use checksums |
1f273e5c47b6574fd828a830e09d0de3c9b9b8e2405cfda8e7814893cddc6bb9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.1.1 CPython/3.12.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logRelease files / vfbquery-1.22.46-py3-none-any.whl
| Download URL | vfbquery-1.22.46-py3-none-any.whl |
|---|---|
| Size | 390.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1d43d4dd3efab6659c0617098f42794afedc108164abd31b3119a4720cc5f5e5
|
|
BLAKE2b-256 checksum How to use checksums |
2839f0ca589a730e6cd5a8661716bfa18f7335d9a25c361ba60b45252d083420
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.1.1 CPython/3.12.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency log
