vocalpy.modules package

Submodules

vocalpy.modules.list_of_vocals module

VocalPy - Vocal analysis framework

class vocalpy.modules.list_of_vocals.ListOfVocals(vocals_in_recording=None)

Bases: object

List of vocalizations identified in the recording. Each vocal if an instance of Vocals

Parameters:: vocals_in_recording (List[Vocal]) – list of vocals identified in the recording

add_classification_to_vocals(predictions, classes)

Updates ListOfVocals with the class and probability distribution obtained using the Neural Network

Parameters:

predictions (List[float]) – Neural Network classification predictions for the ListOfVocals
classes (List[str]) – Labels used for classifying vocalizations

add_segmentation_masks_to_vocals(masks)

Updates ListOfVocals with neural-network segmentation masks.

Parameters:: masks (numpy.ndarray) – binary mask predictions shaped (N, H, W)

add_spectrograms_to_vocals(full_spectrogram, full_mask, spec_range=200)

Stores the spectrogram in each Vocal class object in the ListOfVocals

Parameters:

full_spectrogram (ndarray) – complete spectrogram ranging the recording segment
full_mask (ndarray) – complete segmentation mask ranging the recording segment
spec_range (int, optional) – range to crop the spectrogram/segmentation around the vocal (+-200)

combine_list_of_list_of_vocals(list_of_list_of_vocals)

Combines a list of ListOfVocals into one ListOfVocals. Usually called to combine several lists of parallel processing of a recording

Parameters:: list_of_list_of_vocals (List[ListOfVocals]) – list of ListOfVocals

has_cnn_masks()

remove_cnn_masks(): Removes the neural segmentation data from each Vocal in the ListOfVocals

remove_masks(): Removes the segmentation data from each Vocal in the ListOfVocals

remove_spectrograms(): Removes the spectrogram data from each Vocal in the ListOfVocals

remove_visual_data(): Removes transient image payloads from each Vocal.

remove_vocals_classified_as_noise(predictions)

Removes vocals that were classified as noise from the ListOfVocals and updates the number of vocals

Parameters:: predictions (List[float]) – Neural Network classification predictions for the ListOfVocals

save_cnn_masks(output_dir=None)

Saves the neural segmentation mask image to the output directory

Parameters:: output_dir (str, optional) – path to output directory to save the files

save_list_of_vocals_object(path)

Saves a ListOfVocals Object to file

Parameters:: path (str) – path to save the object

save_masks(output_dir=None)

Saves the segmentation mask image to the output directory

Parameters:: output_dir (str, optional) – path to output directory to save the files

save_spectrograms(output_dir=None)

Saves the spectrogram image to the output directory

Parameters:: output_dir (str, optional) – path to output directory to save the files

save_validation_images(output_dir=None)

Saves the spectrogram overlaidd with the segmentation image to the output directory

Parameters:: output_dir (str, optional) – path to output directory to save the files

update_centroids(): Updates centroid coordinates for each vocal. Usually called after combining vocals. Absolute centroid from vocal coordinates start/end, and min/max frequency

update_coords(spec_range=200)

Updates coordinates for each vocal after cropping area around a vocal. Absolute coords from vocal coordinates start/end, and min/max frequency

Parameters:: spec_range (int, optional) – range before/after vocal used to crop and generate spectrograms

update_intervals(): Updates the interval (silence) between vocals. Usually used after combining or removing vocals

vocalpy.modules.recording module

VocalPy - Vocal analysis framework

class vocalpy.modules.recording.Recording(recording_path, args)

Bases: object

Recording Object which contains auxiliary functions to process the recording Concentrates all objects associated with the recording, including: Audio and ListOfVocals

Parameters:

recording_path (str) – Path to audio file to open
args (args) – Struct with arguments that customizes the execution with parameters such as: animal pipeline, bin size, frequency range, threads for parallelization, verbose output

Returns:

recording – The recording object containing the read audio file and its metadata

Return type:

Object

Examples

>>> audio_path = 'path/to/audio'
>>> args = p.parse_args()
>>> recording = Recording(recording_path=audio_path, args=args)

classify_vocalizations(): Classify identified vocalizations using the appropiate animal pipeline

create_animal_pipeline()

Creates an instance of Animal that implements the pipeline for the animal selected by the user

Parameters:: animal (str) – animal pipeline selected by the user
Returns:: class instance – animal pipeline selected by the user
Return type:: Animal

create_dataset(list_of_vocals=None): Creates an image dataset to be used by the Neural Networks

create_paths(recording_path)

Creates directory structure metadata for output files. Image subdirectories are created lazily by the save paths that actually write into them.

Parameters:: recording_path (str)

create_user_parameters_yaml(args)

property group_name

property has_list_of_vocals

Checks if recording has a list of vocals

Returns:: _has_list_of_vocals
Return type:: Bool

identify_vocalizations(): Process recording by calling appropriate animal pipeline functions

identify_vocalizations_finished(): Recording has already been processed -> clear segments

property list_of_vocals

Returns the list of vocals for this recording

Returns:: _list_of_vocals
Return type:: ListOfVocals

load_list_of_vocals(): Loads ListOfVocals from a python object file

remove_spectrograms_and_masks_from_object(list_of_vocals=None)

Removes transient image payloads from the in-memory Vocal objects.

Parameters:: list_of_vocals (ListOfVocals, optional)

remove_vocals_classified_as_noise_from_list_of_vocals(predictions)

Removes vocals that were classified as noise from the ListOfVocals

Parameters:: predictions (List[float]) – Neural Network classification predictions for the ListOfVocals

save_cnn_masks(list_of_vocals=None, path=None)

