Metadata-Version: 2.1
Name: vfbquery
Version: 1.22.43
Summary: Wrapper for querying VirtualFlyBrain knowledge graph.
Home-page: https://github.com/VirtualFlyBrain/VFBquery
Author: VirtualFlyBrain
License: GPL-3.0 License
Project-URL: Documentation, https://vfbquery.readthedocs.io/en/stable/
Project-URL: Bug Reports, https://github.com/VirtualFlyBrain/VFBquery/issues
Project-URL: Source, https://github.com/VirtualFlyBrain/VFBquery
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pysolr
Requires-Dist: pandas
Requires-Dist: marshmallow
Requires-Dist: vfb-connect
Requires-Dist: aiohttp
Requires-Dist: dataclasses-json
Requires-Dist: dacite
Requires-Dist: requests
Requires-Dist: psycopg[binary]>=3.0

# VFBquery

[![PyPI](https://img.shields.io/pypi/v/vfbquery)](https://pypi.org/project/vfbquery/)
[![Documentation](https://readthedocs.org/projects/vfbquery/badge/?version=stable)](https://vfbquery.readthedocs.io/en/stable/)

VFBquery is the query layer of [Virtual Fly Brain](https://virtualflybrain.org)
(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](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`](clients/vfbquery-client/) needs just `requests` and
`pandas`.

## Quick start

```python
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](https://vfbquery.readthedocs.io/en/stable/python-client.html).

## 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](https://fafb.catmaid.virtualflybrain.org/apis/):
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](https://vfbquery.readthedocs.io/en/stable/http-api.html).

## Documentation

- <https://vfbquery.readthedocs.io> — the documentation site: getting
  started, the Python client, the HTTP API, and the `/combine` reference.
- [VFB_QUERIES_REFERENCE.md](VFB_QUERIES_REFERENCE.md) — every named query,
  its Cypher/Owlery source and its result schema.
- [schema.md](schema.md) — the `term_info` result schema.
- [CACHING.md](CACHING.md) — cache behaviour, configuration and invalidation.
- [RELEASING.md](RELEASING.md) — how releases and versioning work.
- [performance.md](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`](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*](https://www.frontiersin.org/journals/physiology/articles/10.3389/fphys.2023.1076533/full)
when VFB data or services contribute to a publication.
