ContourUSV: Ultrasonic Vocalization Detection Pipeline

ContourUSV is an automated pipeline for detecting ultrasonic vocalizations (USVs) in audio recordings. The system uses spectrogram analysis combined with advanced image processing techniques to identify and classify 22kHz and 50kHz USVs.

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/contourusv.git
   cd contourusv

2. Create and activate virtual environment:

   python -m venv venv
   source venv/bin/activate  # Linux/MacOS
   venv\Scripts\activate     # Windows

3. Install dependencies:

   pip install -e .

Data Directory Structure

Organize your input data using the following structure:

root_path/                  # Passed via --root_path argument
├── EXPERIMENT_NAME/        # Passed via --experiment argument
│   └── TRIAL_NAME/         # Passed via --trial argument
│       ├── *.wav           # Audio recordings
│       ├── *.WAV           # (Alternative capitalization)
│       ├── *.html          # HTML annotations
│       ├── *.xlsx          # Excel annotations
│       └── *.csv           # CSV annotations

Example Concrete Structure:

/Users/username/data/
└── PTSD16/
    └── ACQ/
        ├── rat12_day1.wav
        ├── rat12_day1.html
        ├── rat13_day1.WAV
        └── rat13_day1.html

File Requirements:

• Audio files: Must have .wav or .WAV extension
• Annotation files: Must match audio filenames and reside in same directory
• Supported annotation formats:
  • HTML
  • Excel
  • CSV

Output Structure

output/
├── EXPERIMENT_NAME/
│   ├── TRIAL_NAME/
│   │   ├── contour_detections/
│   │   │   └── *.csv (detection annotations)
│   │   ├── evaluation_results/
│   │   │   └── Evaluation_*.csv (performance metrics)
│   │   └── spectrograms/
│   │       └── *.png (annotated spectrograms)
│   └── ground_truth_annotations/
│       └── *.csv (processed ground truth)

Usage

In the src directory execute the following command to run the detection pipeline.

Basic Command

python main.py \
  --root_path /path/to/your/data \
  --experiment EXPERIMENT_NAME \
  --trial TRIAL_NAME \
  --file_ext ANNOTATION_FILE_EXT

Example Command

python main.py \
  --root_path /Users/username/data \
  --experiment PTSD16 \
  --trial ACQ \
  --file_ext .html

Required Arguments

Argument	Description	Example
--root_path	Root directory containing experiment data	/data/studies
--experiment	Name of the experiment	PTSD16
--trial	Name of the trial/condition	ACQ
--file_ext	Annotation file extension (.html, .xlsx, .csv)	.html

Optional Parameters

Parameter	Default	Description
--overlap	3	Overlap duration between windows (seconds)
--winlen	10	Window length for processing (seconds)
--freq_min	15	Minimum frequency for detection (kHz)
--freq_max	115	Maximum frequency for detection (kHz)
--wsize	2500	Window size for processing
--th_perc	95	Percentile threshold for noise reduction

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

License

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

Contact

Sabah Anis - [email protected]