FlyLab

Provenance-first computational pharmacology on a synapse-resolution Drosophila connectome.

FlyLab links typed receptor evidence to named circuits in the public MaleCNS connectome, simulates compound-specific perturbations, and then asks a question most circuit simulators leave implicit:

Did the predicted effect actually need the wiring?

Open the browser bench · Tutorial · How to read the output · Documentation · Research paper

Research status: FlyLab is a computational methods and scientific-software project. It currently evaluates model behaviour, not biological efficacy or safety. No live-animal results are generated by the software, and there is no independent circuit-level biological validation yet.

What FlyLab does

A FlyLab run starts with a compound and a free concentration.

compound + concentration
        |
        v
typed pharmacological evidence
(Kd / Ki / EC50 / IC50 / unsupported)
        |
        +-------------------------> vertebrate receptor scorecard
        |                           same concentration, no vertebrate circuit
        v
mechanism -> gain transformation
        |
        v
named MaleCNS circuit
(MN9, DNp01, labellar GRNs)
        |
        +--> deterministic rate model
        +--> leaky integrate-and-fire model
        |
        v
readouts + notebook + provenance
        |
        v
dependence | ablation | robustness | uncertainty

The result is not just a simulated firing rate. FlyLab records what evidence entered the model, which assumptions transformed it, which graph was used, and how strongly the prediction depends on those choices.

The browser bench saves your primary run and experiment-design settings in the current browser. Use Export setup and Import setup to share those settings as a versioned JSON preset; the preset contains inputs, not calculated results. On narrow screens, the two tab rows collapse into one grouped panel picker.

Why it is different

1. Evidence is typed, not flattened into one fake "EC50" field

The pharmacology library records the kind of quantity reported by the source, its species and receptor relationship, and its evidence tier. Unsupported receptor rows stay missing instead of becoming convenient small numbers.

Functional potency and binding affinity are therefore distinguishable in the exported result, and every numeric row carries its source context.

2. The connectome has to earn its place

FlyLab compares a prediction on the MaleCNS cut with ensembles of degraded graphs that preserve different amounts of network information.

The analysis asks whether the real-graph effect is distinguishable from null ensembles that preserve, for example:

• only graph size, weight distribution and transmitter composition,
• node degree and transmitter identity,
• the real edge list with shuffled weights,
• the real weighted graph with transmitter labels permuted at matched out-strength, so each transmitter's share of total synaptic weight is held fixed.

A plain label permutation is also run, but it moves the weighted excitation/inhibition balance as well as transmitter identity, so it is reported as a joint null rather than as a rung of the ladder.

This makes it possible to separate effects that are sensitive to detailed wiring from effects that are already explained by much coarser network information. Failing to distinguish an effect from a null is reported as exactly that: each mode carries a three-way verdict against a prespecified equivalence margin, and "not distinguishable" is never rendered as "the degraded graph reproduces the effect".

The ladder itself is validated rather than assumed to work. A recurrent loop of known strength is planted in a synthetic graph of the same size, density and transmitter composition as a real cut, and the analysis is asked to find it; the unplanted control gives an empirical false-positive rate, and a power surface maps detection against effect size and permutation count.

The verdict this analysis returns depends on the extract it is measured on. The saved scale study associates the change more with recurrence than node count, but it does not isolate a causal structural feature. The repository's two committed cuts disagree: the same landscape classifies most cells composition-dominated on the sparse 1-hop named cut and none of them on the denser taste_motor cut. Across the saved 1k–50k ladder, only the named in-star is composition-dominated; scale_1k has fewer nodes but twenty times its mean degree and is already topology-dependent. At 5k and 10k the imidacloprid effect is distinguishable from all three ranked edge/wiring nulls; transmitter-label shuffles are separate and indeterminate at some rungs. The larger scale cut files are absent from this checkout, so those results remain imported observations. Quote any dependence result with the structure of the graph it was measured on.

3. Model conclusions are stress-tested

FlyLab includes:

Analysis	Question
Connectome-dependence analysis	Is the real-graph prediction distinguishable from degraded graph ensembles?
Ablation ladder	Which layer carries the ordering information: receptor evidence, transmitter composition, topology, or the full model?
Specification robustness	Does a qualitative conclusion survive alternative engagement-to-gain rules?
Global uncertainty	Which assumptions dominate variance in a model output?
Value of information	Which measurement or re-analysis would reduce the most model uncertainty?
Claim provenance	Which links in a result are observations, literature-derived inputs, modelling assumptions, or computations?
Scale ladder	How do dependence verdicts vary across saved extracts of different sizes and structure?

Negative results are first-class outputs. If a conclusion depends on an asserted gain rule, or a connectome-specific interpretation is not supported by the null analysis, FlyLab is designed to show that rather than hide it.

4. One scientific core, several ways to run it

The same Python science core is exposed through:

• a command-line interface,
• a local FastAPI application,
• a browser build running on Pyodide.

The browser bridge is tested against the server transport for representative route families. Publication artifacts are regenerated separately by the native reproduction pipeline.

Try FlyLab

Browser

The zero-install bench is published with GitHub Pages:

https://pinkysworld.github.io/FlyLab/

The static build bundles the FlyLab wheel, derived circuit cuts and its Python runtime.

Local installation

git clone https://github.com/pinkysworld/FlyLab.git
cd FlyLab
python -m pip install -e ".[dev,viz]"
python -m pytest -q

Requirements: Python 3.11 or newer.

Start the local bench:

flylab serve

Then open the local URL printed by the command.

Quick examples

List the compound library:

flylab list-drugs

Inspect typed receptor engagement:

flylab occupancy imidacloprid --conc 1e-6

Run the deterministic neighbourhood assay:

