Skip to content

docs: add guide for supervised ID models (multi_class_topdown / multi_class_bottomup) #570

@talmo

Description

@talmo

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

  1. 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.
  2. Data prep — currently relies on the legacy SLEAP GUI for track assignment (Tracks → Set Instance Track → New Track; Ctrl+1Ctrl+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.
  3. Model setup — pick multi_class_topdown or multi_class_bottomup; reference the existing head schemas in docs/reference/models.md:173-206.
  4. Tuningloss_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.
  5. 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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions