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:
base_url (Optional[str])
timeout (int)
session (Optional[requests.Session])
- 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
- 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_idon 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.
/searchalways 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 (searchingneurondoes 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 carriesshort_form, a displaylabel(“synonym (label)” or “label (short_form)”),original_label,id,facets_annotationandunique_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)
exclude_types
demote_types
- Return type:
- get_instances(class_expression)[source]¶
Individuals of a type across all datasets (run_query ListAllAvailableImages).
- 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.weightis 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_classaggregates to one row per class pair, withpercent_connectedandaverage_weight, rather than one row per pair of neurons.exclude_dbsnames connectome datasets to leave out, by symbol. The default —None, meaning the server’s own — dropshbandfafb, 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
_getfor every endpoint, not here.
- get_neuron_connectivity(neuron_id)[source]¶
Per-individual partners (run_query NeuronNeuronConnectivityQuery).
- get_similar_neurons(neuron_id)[source]¶
NBLAST morphological matches (run_query SimilarMorphologyTo).
- get_transcriptomic_profile(term)[source]¶
scRNAseq profile for an anatomy term (run_query anatScRNAseqQuery).
- 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) oraccession(external id -> the VFB term that carries it).dboptionally 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.
- 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
expris 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, unaryNOT, 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) andfound_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,universeandcount(the full size, which differs fromlen(df)whenlimitis 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
NORalways 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
VfbErrorrather than warn if any operand came back truncated. Use it when the number is going in a paper.
- Return type:
- explain_combination(expr, operands=None, universe=None)[source]¶
How
/combinewould read an expression — without running anything.Returns
as_read(the bracketing that would be used) andplain_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.
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:
- 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.