flylab assay-subgraph --compound imidacloprid --conc 1e-6

Run the LIF assay:

flylab assay-spiking --compound fipronil --conc 1e-6

Run the map-extracted gustatory circuit:

flylab assay-taste-map --compound fipronil --conc 1e-6

Inspect connectome null models:

flylab null-panel --compound fipronil

Explore a derived circuit:

flylab graph info --graph taste_motor

Declarative runs, claim cards and the artifact manifest

A single assay answers one question. A spec describes a whole run, and flylab run turns it into a self-describing directory: the resolved spec, one notebook per cell, the analyses requested, figures, claim cards and a manifest recording the spec hash, the code and library hashes, the seeds, the timings and two hashes per artifact. The same spec and the same seed reproduce it byte for byte, and the keys that legitimately vary are declared, stripped from the content hash and listed per file.

flylab spec-schema --example > experiment.yaml   # a starter spec
flylab run experiment.yaml --dry-run             # validate, resolve, estimate the runtime
flylab run experiment.yaml --outdir runs/demo    # write the run directory

A claim card is the answer to "what is this number, and what is it worth?" for one readout. It states the claim, that it is a simulation rather than an observation, the typed evidence behind it with each row's distance from the modelled target, which single link of the provenance chain is a measurement, the assumptions that could change its sign, its connectome-dependence verdict, how much of the specification family retains it, that there is no independent biological validation, and the unknowns it does not paper over with a plausible number.

flylab card imidacloprid --conc 1e-6              # one card, printed
flylab card --run runs/demo --markdown            # every card of a finished run

The artifact manifest hashes the code, the compound library, the derived graphs, the literature datasets and the paper artifacts, so a checkout can prove it is the one a result came from. The release workflow gates a tag on it.

flylab manifest --check                           # verify the committed manifest
flylab manifest --write --lock                    # rewrite it, and the dependency lockfile

The full workflow — spec fields, what each analysis block runs, what the run directory contains and how the determinism digest is computed — is in docs/WORKFLOW.md.

Data and provenance

FlyLab deliberately keeps pharmacology and connectome data separate.

Layer	Source	Role
MaleCNS	public MaleCNS v1.0 data	synapse-resolution wiring and transmitter annotations
Derived cuts	data/derived/	small reproducible research circuits used by the repository
Pharmacology	flylab/pharm/library.yaml	typed receptor evidence with source metadata
Literature datasets	data/literature/	resistance, rankings, expression, mixtures, exposure and behavioural references
Notebook provenance	every exported notebook	FlyLab version, library hash, map identity, seed, warnings and platform

The large source connectome matrix is not required to reproduce the paper. The repository commits the small derived artifacts needed for the analyses.

Reproduce the research paper

The paper is generated from the same computational record as its figures and tables.

python scripts/reproduce_paper.py

A full run regenerates the publication artifacts under papers/, including the machine-readable papers/results.json record.

Useful development modes:

python scripts/reproduce_paper.py --fast
python scripts/reproduce_paper.py --only dependence --outdir /tmp/flylab
python scripts/reproduce_paper.py --list

The fast mode reduces statistical effort and is intended for development checks, not for generating the committed paper results.

Scientific boundaries

FlyLab is intended for computational hypothesis triage, model auditing, reproducible method development and teaching.

It is not:

• a replacement for in vivo or electrophysiological experiments,
• a pharmacokinetic model of a living fly,
• a regulatory toxicology platform,
• a vertebrate safety model,
• a claim that every circuit prediction needs a connectome,
• a source of automatically generated live-animal data.

A free concentration is an input to the model. Receptor expression is incomplete. The gain transformations are modelling assumptions. Circuit cuts are reduced representations of a much larger nervous system. These limitations are part of the exported provenance, not footnotes to be discovered later.

Documentation

Start with docs/README.md.

Useful entry points:

• Tutorial: seven runnable lessons, each with its real output and what it does and does not license
• Interpretation guide: how to read every number the bench produces, and the misreading each one invites
• Architecture: dataflow, layer boundaries and implementation structure
• Research positioning: what FlyLab does and does not claim as novel
• Research map: current analyses, paper results and open research gaps
• Browser build: Pyodide and GitHub Pages architecture
• Software stack: dependencies and engineering choices
• Paper status: manuscript state and reproducibility checklist
• Contributor handoff: internal constraints for agents and contributors

The old v0.5 design contract is retained for history. It is not the authoritative description of the current v0.6 evidence model.

Repository layout

flylab/
  pharm/          typed evidence, receptor engagement, mechanisms
  circuit/        rate and LIF runtimes
  assays/         circuit and experiment entry points
  analysis/       dependence, ablation, robustness, uncertainty, VOI
  validation/     literature concordance and source-overlap checks
  browser/        Pyodide bridge
  static/         interactive bench

data/
  derived/        committed research cuts
  literature/     sourced supporting datasets

papers/
  figures/
  tables/
  results.json
  IJRC_FlyLab_draft.md
  SUPPLEMENT.md

scripts/
  reproduce_paper.py
  build_pages.py

Contributing

Scientific traceability takes priority over adding features.

Before changing the research core, read HANDOFF.md, docs/ARCHITECTURE.md and docs/NOVELTY.md.

At minimum:

python -m pytest -q

Longer browser and end-to-end checks are marked as slow:

pytest -m slow

Do not silently replace missing evidence, hand-edit generated paper numbers, or turn model-internal results into biological claims.

Citation and licence

FlyLab source code is released under the MIT License.

Connectome-derived artifacts retain their upstream attribution requirements. Cite the underlying connectome publications before citing FlyLab as the software layer. See CITATION.cff for the repository citation metadata.