# ๐ชฐ FruitFlyBrain โ the fruit-fly brain, from connectome to a fly you can teach
[](LICENSE)
[](datasets/README.md)
[](https://www.python.org/)
[](projects/09_flylab)
[](https://rohitcraftsyt.github.io/FruitFlyBrain/projects/09_flylab/dashboard/)
Nine working projects built on **officially released *Drosophila melanogaster*
brain data**. They go from network science on a 3.5-million-synapse connectome,
through machine-learning models trained on its wiring, to **FlyLab**: a
physics-simulated fruit fly whose brains keep training continuously and
perform tasks you give them in plain English.
Everything uses reputable primary sources (Janelia HHMI, the Princeton/MRC
FlyWire consortium, EPFL's NeuroMechFly), downloads without a login, and has
been **run end-to-end**. Every animation below was generated by the code in this
repo ([`make_gifs.py`](make_gifs.py)).
FlyLab: a brain that only has its two antennae steers NeuroMechFly (a micro-CT-based fruit-fly
body) to food in MuJoCo physics. The HUD shows what it smells and the descending commands it sends to its legs.
**๐ Watch the brains train live: [training dashboard](https://rohitcraftsyt.github.io/FruitFlyBrain/projects/09_flylab/dashboard/)**
**๐ Run the trained brains yourself: [brain playground](https://rohitcraftsyt.github.io/FruitFlyBrain/projects/09_flylab/playground/)**,
which lets you drag the fly and its target, silence neurons or an antenna, test 200 arenas, and download the weights.
---
## Contents
- [FlyLab: teach a physics-simulated fruit fly](#-flylab--teach-a-physics-simulated-fruit-fly-project-09) (flagship)
- [The data](#the-data--two-complementary-connectomes)
- [Quick start](#quick-start)
- [Connectome analysis projects 01โ05](#connectome-analysis)
- [Machine-learning projects 06โ08](#-machine-learning-on-the-connectome)
- [Results at a glance](#results-at-a-glance)
- [Repository layout](#repository-layout) ยท [Reproducing the animations](#reproducing-the-animations) ยท [Citations & license](#citations)
---
## ๐ฎ FlyLab โ teach a physics-simulated fruit fly ([Project 09](projects/09_flylab))
Type *"find the food"*, *"go to the light"* or *"turn left 90"*. The fly's brain
for that skill trains, then drives **NeuroMechFly v2** (EPFL; a body built from a
micro-CT scan of a real adult *Drosophila*, with 42 actuated leg joints, leg
adhesion and ground contact) in **MuJoCo physics** through the official FlyGym
walking controller.
- **7 skills, 7 brains.** Each skill has its **own neural network and its own
training process**, so learning one skill never overwrites another. An
earlier single shared brain forgot skills: it fell from 86% to 57% physics
success after a long curriculum.
- **Continuous training with physics in the loop.** Each round runs 100
Evolution-Strategies generations in a surrogate body calibrated against
physics, then validates in real MuJoCo. A brain is only replaced when it does
better **in physics**, and every new best is scored on **held-out physics
arenas never used for selection**. Mastery is progressive over three levels
(6 โ 12 โ 24 validation arenas).
- **Runs itself.** It restarts after reboots, spare CPU polishes optimal brains
(a result is kept only if it stays optimal), and every day each brain is
re-tested on new random physics arenas. The status table below rewrites
itself daily and results are pushed hourly. See
[autonomous operation](projects/09_flylab/README.md#autonomous-operation-no-one-needs-to-touch-it).
- **Realistic senses.** Odor is sampled at the model's **measured aristae**
(0.52 mm ahead of the thorax, 0.38 mm apart), there are two compound eyes,
and the gait wobble (0.15 mm and 3.6ยฐ per step), measured in physics, is fed
back into training.
### The seven brains in physics
*Each film is the current best brain on an arena it has never seen, rendered
automatically as training improves it.*
| Walk forward & stop | Turn in place | Go to a location |
|:---:|:---:|:---:|
| 
| 
| 
|
| **Find food by smell** | **Escape a bad smell** | **Walk toward light** |
| 
| 
| 
|
| **Hide from light** | | |
| 
| | |
### Training, round by round
**Status on 2026-10-31** (rewritten daily by `daily.py`; the [dashboard](https://rohitcraftsyt.github.io/FruitFlyBrain/projects/09_flylab/dashboard/) is live):
| Skill brain | Rounds | Physics validation | **Held-out physics test** (95% CI) | Fresh-arena check | Status |
|---|---:|---:|---:|---:|---|
| Walk forward | 241 | 100% of 24 | **100% of 32** (89%โ100%) | 100% of 16 (2026-10-31) | โ
optimal |
| Turn in place | 771 | 100% of 24 | **97% of 32** (84%โ99%) | 94% of 16 (2026-10-31) | โ
optimal |
| Go to a location | 199 | 100% of 24 | **100% of 32** (89%โ100%) | 100% of 16 (2026-10-31) | โ
optimal |
| Find food by smell | 170 | 100% of 24 | **100% of 32** (89%โ100%) | 100% of 16 (2026-10-31) | โ
optimal |
| Escape a bad smell | 707 | 100% of 24 | **97% of 32** (84%โ99%) | 100% of 16 (2026-10-31) | โ
optimal |
| Walk toward light | 394 | 100% of 24 | **100% of 32** (89%โ100%) | 100% of 16 (2026-10-31) | โ
optimal |
| Hide from light | 440 | 100% of 24 | **100% of 32** (89%โ100%) | 100% of 16 (2026-10-31) | โ
optimal |
**How it got here** (full [engineering log](projects/09_flylab/README.md#making-skills-survive-the-jump-to-physics-engineering-log)):
each failure was measured in physics and then fixed.
- Physics initially ran at 0.02ร real time. Updating the controller at 1 kHz
made it **~20ร faster** with the gait verified unchanged.
- The fly circled food instead of stopping, so the task now rewards dwell time.
- Escaping a smell scored 100% in the surrogate but 0% in physics. The cause
was measured gait wobble; the fix was domain randomization plus sensory
integration.
- The fly "stood still" by rocking one side backward, so the surrogate now
models leg-activity sway.
- Walking toward light fidgeted at an eye-level lamp, so the lamp moved
overhead.
- A shared brain forgot skills, so every skill now has its own brain.
```bash
python -m venv .venv-sim && .venv-sim\Scripts\pip install -r requirements-sim.txt
cd projects\09_flylab
..\..\.venv-sim\Scripts\python flylab.py # then type: find the food
..\..\.venv-sim\Scripts\python supervise.py # keep every brain training
```
---
## The data โ two complementary connectomes
| Dataset | What it is | Scale | Source |
|---|---|---|---|
| **hemibrain v1.2** | dense reconstruction of the central brain: *every traced neuron + synapse* | 21,739 neurons ยท 3.55 M connections ยท 14.3 M synapses | Janelia FlyEM (CC BY 4.0) |
| **FlyWire FAFB** | annotations for a *complete* adult brain | 139,248 neurons ยท 8,840 cell types | FlyWire consortium (CC BY 4.0) |
| **NeuroMechFly v2** | biomechanical fly body + locomotion controllers (Project 09) | 42 actuated joints, MuJoCo | EPFL NeLy lab, FlyGym (Apache-2.0) |
Provenance, licenses, SHA-256 checksums and citations are in
[`datasets/README.md`](datasets/README.md).
## Quick start
```bash
# from the FruitFlyBrain/ directory: projects 01-08
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt # Windows (macOS/Linux: source .venv/bin/activate)
python download_datasets.py # connectome data, ~275 MB, first run only
.venv\Scripts\python projects\01_connectome_graph_analysis\analyze.py
.venv\Scripts\python projects\02_neurotransmitter_atlas\atlas.py
.venv\Scripts\python projects\03_shortest_path_circuits\trace.py
.venv\Scripts\python projects\04_connectome_neural_network\simulate.py
.venv\Scripts\python projects\05_navis_3d_viewer\view_neurons.py
.venv\Scripts\python projects\06_celltype_classifier\train_classifier.py
.venv\Scripts\python projects\07_neuron_embeddings\embed_and_cluster.py
.venv\Scripts\python projects\08_synapse_link_prediction\link_prediction.py
# project 09 (FlyLab) has its own environment: see the FlyLab section above
```
Each script prints a summary and writes its figures and tables to its own
`outputs/` folder. Each project's `README.md` has usage, options and a sanity
check against known fly neuroscience.
---
## Connectome analysis
### 01 ยท [Connectome graph analysis](projects/01_connectome_graph_analysis) ยท hemibrain
The brain as a directed, weighted network: degree distributions, hubs and
connected components. The biggest hubs come out as **APL** and **DPM**, the
giant mushroom-body neurons known from the literature.
### 02 ยท [Neurotransmitter & cell-type atlas](projects/02_neurotransmitter_atlas) ยท FlyWire
A census of a *complete* brain: 139,248 neurons by super-class and predicted
neurotransmitter. The brain is **~62% cholinergic**, 18% glutamatergic and 14%
GABAergic, matching the published figures.
### 03 ยท [Synaptic pathway tracer](projects/03_shortest_path_circuits) ยท hemibrain
The strongest multi-synapse routes between cell types (edge cost = 1 / synapses).
**Kenyon cells โ MBONs** recovers the mushroom body's learning connection
directly, plus routes through the modulatory APL/DPM neurons.
### 04 ยท [Connectome-constrained neural network](projects/04_connectome_neural_network) ยท hemibrain
A recurrent network whose weights **are** the real central-complex wiring
(1,968 neurons, 243,743 connections). Stimulating **ER** ring neurons drives
the **EL/EPG** "compass" neurons, the known navigation pathway.
### 05 ยท [3-D neuron morphology viewer](projects/05_navis_3d_viewer) ยท NAVis
Real neuron shapes as a static render **and an interactive 3-D HTML** (drag to
rotate). `--neuprint` fetches the top hubs found by Project 01.
---
## ๐ค Machine learning on the connectome
### 06 ยท [Connectivity-based cell-type classifier](projects/06_celltype_classifier) ยท supervised
Predicts a neuron's cell-type family from *who it connects to* alone.
RandomForest **88.2%** / neural net **87.6%** accuracy across **53 families**
(18,590 neurons), against an 11.3% majority baseline. The animation shows the
neural net training epoch by epoch.
### 07 ยท [Neuron embeddings & unsupervised cell typing](projects/07_neuron_embeddings) ยท unsupervised
128-d embeddings learned from wiring alone recover cell types **without any
labels**: NMI **0.59**, 63% mean cluster purity. The animation shows t-SNE
separating the families.
### 08 ยท [Synapse link prediction](projects/08_synapse_link_prediction) ยท graph ML
Does neuron A synapse onto neuron B? The split is leakage-free (embeddings are
learned from training edges only). Gradient boosting reaches **0.971 ROC-AUC /
0.968 PR-AUC** on held-out connections. The animation shows the ROC curve
sharpening as trees are added.
---
## Results at a glance
| # | Project | Headline result |
|---|---|---|
| 01 | Connectome graph analysis | heavy-tailed wiring; top hubs **APL** (227k synapses) and **DPM** |
| 02 | Neurotransmitter atlas | **62%** cholinergic, 18% glutamate, 14% GABA across 139k neurons |
| 03 | Pathway tracer | strongest **KC โ MBON** learning route recovered |
| 04 | Connectome-constrained dynamics | **ER โ EPG** compass pathway emerges from raw wiring |
| 05 | 3-D morphology | interactive neuron viewer, linked to Project 01's hubs |
| 06 | Cell-type classifier | **88%** accuracy, 53 classes (baseline 11%) |
| 07 | Unsupervised cell typing | NMI **0.59** with no labels |
| 08 | Synapse link prediction | ROC-AUC **0.971** on unseen connections |
| 09 | FlyLab | **7 of 7** brains optimal on held-out physics tests; the rest keep training (table above) |
๐ **[`RESUME.md`](RESUME.md)** has paste-ready, quantified rรฉsumรฉ bullets for all of this.
## Repository layout
```
FruitFlyBrain/
โโโ README.md ยท RESUME.md ยท CITATION.cff ยท LICENSE
โโโ requirements.txt # projects 01-08
โโโ requirements-sim.txt # project 09 (FlyGym / MuJoCo)
โโโ download_datasets.py # fetches the connectome data
โโโ make_gifs.py # builds every animation in this README
โโโ datasets/ # provenance docs (data itself is downloaded)
โโโ docs/gifs/ # the animations
โโโ projects/
โโโ 01_connectome_graph_analysis/ 05_navis_3d_viewer/
โโโ 02_neurotransmitter_atlas/ 06_celltype_classifier/
โโโ 03_shortest_path_circuits/ 07_neuron_embeddings/
โโโ 04_connectome_neural_network/ 08_synapse_link_prediction/
โโโ 09_flylab/
โโโ flylab.py # talk to the fly
โโโ train_brains.py # continuous per-brain training, physics in the loop
โโโ supervise.py # keeps every brain training, re-films and publishes
โโโ training/ # per-brain logs, curves and reports (TRAINING.md)
โโโ state/brains/ # the trained brains (~5 KB each)
โโโ dashboard/ # the live GitHub Pages dashboard
```
## Reproducing the animations
```bash
.venv\Scripts\python make_gifs.py # projects 01-08 + FlyLab training curves
.venv-sim\Scripts\python make_gifs.py flylab_videos # FlyLab brain films
```
Every animation is computed from the real data by each project's own code.
Projects 06 and 08 re-run their pipelines and record the model while it trains.
## Environment used
Python 3.12 ยท pandas 3.0 ยท numpy 2.5 ยท networkx 3.6 ยท matplotlib 3.11 ยท scipy 1.18 ยท
scikit-learn 1.9 ยท navis 1.12 ยท plotly 7.1 ยท FlyGym 2.1 ยท MuJoCo 3.9
## Going further
- **FlyWire synapse-level edges:** free account on [Codex](https://codex.flywire.ai),
or programmatic access via [`CAVEclient`](https://github.com/seung-lab/CAVEclient) /
[`fafbseg`](https://github.com/navis-org/fafbseg-py).
- **neuPrint queries:** [`neuprint-python`](https://github.com/connectome-neuprint/neuprint-python) (free token).
- **FlyLab realism roadmap:** [`REALISM_AUDIT.md`](projects/09_flylab/REALISM_AUDIT.md), a fact-checked
list of what would make the simulated fly more lifelike.
## Citations
Please cite the original works when using them:
- Scheffer et al. (2020). *A connectome and analysis of the adult Drosophila central brain.* eLife 9:e57443.
- Dorkenwald et al. (2024). *Neuronal wiring diagram of an adult brain.* Nature 634, 124โ138.
- Schlegel et al. (2024). *Whole-brain annotation and multi-connectome cell typing of Drosophila.* Nature 634, 139โ152.
- Wang-Chen et al. (2024). *NeuroMechFly v2: simulating embodied sensorimotor control in adult Drosophila.* Nature Methods 21, 2353โ2362.
Full references are in [`datasets/README.md`](datasets/README.md) and [`CITATION.cff`](CITATION.cff).
## License
- **Code & docs in this repo:** [MIT](LICENSE) ยฉ 2026 Rohit (ROHITCRAFTSYT).
- **Connectome datasets:** owned by their creators and used under **CC BY 4.0**.
- **NeuroMechFly / FlyGym:** EPFL, Apache-2.0 (installed as a dependency, not redistributed).