song_phenotyping

Automated pipeline for phenotyping Bengalese finch song.

song_phenotyping segments, embeds, clusters, and characterises syllable repertoires from raw audio recordings. It supports two annotation formats (evsonganaly and wseg) and produces standardised phenotype tables suitable for statistical comparison across birds and conditions.

Getting started

• Installation
  • Requirements
  • Install from source
  • Optional extras
  • Configuration
  • Macaw server configuration
• Usage guide
  • Quick start
  • Stage A — Spectrogram ingestion
  • Stage B — Flattening
  • Stage C — UMAP embedding
  • Stage D — Clustering and labelling
  • Stage E — Phenotyping
  • Visual inspection — HTML catalogs
  • Configuration

API reference

• API Reference
  • Ingestion (Stage A)
  • Flattening (Stage B)
  • Embedding (Stage C)
  • Labelling (Stage D)
  • Phenotyping (Stage E)
  • Catalog (HTML visualization)
  • Slicing (Stage A1)
  • Signal processing
  • Tools
• Ingestion (Stage A)
  • Public API
  • copy_audio_and_partner_rec()
  • create_empty_segmented_data()
  • create_segmented_audio_data()
  • filepaths_from_evsonganaly()
  • filepaths_from_local_cache()
  • filepaths_from_wseg()
  • main()
  • process_and_save_audio()
  • process_pipeline()
  • process_single_file()
  • reconstruct_server_path()
  • resolve_audio_file_path()
  • save_data_specs()
  • save_specs_for_evsonganaly_birds()
  • save_specs_for_wseg_birds()
  • select_new_file_pairs()
  • select_new_files()
  • select_wseg_file_pairs_from_metadata()
  • standardize_bird_band()
• Flattening (Stage B)
  • Public API
  • create_flattened_output_path()
  • extract_song_id()
  • find_syllable_files()
  • flatten_bird_spectrograms()
  • flatten_spectrograms()
  • load_syllable_data()
  • process_single_syllable_file()
  • save_flattened_data()
• Embedding (Stage C)
  • Public API
  • UMAPParams
  • calculate_adaptive_workers_improved()
  • calculate_safe_batch_size()
  • check_embedding_compatibility()
  • compare_umap_embeddings_plot()
  • complex_spectrogram_distance()
  • compute_and_save_umap_memory_aware()
  • compute_embedding_grid_parallel_robust()
  • compute_single_umap_worker_safe()
  • estimate_umap_memory_usage()
  • explore_embedding_parameters_robust()
  • generate_embedding_paths()
  • group_delay_distance()
  • inspect_existing_embeddings()
  • instantaneous_freq_distance()
  • load_embedding_from_file()
  • load_flattened_specs()
  • main()
  • monitor_memory_usage()
  • phase_aware_spectrogram_distance()
  • save_umap_embeddings()
  • save_umap_model()
  • subsample_by_song()
  • subsample_data()
• Labelling (Stage D)
  • Supported quality metrics
  • Public API
  • DEFAULT_HDBSCAN_GRID
  • HDBSCANParams
  • aggregate_raw_scores_across_birds()
  • analyze_parameter_performance_by_sample_size()
  • clear_clustering_outputs()
  • cluster_embeddings()
  • compute_composite_score()
  • compute_cross_bird_composite_scores()
  • compute_metric_ranking()
  • compute_scores()
  • create_cluster_summary_pdf()
  • dunn_index()
  • identify_optimal_parameters_by_sample_size()
  • information_criterion()
  • label_bird()
  • load_labels()
  • load_master_summary()
  • load_umap_embeddings()
  • main()
  • parse_embedding_filename()
  • plot_summary_matrix()
  • plot_umap()
  • remove_directory()
  • reorder_columns()
  • save_cross_bird_analysis()
  • save_labels()
  • save_master_summary()
  • score_cluster_penalty()
  • search_cluster_params()
  • select_best_params()
• Phenotyping (Stage E)
  • Public API
  • PhenotypingConfig
  • analyze_repeats()
  • analyze_transitions()
  • analyze_vocabulary_and_entropy()
  • calculate_phenotypes_for_label_type()
  • create_unified_phenotype_row()
  • detect_intro_notes()
  • generate_manual_umap_plot()
  • load_bird_syllable_data()
  • load_clustering_labels_for_syllables()
  • load_clustering_results()
  • load_tempo_stats()
  • main()
  • phenotype_bird()
  • plot_repeat_patterns()
  • plot_transition_matrices()
  • plot_vocabulary_comparison()
  • save_detailed_phenotype_data()
• Catalog (HTML visualization)
  • Public API
  • CatalogConfig
  • generate_all_catalogs()
  • generate_cluster_quality_catalog()
  • generate_sequencing_catalog()
  • generate_song_catalog()
  • generate_syllable_type_catalog()
• Slicing (Stage A1)
  • Public API
  • main()
  • process_slicing_pipeline()
  • slice_syllable_files_from_evsonganaly()
  • slice_syllable_files_from_wseg()
• Tools
  • Label handling
  • Spectrogram parameters
  • Run configuration and registry
  • Project configuration
  • Pipeline paths
  • File records