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