chatter.analyzer

chatter.analyzer#

Classes

Analyzer(config[, n_jobs])

Main analysis class for audio preprocessing, segmentation, and spectrogram creation.
class chatter.analyzer.Analyzer(config, n_jobs=-1)[source]#

Main analysis class for audio preprocessing, segmentation, and spectrogram creation.

This class encapsulates the end-to-end pipeline for preparing audio data for autoencoder-based analyses. It provides methods for preprocessing audio files, segmenting them into syllable-like units, storing unit spectrograms in an HDF5 file, and managing associated metadata.

config#

Configuration dictionary containing all pipeline parameters, including audio preprocessing, spectrogram generation, and segmentation settings.

Type:

dict

n_jobs#

Number of parallel worker processes used for preprocessing and segmentation steps.

Type:

int

__init__(config, n_jobs=-1)[source]#

Initialize the Analyzer with a configuration and optional parallelism.

Parameters:

  • config (dict) – Configuration dictionary containing all pipeline parameters.

  • n_jobs (int, optional) – Number of parallel jobs to run for preprocessing and segmentation. If set to -1, all available CPU cores are used. The default is -1.

extract_species_clips(input_dir, output_dir, species, confidence_threshold=0.5, buffer_seconds=1.0, batch_size=None)[source]#

Recursively find audio files, detect a species, and export clips.

This method scans an input directory for audio files, runs BirdNET to detect a specific species, and saves the resulting audio clips to an output directory that mirrors the input’s structure. The process is executed in parallel across multiple CPU cores.

Parameters:

  • input_dir (str or Path) – The root directory to search for audio files.

  • output_dir (str or Path) – The root directory where the output clips will be saved.

  • species (str) – The common name of the target species to detect (e.g., “House Finch”).

  • confidence_threshold (float, optional) – The minimum confidence level (0-1) for a detection to be included. The default is 0.5.

  • buffer_seconds (float, optional) – The number of seconds to add to the start and end of each detected clip. The default is 1.0.

  • batch_size (int, optional) – Number of files to process per batch in each parallel submission. If None, a default value of ‘n_jobs * 2’ is used.

preprocess_directory(input_dir, processed_dir, batch_size=None)[source]#

Preprocess all audio files in a directory and its subdirectories.

This method performs batch preprocessing of audio files by calling ‘_preprocess_wav_worker’ in parallel. All supported audio file formats are discovered recursively under ‘input_dir’, preprocessed, and saved as standardized WAV files under ‘processed_dir’, preserving the directory structure.

Parameters:

  • input_dir (str or Path) – Directory containing raw audio files in various formats.

  • processed_dir (str or Path) – Directory in which to save preprocessed WAV files. The directory structure mirrors that of ‘input_dir’.

  • batch_size (int, optional) – Number of files to process per batch in each parallel submission. If None, a default value of ‘n_jobs * 2’ is used. The default is None.

Returns:

This method writes preprocessed files to disk and prints progress information but does not return a value.

Return type:

None

demo_preprocessing(input_dir)[source]#

Process a single random file (or segment) from the directory in memory and plot a comparison.

This function replicates the production preprocessing pipeline logic on a slice of audio defined by ‘plot_clip_duration’. It prioritizes segments with active audio content.

Parameters:

input_dir (str or Path) – Directory containing audio files to process.

segment_and_create_spectrograms(processed_dir, h5_path, csv_path, simple=False, batch_size=None, presegment_csv=None)[source]#

Segment files and save spectrograms, optionally from a pre-segmented CSV.

If presegment_csv is provided, this method bypasses internal segmentation. Instead, it reads the given CSV for ‘source_file’, ‘onset’, and ‘offset’ information and generates spectrograms for those specific time slices.

If presegment_csv is None, it scans a directory of preprocessed WAV files, segments each file into syllable-like acoustic units using internal methods, converts segments into spectrograms, and stores them.

Parameters:

  • processed_dir (str or Path) – Directory containing preprocessed WAV files.

  • h5_path (str or Path) – Path to the output HDF5 file for spectrograms.

  • csv_path (str or Path) – Path to the CSV file for unit metadata.

  • simple (bool, optional) – If True, use simple amplitude-based segmentation. Default is False.

  • batch_size (int, optional) – Number of files to process per batch in parallel. Default is ‘n_jobs’.

  • presegment_csv (str or Path, optional) – Path to a CSV file with pre-defined segmentations. If provided, internal segmentation is skipped. Default is None.

Returns:

DataFrame containing metadata for all units.

Return type:

pd.DataFrame

demo_segmentation(input_dir, simple=False)[source]#

Segment a random file (or clip) in memory and visualize it.

This function picks a random audio file, applies the configured segmentation algorithm (simple or pykanto) to a specific clip, and plots the results matching the visual style of ‘plot_detected_units’.

Parameters:

  • input_dir (str or Path) – Directory containing audio files to process.

  • simple (bool, optional) – If True, use simple amplitude-based segmentation. If False, use image-based segmentation (pykanto). The default is False.

load_df(metadata_csv_path)[source]#

Load a DataFrame from a CSV file containing unit metadata.

Parameters:

metadata_csv_path (str or Path) – Path to the CSV file containing unit metadata.

Returns:

Loaded DataFrame if the file is found and successfully read. Returns None if the file is not found.

Return type:

pd.DataFrame or None

Contents