Waggle Detection

MATLAB code for detecting and annotating waggle bouts in Drosophila courtship behavior.

Overview

Waggling is a distinct courtship wing behavior characterized by rhythmic, anti-phase oscillations of both wings at approximately 8-18 Hz. This repository contains code for:

1. Automated detection of waggle bouts from wing angle traces
2. Manual proofreading of detected waggle bouts via an interactive GUI

Citation

If you use this code, please cite:

Li X, Thieringer K, Gao Y, Murthy M (2026). Sequencing of distinct wing behaviors during Drosophila courtship. Current Biology 36:1-9. https://doi.org/10.1016/j.cub.2026.01.042

Requirements

• MATLAB R2020b or later
• Signal Processing Toolbox (for butter, filtfilt, hilbert)

Installation

Clone this repository:

git clone https://github.com/murthylab/waggle-detection.git
cd waggle-detection

Add the directory to your MATLAB path:

addpath('/path/to/waggle-detection');

Usage

Quick Start

% Load your wing angle data
% left_wing_angle: left wing angle trace (vector, in degrees)
% right_wing_angle: right wing angle trace (vector, in degrees)  
% fps: frame rate in Hz (e.g., 150)

waggle_bouts = detect_waggling(left_wing_angle, right_wing_angle, fps);

Files

File	Description
detect_waggling.m	Core detection function
waggle_detector.m	Batch processing script
proofread_waggle_bouts.m	Interactive proofreading GUI

Core Function: detect_waggling.m

waggle_bouts = detect_waggling(left_wing_angle, right_wing_angle, fps)
waggle_bouts = detect_waggling(left_wing_angle, right_wing_angle, fps, min_cycles)

Inputs:

Parameter	Description
left_wing_angle	Left wing angle trace (degrees)
right_wing_angle	Right wing angle trace (degrees)
fps	Frame rate (Hz)
min_cycles	Minimum oscillation cycles for valid bout (default: 3)

Output:

• waggle_bouts: N × 2 matrix where each row is [start_frame, end_frame]

Batch Processing: waggle_detector.m

For processing multiple sessions, edit the configuration section in waggle_detector.m:

% Configuration
fps = 150;                    % Frame rate
min_cycles = 3;               % Minimum cycles per bout
input_file = 'wing_angle_data.mat';
output_file = 'waggle_bouts_detected.mat';

Input file format:

Results(i).name             % Session name (string)
Results(i).genotype         % Genotype identifier (string, optional)
Results(i).left_wing_angle  % Left wing angle trace
Results(i).right_wing_angle % Right wing angle trace

Proofreading: proofread_waggle_bouts.m

Interactive GUI for manual verification of detected bouts.

Controls:

• Exclude: Mark false positives
• Edit: Adjust bout boundaries
• Add New: Add missed detections
• Done: Accept and continue

Algorithm

The detection algorithm:

1. Bandpass filter wing angles (8-18 Hz) to isolate waggling frequency
2. Hilbert transform to extract instantaneous phase and amplitude
3. Identify anti-phase frames where phase difference is 180° ± 60°
4. Apply amplitude thresholds:
   • Filtered amplitude > mean + 0.5×std
   • Raw wing angle > 8° (at least one wing)
5. Group continuous frames into bouts with minimum cycle count
6. Merge nearby bouts separated by < 1 cycle

Example Workflow

%% Step 1: Detect waggle bouts
waggle_detector

%% Step 2: Proofread detections (optional but recommended)
proofread_waggle_bouts

Data Availability

Data reported in this paper will be shared by the lead contact upon request.

Contact

• Lead Contact: Mala Murthy (mmurthy@princeton.edu)
• Lab Website: murthylab.princeton.edu
• Code Issues: Please open an issue on GitHub

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

We thank members of the Murthy Lab for helpful discussions. This research was supported by HHMI, NIH NINDS, and NIH BRAIN.