Detection

detection sub-module within the ketos.neural_networks.dev_utils module

This module provides auxiliary functions to incorporate pre-trained ketos classifiers models into detection tools

Contents:

ketos.neural_networks.dev_utils.detection.compute_avg_score(score_vector, win_len)[source]

Compute a moving average of the score vector.

Args:
score_vector: numpy array

1d numpy array containing the target class classification score for each input

win_len:int

The window length for the moving average. Must be an odd integer

Returns:
numpy arrays

One numpy arrays with the average scores each time step

ketos.neural_networks.dev_utils.detection.group_detections(scores_vector, batch_support_data, buffer=0.0, step=0.5, spec_dur=3.0, threshold=0.5)[source]

Groups time steps with a detection score above the specified threshold.

Consecutive detections are grouped into one single detection represented by the time interval (start-end, in seconds from beginning of the file).

Args:
scores_vector: numpy array

1d numpy array containing the target class classification score for each input

batch_support_data: numpy array

An array of shape n x 2, where n is the batch size. The second dimension contains the filename and the start timestamp for each input in the batch

buffer: float

Time (in seconds) to be added around the detection

step: float

The time interval(in seconds) between the starts of each contiguous input spectrogram. For example, a step=0.5 indicates that the first spectrogram starts at time 0.0s (from the beginning of the audio file), the second at 0.5s, etc.

spec_dur: float

The duration of each spectrogram in seconds

threshold: float

Minimum score value for a time step to be considered as a detection.

Returns:
det_timestamps:list of tuples

The detections time stamp. Each item in the list is a tuple with the filename, start time, duration and score for that detection. The filename corresponds to the file where the detection started.

ketos.neural_networks.dev_utils.detection.map_detection_to_time(det_start, det_end, batch_start_timestamp, batch_end_timestamp, step, spec_dur, buffer)[source]

Converts the start and end of a detection from the position in the scores vecotr to time.

Args:
det_start: int

The detection start expressed as an index in the scores vector.

det_end: int

The detection end (the last score that is part of the detection) expressed as an index in the scores vector.

batch_start_timestap:float

The timestamp (in seconds from the beginning of the file) of the first score in the scores vector

(i.e.: the score of the first input spectrogram in that batch)

batch_end_timestap:float

The timestamp (in seconds from the beginning of the file) of the last score in the scores vector

(i.e.: the score of the last input spectrogram in that batch)

step: float

The time interval(in seconds) between the starts of each contiguous input spectrogram. For example, a step=0.5 indicates that the first spectrogram starts at time 0.0s (from the beginning of the audio file), the second at 0.5s, etc.

spec_dur: float

The duration of each spectrogram in seconds

buffer: float

Time (in seconds) to be added around the detection.

Raises:
ValueError:

If det_end is lower than det_start

Returns:
time_start, duration:float

The corresponding start (in seconds from the beggining of the file) and duration

ketos.neural_networks.dev_utils.detection.merge_overlapping_detections(detections)[source]

Merge overlapping detection groups

Note: The annotations for each file are assumed to be sorted by start time in increasing order.

Args:
detections: numpy.array

List of detections

Returns:
merged: numpy.array

List of merged detections

ketos.neural_networks.dev_utils.detection.process(provider, **kwargs)[source]

Use classifier to process audio clips (waveform or spectrogram).

Delegates to detection.process_audio_loader() or detection.process_batch_generator() depending on the type of the provider argument.

See these functions for a description of the required input arguments.

Args:

provider: instance of ketos.audio.audio_loader.AudioFrameLoader or ketos.data_handling.data_feeding.BatchGenerator

ketos.neural_networks.dev_utils.detection.process_audio_loader(audio_loader, model, batch_size=128, threshold=0.5, buffer=0, win_len=1, group=False, progress_bar=False)[source]

Use an audio_loader object to compute spectrogram from the audio files and process them with the trained classifier.

The resulting .csv is separated by commas, with each row representing one detection and has the following columns:
filename: The name of the audio file where the detection was registered.

In case the detection starts in one file and ends in the next, the name of the first file is registered.

start: Start of the detection (in seconds from the beginning of the file) end: End of the detection (in seconds from the beginning of the file) score: The sore given to the detection by the trained neural network ([0-1])

Args:
audio_loader: a ketos.audio.audio_loader.AudioFrameLoader object

An audio loader that computes spectrograms from the audio audio files as requested

model: ketos model

The ketos trained classifier

batch_size:int

The number of spectrogram to process at a time.

threshold: float

Minimum score value for a time step to be considered as a detection.

buffer: float

