Zebra Finch Vocalization Dataset for Semi-Automated Clustering

Zebra Finch Vocalization Dataset for Semi-Automated Clustering

This dataset supports the paper "Benchmarking Automated and Semi-Automated Vocal Clustering Methods". It contains vocalization data for three juvenile male zebra finches (R3406, R3640, R3822), processed and organized for clustering analysis.

================================================================================
Dataset Structure
================================================================================

The dataset is organized by subject (bird ID). Each subject folder contains:

1. HDF5 Files (*.h5): Self-contained files storing segmentation, audio features, embeddings, and clustering results.
2. Audio Files (wavs/): Original Waveform Audio File Format (.wav) recordings.

--------------------------------------------------------------------------------
Directory Layout
--------------------------------------------------------------------------------

data/
├── R3406/
│   ├── wavs/                    Original .wav files
│   ├── R3406_unclustered.h5     Base data with segmentation & embeddings (no clusters)
│   ├── R3406_hdbscan.h5         Automated clustering results (HDBSCAN)
│   ├── R3406_kmeans.h5          Automated clustering results (K-means)
│   ├── R3406_manual_expr_*.h5   Fully manual clustering by experts (az, kl, mb)
│   └── R3406_semiauto_expr_*.h5 Semi-automated clustering results by experts
├── R3640/
│   └── ... (same structure)
└── R3822/
    └── ... (same structure)

================================================================================
HDF5 File Contents
================================================================================

The HDF5 files follow a standardized structure compatible with the provided Python analysis tools.

1. segments/ Group
------------------
Contains data for each segmented vocalization (rows correspond to segments):
- Timing: onset_sec, duration_sec, onset_sample, duration_samples
- Identification: file_id (index into files group), segment_id
- Features: 
  - umap: (N, 2) matrix of UMAP projections of embeddings
  - pca: (N, 100) matrix of PCA-reduced embeddings
- Clustering: cluster_id (integer label for each segment)

2. files/ Group
---------------
List of source audio files:
- filename: Name of the .wav file
- file_id: Unique identifier referenced by segments

3. spectrograms/ Group
----------------------
Compressed linear spectrograms for each original audio file to facilitate quick visualization.
- Keys are file IDs (e.g., '0', '1')

4. embeddings/ Group
--------------------
Deep learning embeddings for each segment:
- raw: High-dimensional embeddings (e.g., from WhisperSeg/Faster-Whisper)
- segment_id: Corresponding segment IDs

5. parameters/ Group (Attributes)
---------------------------------
Metadata and parameters used for preprocessing, organized by step:
- Audio: audio_sr (sampling rate), sr_original
- Spectrogram: spec_n_fft, spec_hop_length, spec_min_freq, spec_max_freq
- Segmentation: seg_model (e.g., WhisperSeg), seg_min_freq, seg_time_step
- Embedding: emb_model, emb_batch_size
- Dimensionality Reduction: umap_n_neighbors, pca_n_components

================================================================================
Usage & Code
================================================================================

This dataset is designed for use with the "Semi-Automated Clustering Tool", a Python-based GUI developed for efficient refinement of vocal clusters.
- Code Repository: https://github.com/hwiora/semi_automated_clustering/
- Documentation: Refer to the repository `README.md` for instructions on loading this data and running the visualization tool.