vfbquery_client

The lightweight HTTP client. See the client guide for the behaviour that is not visible from a signature — DataFrame conventions, df.attrs, warnings and errors.

The package exports five names — VfbClient, VfbError, default_base_url, and the two base-URL constants — and each is documented below. There is deliberately no automodule block for the package itself: every one of those names is re-exported from vfbquery_client.client, and autodoc registers a re-export under both its public and its canonical path, so documenting the module and its members individually would register each of them twice and the -W docs build would fail on the collision. The explicit directives are the single registration.

VfbClient

class vfbquery_client.VfbClient(base_url=None, timeout=180, session=None)[source]

Bases: object

Parameters:
DEFAULT_TIMEOUT = 180

a broad neuron type expands over its subclasses into thousands of individuals, and a cold Tm1 -> T3 (4,915 against 5,430) has been measured at 30-60s end to end. The server caches the answer, so it is only ever the first caller who waits — but a default that times that caller out turns a slow query into an apparent outage, and the failure lands on whoever asked the broad question first, which in a workshop is everyone at once.

Type:

Read timeout in seconds. 180 rather than 60 because of connectivity

term(term)[source]

Full TermInfo for one id (GET /get_term_info).

Parameters:

term (str)

Return type:

dict

terms(terms)[source]
Parameters:

terms (Iterable[str])

Return type:

list

search(query, limit=50, rows=500, filter_types=None, exclude_types=None, boost_types=None, demote_types=None)[source]

Free-text term search (GET /search) — the website’s own ranked results.

Ranked, fuzzy, synonym/autosuggest-aware (‘DA1 lPN’, ‘kenyon’, partials, bare hemibrain bodyIds). This is the discovery entry point; see _resolve_to_id on why not resolve_entity.

Rows come back in the order the website shows them, because the server runs the website’s own query construction and comparator — with one deliberate difference. /search always adds an exact-label boost the website has no counterpart for, and there is no parameter to turn it off. It fixes a real website recall bug (searching neuron does not retrieve neuron into the candidate set at all), and it only ever lifts a term whose label is the query, so it changes retrieval rather than relative order: the recall gate holds top-10 churn at exactly zero. Treat “website order” as true of every query except one whose exact-label match the website was losing. Each row carries short_form, a display label (“synonym (label)” or “label (short_form)”), original_label, id, facets_annotation and unique_facets.

Parameters:
  • limit (int | None) – how many ranked rows to return (None for all).

  • rows (int) – how many candidates the server asks Solr for. A ranking knob — lowering it can drop the best answer before ranking sees it.

  • exclude_types (Iterable[str] | None) – keep / drop by facet (e.g. “Class”, “Individual”, “Neuron”).

  • demote_types (Iterable[str] | None) – nudge facets up / down the ranking.

  • query (str)

  • filter_types (Iterable[str] | None)

  • exclude_types

  • boost_types (Iterable[str] | None)

  • demote_types

Return type:

DataFrame

get_instances(class_expression)[source]

Individuals of a type across all datasets (run_query ListAllAvailableImages).

Parameters:

class_expression (str)

Return type:

DataFrame

get_subclasses(class_expression)[source]
Parameters:

class_expression (str)

Return type:

DataFrame

get_connected_neurons_by_type(upstream_type=None, downstream_type=None, weight=5, group_by_class=False, exclude_dbs=None)[source]

Type -> type synaptic connections (GET /query_connectivity).

Either side may be omitted, which asks the open-ended question: everything downstream of a type, or everything upstream of it.

A type includes its subclasses. "Kenyon cell" finds Kenyon cells, though none of the ~16,000 of them is typed to that class — they hang off its subclasses. The server does the expansion and reports what it covered.

weight is the minimum synapse count and is applied server-side; the default matches the server’s own so the threshold in the signature is the threshold that ran. Filtering here instead would be a second, weaker filter on top of an unstated one.

group_by_class aggregates to one row per class pair, with percent_connected and average_weight, rather than one row per pair of neurons.

exclude_dbs names connectome datasets to leave out, by symbol. The default — None, meaning the server’s own — drops hb and fafb, which double-count against datasets that are kept rather than being poor data: FAFB and FlyWire reconstruct the same EM volume, and hemibrain overlaps in type with FlyWire and male-CNS. Pass [] for every dataset, or exclude the others to isolate one; reproducing a published hemibrain figure needs that.

A type the server could not resolve comes back as a warning rather than an error, and an unresolved type is indistinguishable from a genuinely unconnected pair by looking at the rows — so warnings are re-raised as Python warnings instead of being dropped. That happens in _get for every endpoint, not here.

