contourusv package

Submodules

contourusv.detection module

contourusv.detection.detect_contours(cleaned_image, start_time, end_time, freq_min, freq_max, file_name, annotations, call_type_defs=None, processing='adaptive')

Detect and classify USVs in cleaned spectrogram images.

Parameters:

• cleaned_image (ndarray) – Preprocessed spectrogram image (2D array)

• start_time (float) – Start time of current processing window (seconds)

• end_time (float) – End time of current processing window (seconds)

• freq_min (float) – Minimum frequency bound for detection (kHz)

• freq_max (float) – Maximum frequency bound for detection (kHz)

• file_name (Path) – Source audio file path

• annotations (list) – List to accumulate detection annotations

Returns:

(annotated_image, updated_annotations) annotated_image: RGB image with detection bounding boxes updated_annotations: List of annotation dictionaries

Return type:

tuple

contourusv.evaluation module

contourusv.evaluation.evaluate_predictions(filename, sample_labels, predicted_sample_labels, total_samples)

Calculate evaluation metrics for USV predictions.

Parameters:

• filename (str) – Name of the audio file being evaluated

• sample_labels (ndarray) – Ground truth binary labels (1=USV present)

• predicted_sample_labels (ndarray) – Predicted binary labels (1=USV detected)

• total_samples (int) – Total number of samples in audio file

Returns:

Evaluation metrics dictionary with keys: [‘Filename’, ‘TP’, ‘FP’, ‘TN’, ‘FN’, ‘Precision’, ‘Recall’, ‘F1 Score’, ‘Specificity’]

Return type:

dict

contourusv.evaluation.get_sample_labels(audio_file, actual_labels, predicted_labels)

Convert time-based annotations to sample-wise binary labels.

Parameters:

• audio_file (Path) – Path to audio file

• actual_labels (DataFrame) – Ground truth annotations

• predicted_labels (DataFrame) – Detected USV annotations

Returns:

(sample_labels, predicted_sample_labels, total_samples) sample_labels: Ground truth binary array predicted_sample_labels: Detection binary array total_samples: Length of audio file in samples

Return type:

tuple

contourusv.evaluation.has_columns(file_path, delimiter=',')

contourusv.evaluation.load_annotation(predicted_labels, actual_labels)

contourusv.evaluation.run_evaluation(experiment, trial, root_path)

Run full evaluation pipeline for an experiment.

Parameters:

• experiment (str) – Experiment name

• trial (str) – Trial/condition name

• root_path (Path) – Root data directory

• Outputs

• -------

• to (Saves evaluation results CSV)

• {root_path}/output/{experiment}/{trial}/evaluation_results/

contourusv.generate_annotation module

contourusv.generate_annotation.generate_annotations(experiment, trial, root_path, file_ext)

Generate ground truth annotations for all audio files in experiment.

Parameters:

• experiment (str) – Experiment name

• trial (str) – Trial/condition name

• root_path (Path) – Root data directory

• file_ext (str) – Annotation file extension (.html, .xlsx, .csv)

Raises:

ValueError – If invalid file extension is provided

contourusv.generate_annotation.load_csv_usv(file_name)

Load simple timestamp annotations from CSV file.

Parameters:

file_name (Path) – Path to CSV annotation file

Returns:

Processed annotations with columns: [‘begin_time’, ‘end_time’]

Return type:

DataFrame

contourusv.generate_annotation.load_excel_usv(file_name)

Load USV annotations from Excel file.

Parameters:

file_name (Path) – Path to Excel annotation file (.xlsx)

Returns:

Processed annotations with columns: [‘begin_time’, ‘end_time’, ‘low_freq’, ‘high_freq’, ‘usv_type’]

Return type:

DataFrame

contourusv.generate_annotation.load_html_usv(file_name)

Load USV annotations from DeepSqueak HTML file.

Parameters:

file_name (Path) – Path to DeepSqueak HTML annotation file

Returns:

Processed annotations with columns: [‘begin_time’, ‘end_time’, ‘usv_type’]

Return type:

DataFrame

contourusv.generate_annotation.save_annotations(files, audio_file_name, output_path, file_ext, freq_min=18000, freq_max=30000)

