MOUSEFLOW: A PYTHON TOOLBOX FOR HIGH-RESOLUTION BEHAVIORAL TRACKING IN HEAD-FIXED MICE

Precise quantification of behavior is essential for understanding how neural population activity encodes internal states and sensory–motor transformations. In head-fixed mouse experiments, stable optical and electrophysiological recordings are readily achieved, yet extracting fine-grained behavioral variables from video remains a major bottleneck. We introduce MouseFlow (MF), an open-source Python toolbox that enables automated, high-resolution behavioral tracking from face and body videos with minimal user intervention.
MouseFlow uniquely integrates marker-based pose estimation with dense optical flow to bridge discrete kinematic features and continuous motion fields within a unified framework. It combines pretrained DeepLabCut and LightningPose models with region-specific optical flow to quantify both localized features (e.g. pupil diameter, eye movements, blinks) and structured motion dynamics across the whisker pad, nose, mouth, and cheek. This allows simultaneous characterization of rhythmic orofacial behaviors such as whisking and sniffing, as well as their inter-regional coordination. In addition, MF extracts gait and locomotor parameters from body tracking, enabling joint analysis of facial and whole-body behavior across treadmill speeds.
We validated MouseFlow on the publicly available IBL Brain-Wide Map dataset, demonstrating robust cross-dataset generalization and tracking performance comparable to in-distribution data. Compared to existing tools such as Facemap, MF shows increased robustness for pupil tracking under challenging illumination and uniquely captures movement directionality, enabling structured analysis of coordinated facial dynamics.
By extending behavioral quantification from sparse markers to high-dimensional motion fields, MouseFlow provides a scalable and reproducible framework for linking distributed behavioral states to neural population activity.