Catalog (HTML visualization)

HTML-based song catalogs for visual inspection (Stage F utility).

Replaces the ReportLab PDF approach with matplotlib + base64 PNG embedded in HTML. Produces two separate catalog types:

Song catalog — one continuous spectrogram per song, with manual labels above and automated cluster labels below, sorted chronologically.
Syllable-type catalog — for each unique label, a grid of individual syllable spectrograms drawn directly from the Stage A HDF5 arrays (no audio files required).

Public API

generate_song_catalog() — chronological song view for one bird.
generate_syllable_type_catalog() — per-label spectrogram grid.
generate_sequencing_catalog() — transition matrices and repeat stats.
generate_cluster_quality_catalog() — per-cluster feature stats, discriminative feature violins, outgoing transitions, and repeat-ramping analysis. Output file uses the name syllable_characteristics.
generate_all_catalogs() — convenience wrapper that calls all of the above.
CatalogConfig — configurable display parameters.

Examples

>>> from song_phenotyping.catalog import generate_all_catalogs
>>> results = generate_all_catalogs("/Volumes/Extreme SSD/pipeline_runs/or18or24", rank=0)
>>> results['song_catalog']
'.../or18or24/syllable_data/html/or18or24_song_catalog_rank0.html'

class song_phenotyping.catalog.CatalogConfig(n_songs=30, song_duration=6.0, song_fig_width=14.0, song_fig_height=3.5, n_per_type=30, grid_cols=6, syl_fig_size=1.2, dpi=120, overwrite=True)[source]

Bases: object

Shared configuration for both catalog types.

Parameters:

n_songs (int)
song_duration (float)
song_fig_width (float)
song_fig_height (float)
n_per_type (int)
grid_cols (int)
syl_fig_size (float)
dpi (int)
overwrite (bool)

dpi: int = 120

grid_cols: int = 6

n_per_type: int = 30

n_songs: int = 30

overwrite: bool = True

song_duration: float = 6.0

song_fig_height: float = 3.5

song_fig_width: float = 14.0

syl_fig_size: float = 1.2

song_phenotyping.catalog.generate_all_catalogs(bird_path, rank=0, config=None)[source]

Generate the full suite of HTML catalogs for one bird.

Convenience wrapper that calls generate_song_catalog(), generate_syllable_type_catalog() (auto labels), and — when manual labels are present — generate_syllable_type_catalog() (manual labels).

Parameters:

bird_path (str) – Path to the bird’s root directory.
rank (int, optional) – Clustering rank passed to each catalog generator. Default is 0.
config (CatalogConfig or None, optional) – Shared display parameters. Uses default CatalogConfig when None.

Returns:

Maps catalog type to the absolute HTML output path. Keys may include 'song_catalog', 'syllable_types_auto', 'syllable_types_manual', 'sequencing', and 'syllable_characteristics'. Only successfully generated catalogs are included.

Return type:

dict of str → str

song_phenotyping.catalog.generate_cluster_quality_catalog(bird_path, rank=0, config=None)[source]

Generate an HTML syllable characteristics catalog for one bird.

Presents per-cluster acoustic feature statistics, spectrogram thumbnails, eigensyllables, discriminative feature distributions, transition outflows, and (for repeat clusters) a ramping analysis.

Parameters:

bird_path (str) – Path to the bird’s root directory (the run-scoped path, same as passed to generate_all_catalogs()).
rank (int, optional) – Clustering rank to use. Default is 0.
config (CatalogConfig or None, optional) – Display parameters. Uses default CatalogConfig when None.

Returns:

Absolute path to the generated HTML file, or '' on failure.

Return type:

str

song_phenotyping.catalog.generate_sequencing_catalog(bird_path, rank=0, config=None)[source]

Generate an HTML sequencing catalog for one bird.

Reads the automated phenotype pickle from Stage E and renders transition matrices, repeat counts, syllable proportions, and summary statistics as embedded base64 PNGs inside a single HTML file.

Parameters:

bird_path (str) – Path to the bird’s root directory (must contain stages/05_phenotype/ from Stage E).
rank (int, optional) – Clustering rank to use (0 = best-ranked result). Default is 0.
config (CatalogConfig or None, optional) – Display parameters. Uses default CatalogConfig when None.

Returns:

Absolute path to the generated HTML file, or '' on failure.

Return type:

str

song_phenotyping.catalog.generate_song_catalog(bird_path, rank=0, config=None)[source]

Generate an HTML song catalog for one bird.

Each entry shows a continuous-song spectrogram spanning config.song_duration seconds, with manual syllable labels rendered above the spectrogram and automated cluster labels below. Songs are sorted chronologically using timestamps parsed from the audio filenames.

Parameters:

bird_path (str) – Path to the bird’s root directory (must contain syllable_data/specs/ from Stage A).
rank (int, optional) – Clustering rank to use for automated labels (0 = best-ranked HDBSCAN result). Default is 0.
config (CatalogConfig or None, optional) – Display parameters. Uses default CatalogConfig when None.

Returns:

Absolute path to the generated HTML file, or '' on failure.

Return type:

str

song_phenotyping.catalog.generate_syllable_type_catalog(bird_path, rank=0, label_source='auto', config=None)[source]

Generate an HTML syllable-type catalog for one bird.

For each unique label, renders a grid of up to config.n_per_type individual syllable spectrograms drawn directly from the Stage A HDF5 arrays — no audio files required.

Parameters:

bird_path (str) – Path to the bird’s root directory.
rank (int, optional) – Clustering rank to use when label_source is 'auto'. Default is 0.
label_source ({'auto', 'manual'}, optional) – Which label set to group syllables by. Default is 'auto'.
config (CatalogConfig or None, optional) – Display parameters. Uses default CatalogConfig when None.

Returns:

Absolute path to the generated HTML file, or '' on failure.

Return type:

str