3D Mouse Tracking Analysis

This repository provides a comprehensive toolkit for analyzing 3D mouse tracking data. The code is designed to work with 3D pose estimates generated by DANNCE (a deep learning-based 3D animal pose estimation framework).

⚠️ Prerequisite

Before using this analysis pipeline, you must first run DANNCE on your video data to obtain accurate 3D coordinate predictions. This repository assumes you already have DANNCE-generated 3D keypoint data ready for downstream analysis.

📁 Repository Structure

├── analyze_data_3d_utils/
│ ├── DataAnalyzer.py # Core analysis functions for 3D tracking data
│ ├── DataLoader.py # Data import and loading utilities
│ ├── DataProcessor.py # Preprocessing and data cleaning functions
│ ├── DataVisualizer.py # General data visualization tools
│ └── SkelVisualizer.py # 3D mouse skeleton visualization tools
├── analyze_data_3d.ipynb # Jupyter notebook with usage examples and workflow demonstrations
├── analyze_data_3d_cfg.yaml # Configuration file with all adjustable parameters and variables
├── keypoint_moseq_test.ipynb # Behavioral clustering using Keypoint-MoSeq (unsupervised segmentation of 3D keypoint data)
└── lst_3d_result.csv # Trial log/experiment records for each mouse session

🛠️ Quick Start

1. Clone the repository:

git clone https://github.com/Gao-Xinjian/looming_3d_analysis_code.git
cd looming_3d_analysis_code

2. Configure parameters in analyze_data_3d_cfg.yaml and other paths in .ipynb to match your experimental setup.
3. Run the analysis pipeline: jupyter notebook analyze_data_3d.ipynb
4. For behavioral clustering: jupyter notebook keypoint_moseq_test.ipynb