Saves the neural-network segmentation masks to the output directory.

Parameters:

list_of_vocals (ListOfVocals, optional)
path (str, optional)

save_outputs(validation_flag)

save_recording_data_to_csv(list_of_vocals=None, path=None)

Saves recording metadata to a CSV file. The file will contain information regarding each vocalization identified in the recording.

Parameters:

list_of_vocals (ListOfVocals, optional)
path (str, optional)

save_recording_object(path, filename='recording')

save_spectrograms(list_of_vocals=None, path=None)

Saves the spectrogram images to the output directory for this Recording Object

Parameters:

list_of_vocals (ListOfVocals, optional)
path (str, optional)

save_spectrograms_and_masks(list_of_vocals=None, path=None)

Saves the spectrograms and segmentation images to the output directory for this Recording Object

Parameters:

list_of_vocals (ListOfVocals, optional)
path (str, optional)

save_validation_images(list_of_vocals=None, path=None)

Saves the spectrogram overlaid with the segmentation images to the output directory for this Recording Object

Parameters:

list_of_vocals (ListOfVocals, optional)
path (str, optional)

segment_vocalizations(): Segment identified vocalizations using the configured neural network model.

update_vocals_with_class_classification(predictions, classes)

Updates ListOfVocals with the class and probability distribution obtained using the Neural Network

Parameters:

predictions (List[float]) – Neural Network classification predictions for the ListOfVocals
classes (List[str]) – Labels used for classifying vocalizations

update_vocals_with_segmentation_masks(predictions)

Updates ListOfVocals with neural-network segmentation masks.

Parameters:: predictions (numpy.ndarray) – segmentation mask predictions for each vocal

vocalpy.modules.viz module

VocalPy visualization helpers.

class vocalpy.modules.viz.GroupViz(list_of_viz, group_name, bin_size)

Bases: _BaseViz

Aggregate visualization object for a group of recordings.

class vocalpy.modules.viz.SingleViz(recording_path=None, bin_size=1)

Bases: _BaseViz

Visualization object for a single recording.

create_list_of_vocals()

create_object_dataframe()

class vocalpy.modules.viz.Viz(list_of_groups, group_names=None, bin_size=1)

Bases: object

Visualization object for plotting data from one or more recordings.

combine_viz(list_of_viz, groupname)

combine_viz_dataframes(list_of_viz=None)

create_group_viz()

create_viz_for_each_recording()

generate_group_names()

group_pointplot(dataname='avg_freq')

property list_of_groups

plot(plot_type='group', dataname='avg_freq')

plot_group(dataname)

plot_individual(dataname)

vocalpy.modules.vocal module

VocalPy - Vocal analysis framework

class vocalpy.modules.vocal.Vocal(bin_number=None, start=None, end=None, start_coord=None, end_coord=None, duration=None, interval=None, min_freq=None, max_freq=None, min_freq_coord=None, max_freq_coord=None, avg_freq=None, bandwidth=None, min_intensity=None, max_intensity=None, avg_intensity=None, bg_intensity=None, area=None, centroid=None, orientation=None, coords=None, spectrogram=None, mask=None, cnn_mask=None, probabilities=None, top1=None, top2=None)

Bases: object

Vocalization object stores metadata abouteach vocal identified in the recording

Parameters:

bin_number (float, int) – bin number for this vocal (if recording uses 1 minute bins, bin indicates which minute the vocal happened)
start (float, optional) – vocal start time in the recording
end (float, optional) – vocal end time in the recording
start_coord (float, optional) – vocal start coordinate in the recording spectrogram
end_coord (float, optional) – vocal end coordinate in the recording spectrogram
duration (float, optional) – vocal duration in seconds
interval (float, optional) – distance from last vocal in seconds
min_freq (float, optional) – vocal minimum frequency
max_freq (float, optional) – vocal maximum frequency
min_freq_coord (float, optional) – vocal minimum frequency coordinate in the spectrogram
max_freq_coord (float, optional) – vocal maximum frequency coordinate in the spectrogram
avg_freq (float, optional) – vocal average frequency
bandwidth (float, optional) – vocal bandwidth (maximum frequency - minimum frequency)
min_intensity (float, optional) – vocal minimum intensity in decibel
max_intensity (float, optional) – vocal maximum intensity in decibel
avg_intensity (float, optional) – vocal average intensity in decibel
bg_intensity (float, optional) – background average intensity in decibel
area (float, optional) – vocal area in pixels
centroid (float, optional) – vocal centroid coordinates in the spectrogram
orientation (float, optional) – vocal orientation (slope)
coords (float, optional) – vocal coordinates in the spectrogram
spectrogram (ndarray, optional) – spectrogram (image)
mask (ndarray, optional) – segmentation (image)
cnn_mask (ndarray, optional) – segmentation from neural network (image)
probabilities (List[float], optional) – classes probability distribution from the neural network
top1 (str, optional) – top 1 class from the neural network
top2 (str, optional) – top 2 class from the neural network

property area

property avg_freq

property avg_intensity

property bandwidth

property bg_intensity

property bin_number

property centroid

property cnn_mask

property coords

property duration

property end

property end_coord

property interval

property mask

property max_freq

property max_freq_coord

property max_intensity

property min_freq

property min_freq_coord

property min_intensity

property orientation

property probabilities

save_cnn_mask_as_image(path=None, filename='vocal')

save_mask_as_image(path=None, filename='vocal')

save_spectrogram_as_image(path=None, filename='vocal')

save_spectrogram_with_segmentation_as_image(path=None, filename='vocal')

property spectrogram

property start

property start_coord

property top1

property top2

Module contents

vocalpy modules

modules for processing audio recordings and vocalizations