Time (in seconds) to be added around the detection

win_len:int

The windown length for the moving average. Must be an odd integer. The default value is 5.

group:bool

If False, return the filename, start, duration and scores for each spectrogram with score above the threshold. In this case, the duration will always be the duration of a single spectrogram. If True (default), average scores over(overlapping) spectrograms and group detections that are immediatelly next to each other. In this case, the score given for that detection will be the average score of all spectrograms comprising the detection event.

progress_bar: bool

Show progress bar.

Returns:
detections: list

List of detections

ketos.neural_networks.dev_utils.detection.process_batch(batch_data, batch_support_data, model, buffer=0, step=0.5, spec_dur=3.0, threshold=0.5, win_len=1, group=False)[source]

Runs one batch of (overlapping) spectrogram throught the classifier.

Args:
batch_data: numpy array

An array with shape n,f,t, where n is the number of spectrograms in the batch, t is the number of time bins and f the number of frequency bins.

batch_support_data: numpy array

An array of shape n x 2, where n is the batch size. The second dimension contains the filename and the start timestamp for each input in the batch

model: ketos model

The ketos trained classifier

buffer: float

Time (in seconds) to be added around the detection

step: float

The time interval(in seconds) between the starts of each contiguous input spectrogram. For example, a step=0.5 indicates that the first spectrogram starts at time 0.0s (from the beginning of the audio file), the second at 0.5s, etc.

spec_dur: float

The duration of each input spectrogram in seconds

threshold: float

Minimum score value for a time step to be considered as a detection.

win_len:int

The windown length for the moving average. Must be an odd integer. The default value is 5.

group:bool

If False, return the filename, start, duration and scores for each spectrogram with score above the threshold. In this case, the duration will always be the duration of a single spectrogram. If True (default), average scores over(overlapping) spectrograms and group detections that are immediatelly next to each other. In this case, the score given for that detection will be the average score of all spectrograms comprising the detection event.

Returns:
batch_detections: list

An array with all the detections in the batch. Each detection (first dimension) consists of the filename, start, duration and score. The start is given in seconds from the beginning of the file and the duration in seconds.

ketos.neural_networks.dev_utils.detection.process_batch_generator(batch_generator, model, duration=3.0, step=0.5, threshold=0.5, buffer=0, win_len=1, group=False)[source]

Use a batch_generator object to process pre-computed spectrograms stored in an HDF5 database with the trained classifier.

The resulting .csv is separated by commas, with each row representing one detection and has the following columns:
filename: The name of the audio file where the detection was registered.

In case the detection starts in one file and ends in the next, the name of the first file is registered.

start: Start of the detection (in seconds from the beginning of the file) end: End of the detection (in seconds from the beginning of the file) score: The sore given to the detection by the trained neural network ([0-1])

Args:
batch_generator: a ketos.data_handling.data_feeding.BatchGenerator object

A batch_generator that loads pre-computed spectrograms from the a HDF5 database files as requested

model: ketos model

The ketos trained classifier

duration: float

The duration of each input spectrogram in seconds

step: float

The time interval(in seconds) between the starts of each contiguous input spectrogram. For example, a step=0.5 indicates that the first spectrogram starts at time 0.0s (from the beginning of the audio file), the second at 0.5s, etc.

threshold: float

Minimum score value for a time step to be considered as a detection.

buffer: float

Time (in seconds) to be added around the detection

win_len:int

The windown length for the moving average. Must be an odd integer. The default value is 5.

group:bool

If False, return the filename, start, duration and scores for each spectrogram with score above the threshold. In this case, the duration will always be the duration of a single spectrogram. If True (default), average scores over(overlapping) spectrograms and group detections that are immediatelly next to each other. In this case, the score given for that detection will be the average score of all spectrograms comprising the detection event.

Returns:
detections: list

List of detections

ketos.neural_networks.dev_utils.detection.save_detections(detections, save_to)[source]

Save the detections to a csv file

Args:
detections: numpy.array

List of detections

save_to:string

The path to the .csv file where the detections will be saved. Example: “/home/user/detections.csv”

ketos.neural_networks.dev_utils.detection.transform_batch(x, y)[source]

Transform the data loaded from the database to the format expected by process_batch

Args:
x: numpy array

A batch of spectrograms of shape batch_size, time bins, frequency bins

y: numpy array

Suppporting information for the batch (the filename and offset fields from the hdf5 dataset)

Returns:
tuple:
transformed_x:numpy array

x, unmodified

transformed_y:numpy array

y reshaped to shape batch_size, 2. type converted to str (from bytes string).