Adding an experiment setup
The arena is described once, in one file; the labeler, the trainer and both desktop apps read that description, so a new setup needs no code.
| Step | What you do | Result |
|---|---|---|
| 1 | Describe the arena: configs/arenas/<name>.yaml |
points, their order, floor and zones |
| 2 | Click ~30 frames per camera setup: scripts/label_arena.py |
arena_labels/<name>.json |
| 3 | Train the arena detector: scripts/train_arena.py |
arena_<name>.pt and its accuracy report |
| 4 | Choose the behavior rules: an assay: section in a pipeline config |
per-frame and summary CSVs |
| 5 | Use it: a profile with the config and the detector | the apps find the arena in every video |
1. Describe the arena
# configs/arenas/light_dark.yaml — a light–dark box seen from above: 4 corners and the 2 ends of
# the partition (on the top and bottom walls). Clockwise from the top-left corner the points are
# corner, partition end, corner, corner, partition end, corner.
name: light_dark
experiment: light_dark # the assay experiment this arena serves
ask: the 4 corners and both ends of the partition
order: polygon # how clicks in any order are put in order (below)
points: [corner top-left, partition top end, corner top-right, corner bottom-right,
partition bottom end, corner bottom-left]
floor: [1, 3, 4, 6] # 4 references for a box floor; empty when there is none
zones:
- {name: dark, kind: chamber, polygon: [1, 2, 5, 6]}
- {name: light, kind: chamber, polygon: [2, 3, 4, 5]}
sources: # optional: where scripts/label_arena.py finds top-view videos on larcc
folder: /home/z0song04/upload4/light dark
- points: names in the order they are saved. You click them in any order.
- order:
box(4 corners, clockwise from the one nearest the image's top-left),polygon(any number of points clockwise around their center, from the one nearest the top-left — right for arenas whose outline goes once around the center, including points on the walls),three_chamberorplus(seesrc/animalpose/arena.py). Pick one where every clicked set comes out in the same order however the arena sits in the image; a new rule is one function inORDERSthere. - Point references in
floorandzones: a point number (1-based) or"a-b x c-d", where the line through points a and b crosses the line through c and d (inner corners of mazes). - Zone kinds are what the behavior modules read:
center,open_arm/closed_arm(the plus maze; checked against the walls in each video),chamber, or any name of your own (thezonesmodule reports time and entries for every zone by name).
The definition is checked when it loads (python3 -c "from animalpose import arena; arena.load('light_dark')");
add a case to tests/test_arena.py with a few clicked sets in shuffled order.
2. Label
30 frames per experiment folder (camera setup) are enough to start; more setups beat more frames
of one setup. Click the points in any order; the window shows them numbered in the saved order
with the zones they make. --check lists frames to look at again. --export --zones
~/AnimalPose/zones writes a hand-made layout per camera setup, named after its folder
(light_dark/ → light_dark.json, printed with the assay.arena.rig to set); the apps use it as
is, before any training.
3. Train
On larcc, ~/upload/arena/train_arena.sbatch runs it for every type (a GPU, ~4 min per run).
report.txt gives the error per point in frame pixels on videos left out of training (heldout)
and, with several setups, on a setup left out entirely (loeo:<setup>): the second is what a new
lab's camera will see. Under ~5 px is good; a setup with large loeo errors needs a few labeled
frames of its own.
4. Behavior rules
In the pipeline config (see configs/assay_example.yaml):
assay:
experiment: light_dark
modules: [zones, grooming, rearing] # presets exist for open_field, plus_maze, three_chamber, grooming
arena: {rig: light-dark-room-2}
The zones module writes, per frame, the zone the body is in and — when the arena has a floor —
its position on the floor (floor_u, floor_v, 0–1) and distance to the wall in body lengths.
A new rule is one Module in rust/src/assay/modules.rs.
5. Use it in the apps
Settings → Profiles: pick the config, and under Arena the Arena Detector (import the
.pt with Settings → General → Import → Model…). Each processed video's arena is saved with a
picture as zones/<rig>.<video>.json; a layout the detector doubts (a point found with low
confidence or moving between frames, a floor that is not a convex quadrilateral) is marked
needs_review with the reason, and the run says so. A hand-made zones/<rig>.json always wins.
To ship the setup with the apps, add it to SETUPS in scripts/build_samples.py, rebuild
samples/, and run animalpose samples check (built with --features ffi or gui) or animalpose-gui --check-samples.