Migrated from talmolab/sleap#1878 (Talmo's original docs-roadmap issue, opened July 2024).
Goal
Add a user-facing tutorial for supervised ID models under docs/guides/. Reference coverage already exists at docs/reference/models.md:173-206 (head config schemas) and the model picker mentions them at docs/getting-started/first-model.md:30, but there is no narrative guide explaining when to use them and how to prepare data.
Suggested outline
- When to use — distinct identities (visual markers, fur color, ear-clips) vs. unsupervised tracking. Trade-off: cleaner identity propagation in exchange for finicky training and the need to label tracks on every user instance.
- Data prep — currently relies on the legacy SLEAP GUI for track assignment (
Tracks → Set Instance Track → New Track; Ctrl+1–Ctrl+9 shortcuts to assign instances). Track names become identity classes (e.g. "male", "female", "dark_fur"). Note: only user instances with a track assigned are used for training.
- Model setup — pick
multi_class_topdown or multi_class_bottomup; reference the existing head schemas in docs/reference/models.md:173-206.
- Tuning —
loss_weight on the classification head, starting around 1e-3; decrease to 1e-4 if poses degrade, increase to 1e-2 if IDs don't separate. Document the pose-vs-ID objective tension.
- Inference — no
--tracking.tracker arguments needed; identities are assigned by the model directly.
Source draft text
Talmo wrote a lot of usable narrative in talmolab/sleap#1878 — adapt/lift from there.
Reference
SLEAP paper: https://www.nature.com/articles/s41592-022-01426-1 (general supervised-ID architecture description).
Migrated from talmolab/sleap#1878 (Talmo's original docs-roadmap issue, opened July 2024).
Goal
Add a user-facing tutorial for supervised ID models under
docs/guides/. Reference coverage already exists atdocs/reference/models.md:173-206(head config schemas) and the model picker mentions them atdocs/getting-started/first-model.md:30, but there is no narrative guide explaining when to use them and how to prepare data.Suggested outline
Tracks → Set Instance Track → New Track;Ctrl+1–Ctrl+9shortcuts to assign instances). Track names become identity classes (e.g."male","female","dark_fur"). Note: only user instances with a track assigned are used for training.multi_class_topdownormulti_class_bottomup; reference the existing head schemas indocs/reference/models.md:173-206.loss_weighton the classification head, starting around1e-3; decrease to1e-4if poses degrade, increase to1e-2if IDs don't separate. Document the pose-vs-ID objective tension.--tracking.trackerarguments needed; identities are assigned by the model directly.Source draft text
Talmo wrote a lot of usable narrative in talmolab/sleap#1878 — adapt/lift from there.
Reference
SLEAP paper: https://www.nature.com/articles/s41592-022-01426-1 (general supervised-ID architecture description).