Three-camera 3D behaviour tracking for medaka (Oryzias latipes) mating experiments.
Research question. How do female mate choice, male courtship, and male–male aggression interact — and which behavioural factors actually determine the female's mating decision? One female and two males per trial, filmed from three synchronised cameras at 166 fps.
Current direction (2026-09-30). Deliver 3D trajectories for medaka_202512
with consistent individual IDs throughout each trial, excluding each recording's
first five minutes. Maximize usable time and reliable continuous segments while
leaving unsupported identity assignments unresolved. Tracking prototypes exist;
the latest SLEAP adapter remains unpromoted. See the
dataset delivery plan and
current handoff.
Student and collaborator start here: Analysis workspace provides setup, a runnable notebook template, and the review/handoff workflow. AGENTS.md defines the shared rules for AI agents after a fresh clone; CLAUDE.md adds Claude Code context. Repository-authored text is in English.
It replaces medaka-mating-pipeline, which was retired in August 2026 after accumulating
~175,000 lines across 605 scripts, ~153 GB of derived output, and documentation that had
drifted out of sync with what the code actually did. The science underneath is probably
sound, but it was no longer separable from the artifacts of partial runs and
late-discovered bugs.
Almost nothing was inherited. What was:
| Document | Contents |
|---|---|
| docs/HANDOFF.md | Index of the reset — what survived and what was done |
| docs/ASSET_MANIFEST.md | Every inherited data and model asset, with paths and sizes |
| docs/OIST_HPC.md | The one inheritedskill: running work on saion and deigo |
| docs/PRIOR_FINDINGS.md | Prior results —as hypotheses to re-verify, plus dead ends |
| docs/MIGRATION_PLAN.md | Order of operations, and the habits that made the old repo decay |
No analysis code was carried over.
- Nearly all previous analysis rests on 3 experiments out of 71, and it is not established that they are three independent females.
- Only about 22–26 experiments have any human (BORIS) annotation.
- Historical female annotations alone do not validate all-three-fish identity. Check the current identity evidence and source reviews before making M1/M2 claims.
Details and per-claim re-verification recipes are in docs/PRIOR_FINDINGS.md.
Each one exists because its absence caused a specific failure in the old repo.
- One importable package. No loose scripts, and no numbered ones — a number in a filename is a decision someone refused to make.
- Config fails loudly. Every configured path is existence-checked at load. A model that has been deleted is a hard error, never a silent fallback.
- Assets are checksummed. Inherited models and labels live under
asset_rootwith aMANIFEST.jsonrecording size, sha256 and provenance, verified before use. - Every output carries provenance. Code revision, inputs, resolved model paths, full argv — written to a sidecar next to the artifact, on failure as well as success.
- No flag may change which algorithm runs. A different algorithm gets a different
command. (In the old repo, omitting
--num-candidatessilently selected a different, 60× slower, unvalidated code path.) - One way to do each thing. Retire by deleting, not by prefixing the old thing with "legacy".
- Human-made data goes to
/bucketimmediately — never only into a working directory.
uv sync --locked --python 3.13 --extra dev --extra analysis
cp configs/paths.example.toml configs/paths.local.toml # then edit for your machine
pytest -qfrom medaka3d import load_paths, load_catalog
paths = load_paths()
video = paths.video("20251225_K_1_2_FCMC", "top_cam")
models = load_catalog(paths.asset_root)
centroid = models.get("sleap.round8.top.centroid")Three cameras — cam0 top (XY), cam1 side (XZ), cam2 side (YZ). Tank 20×20×20 cm, 166 fps, three fish (1 female + 2 males).