Parameters:
  • upstream_type (str | None)

  • downstream_type (str | None)

  • weight (int)

  • group_by_class (bool)

  • exclude_dbs (Iterable[str] | None)

Return type:

DataFrame

get_neuron_connectivity(neuron_id)[source]

Per-individual partners (run_query NeuronNeuronConnectivityQuery).

Parameters:

neuron_id (str)

Return type:

DataFrame

get_similar_neurons(neuron_id)[source]

NBLAST morphological matches (run_query SimilarMorphologyTo).

Parameters:

neuron_id (str)

Return type:

DataFrame

get_transcriptomic_profile(term)[source]

scRNAseq profile for an anatomy term (run_query anatScRNAseqQuery).

Parameters:

term (str)

Return type:

DataFrame

list_connectome_datasets()[source]
Return type:

DataFrame

xref(id=None, accession=None, db=None)[source]

VFB id <-> external accession, both ways (GET /xref).

Pass exactly one of id (VFB id -> every accession that term carries) or accession (external id -> the VFB term that carries it). db optionally narrows to one site and accepts its symbol (“hb”), short_form (“neuprint_JRC_Hemibrain_1point2point1”) or label.

Columns: id, label, db, db_label, site_id, accession, is_data_source, link.

The reverse direction is confirmed, not guessed: the server checks each candidate’s own xref list and returns a row only on an exact accession match. An accession that appears nowhere in VFB’s indexed text is therefore an empty frame rather than a plausible wrong neuron.

Parameters:
  • id (str | None)

  • accession (str | None)

  • db (str | None)

Return type:

DataFrame

combine(expr, operands=None, universe=None, limit=None, require_complete=False)[source]

Set algebra over the results of several queries (GET /combine).

Each name in expr is a query; the expression says how to combine their results. Rows are matched on each result’s own term-id column, so tables with completely different shapes still compare correctly:

vfb.combine("calyx AND lh", {
    "calyx": "NeuronsPartHere:FBbt_00007401",
    "lh":    "NeuronsPartHere:FBbt_00007053"})

Operators: OR AND NOT XOR NAND NOR XNOR, unary NOT, brackets ([], () or {}), symbols (| & - ^) and plain-English aliases (“but not”, “in both”, “either but not both”). Precedence, loosest binding first: OR/NOR, then XOR/XNOR, then AND/NAND/NOT — all left-associative. Bracket anything you would otherwise have to think about.

No column from any operand is dropped: the returned frame carries the union of every operand’s columns, plus found_in (which operands the row came from) and found_in_count. Where two operands disagree about the value of a shared column, both are kept, the second suffixed with its operand name.

The explanation travels with the frame in df.attrs: as_read (the grouping actually used — check it), plain_english, steps (every intermediate set size), operands, universe and count (the full size, which differs from len(df) when limit is set). Anything the server thinks is misleading — a truncated operand, two sides that can never intersect, a complement against an implicit universe — arrives as a Python warning.

Parameters:
  • expr (str) – the expression.

  • operands (dict | None) – {name: query}. A query is a string ('<QueryType>:<id>', 'search:<text>', 'ids:<id>,<id>'), a (query_type, id) pair, or any iterable of ids (a list, a set, a DataFrame column) — which is how one combination’s output becomes the next one’s input.

  • universe – what “everything” means, for NOT/NOR/NAND/XNOR. Same forms as an operand. Without it the universe is whatever the operands between them returned, which makes NOR always empty — the server warns when that matters.

  • limit (int | None) – return at most this many rows (attrs['count'] still reports the full size).

  • require_complete (bool) – fail with VfbError rather than warn if any operand came back truncated. Use it when the number is going in a paper.

Return type:

DataFrame

explain_combination(expr, operands=None, universe=None)[source]

How /combine would read an expression — without running anything.

Returns as_read (the bracketing that would be used) and plain_english (a sentence naming the actual queries). Cheap, because no query is run: worth calling first on any expression whose grouping you would otherwise be assuming.

Parameters:
  • expr (str)

  • operands (dict | None)

Return type:

dict

Build a virtualflybrain.org link that opens with these IDs loaded.

Parameters:
Return type:

str

Errors

class vfbquery_client.VfbError[source]

Bases: RuntimeError

Base URL

vfbquery_client.default_base_url()[source]

Resolved per call, not at import, so setting the variable in a test or a notebook cell takes effect without a reimport.

Return type:

str

vfbquery_client.PUBLIC_BASE_URL

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

vfbquery_client.DEFAULT_BASE_URL

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

PUBLIC_BASE_URL is the deployed service; DEFAULT_BASE_URL is what a bare VfbClient() uses. VFB_API_URL in the environment overrides both, which is how a workshop points a room at a private deployment without editing a notebook.