Convert annotation files to standardized format and save.

Parameters:

• files (list) – List of annotation file paths

• audio_file_name (Path) – Corresponding audio file path

• output_path (Path) – Directory to save processed annotations

• file_ext (str) – Annotation file type (.html, .xlsx, .csv)

• freq_min (int, optional) – Default minimum frequency (Hz) for CSV/HTML (default: 18000)

• freq_max (int, optional) – Default maximum frequency (Hz) for CSV/HTML (default: 30000)

contourusv.main module

contourusv.main.low_pass_filter(data, cutoff, fs, order=5)

Apply a Butterworth low-pass filter to input data.

Parameters:

• data (ndarray) – Input signal to be filtered

• cutoff (float) – Cutoff frequency in Hz

• fs (float) – Sampling frequency in Hz

• order (int, optional) – Filter order (default: 5)

Returns:

Filtered output signal

Return type:

ndarray

contourusv.main.run_detection(root_path, file_name, experiment, trial, overlap=3, winlen=10, freq_min=15, freq_max=115, wsize=2500, th_perc=95, processing='none', overlapsize=0.25)

Process audio file to detect ultrasonic vocalizations (USVs).

Parameters:

• root_path (Path) – Root directory for input/output data

• file_name (Path) – Path to audio file to process

• experiment (str) – Name of the experiment

• trial (str) – Name of the trial/condition

• overlap (int, optional) – Overlap between processing windows in seconds (default: 3)

• winlen (int, optional) – Window length for processing in seconds (default: 10)

• freq_min (int, optional) – Minimum frequency for USV detection in kHz (default: 15)

• freq_max (int, optional) – Maximum frequency for USV detection in kHz (default: 115)

• wsize (int, optional) – Spectrogram window size (default: 2500)

• th_perc (float, optional) – Percentile threshold for noise reduction (default: 95)

• processing (str, optional) – Type of preprocessing to apply Otsu/Adaptive(default: ‘adaptive’)

• overlapsize (int, optional) – Defines size of overlap window as a percentage (defailt: .25)

Returns:

Outputs: - Annotated spectrogram images in {root_path}/output/spectrograms/ - Detection annotations in {root_path}/output/contour_detections/

Return type:

None

contourusv.main.use_ICA(Sxx)

Perform Independent Component Analysis (ICA) on the input spectrogram.

Parameters:

Sxxndarray

Input spectrogram to process.

Returns:

ndarray

Transformed spectrogram after ICA.

contourusv.main.use_NMF(Sxx, n_components=30)

Perform Non-negative Matrix Factorization (NMF) on the input spectrogram.

Parameters:

Sxxndarray

Input spectrogram to process.

n_componentsint

Components to split for NMF (default: 30)

Returns:

ndarray

Transformed spectrogram after NMF.

contourusv.main.use_NMF_Small(Sxx, num_splits=120, n_components=25)

Perform Non-negative Matrix Factorization (NMF) on the input spectrogram by splitting it into parts and applying NMF with specified components on each block. This segmentation allows better capture of properties of the signal when it is non-stationary.

Parameters:

Sxxndarray

Input spectrogram to process.

num_splitsint, optional

Number of segments to divide the spectrogram into (default: 80).

n_componentsint, optional

Number of NMF components (default: 25).

Returns:

ndarray

Transformed spectrogram after NMF.

contourusv.preprocessing module

contourusv.preprocessing.clean_spec_imp(Sxx)

Improved preprocessing of spectrogram data for USV detection, using adaptive theshholding.

Parameters:

Sxx (ndarray) – Input spectrogram (2D array in dB scale)

Returns:

Preprocessed binary image (2D uint8 array)

Return type:

ndarray

contourusv.preprocessing.clean_spec_orig(Sxx)

Preprocess spectrogram data for USV detection using Otsu’s threshholding and CLAHE contrast enhancement.

Processing steps: 1. Median filtering 2. Normalization (0-255) 3. Otsu’s thresholding 4. CLAHE contrast enhancement 5. Morphological closing

Parameters:

Sxx (ndarray) – Input spectrogram (2D array in dB scale)

Returns:

Preprocessed binary image (2D uint8 array)

Return type:

ndarray

Module contents