Data feeder

For most common applications in bioacoustics, SpectralDataFeeder offers a convenient way to convert prepared audio clips into spectrograms on-the-fly during training/validation. DataFeeder does not apply any transformations and feeds audio clips as-is. Both these classes may be extended to add additional functionalities, change or add new transformation functions, and to include on-the-fly data augmentations.

For processing prepared data generated by mechanisms outside of Koogu, extend koogu.data.feeder.BaseFeeder to implement custom logic to feed your data into the Koogu training pipeline.

class koogu.data.feeder.SpectralDataFeeder(data_dir, fs, spec_settings, **kwargs)

Bases: DataFeeder

A handy data feeder, which converts prepared audio clips into power spectral density spectrograms.

Parameters:

data_dir – Directory under which prepared data (.npz files) are available.
fs – Sampling frequency of the prepared data.
spec_settings – A Python dictionary. For a list of possible keys and values, see parameters to Audio2Spectral.
normalize_clips – (optional; boolean) If True (default), input clips will be normalized before applying transform (computing spectrograms).
cache – (optional; boolean) If True (default), the logic to ‘queue & batch’ training/evaluation samples (loaded from disk) will also cache the samples. Helps speed up processing.

Other parameters applicable to the parent DataFeeder class may also be specified.

class koogu.data.feeder.DataFeeder(data_dir, validation_split=None, min_clips_per_class=None, max_clips_per_class=None, random_state_seed=None, **kwargs)

Bases: BaseFeeder

A class for loading prepared data from numpy .npz files and feeding them untransformed into the training/evaluation pipeline.

Parameters:

data_dir – Directory under which prepared data (.npz files) are available.
validation_split – (default: None) Fraction of the available data that must be held out for validation. If None, all available data will be used as training samples.
min_clips_per_class – (default: None) The minimum number of per-class samples that must be available. If fewer samples are available for a class, the class will be omitted. If None, no classes will be omitted.
max_clips_per_class – (default: None) The maximum number of per-class samples to consider among what is available, for each class. If more samples are available for any class, the specified number of samples will be randomly selected. If None, no limits will be imposed.
random_state_seed – (default: None) A seed (integer) used to initialize the psuedo-random number generator that makes shuffling and other randomizing operations repeatable.
cache – (optional; boolean) If True (default), the logic to ‘queue & batch’ training/evaluation samples (loaded from disk) will also cache the samples. Helps speed up processing.

class koogu.data.feeder.BaseFeeder(data_shape, num_training_samples, num_validation_samples, class_names, **kwargs)

Base class defining the interface for implementing feeder classes for building data pipelines in Koogu.

Parameters:

data_shape – Shape of the input samples presented to the model.
num_training_samples – List of per-class counts of training samples available.
num_validation_samples – List of per-class counts of validation samples available.
class_names – List of names (str) corresponding to the different classes in the problem space.

get_shape_transformation_info()

Override in inherited class if its transform() alters the shape of the read/input data before a dataset is returned. If not None, must return a tuple where:

first value is the untransformed input shape,
second is the actual transformation function.

abstract make_dataset(is_training, batch_size, **kwargs)

This function must be implemented in the derived class.

It should contain logic to load training & validation data (usually from stored files) and construct a TensorFlow Dataset.

Parameters:

is_training – (boolean) True if operating in training mode.
batch_size – (integer) Number of input samples from the dataset to combine in a single batch.

Returns:

A tf.data.Dataset

abstract post_transform(sample, label, is_training, **kwargs)

Implement this method in the derived class to apply any post-transformation augmentations to a single input to the model (during training and validation).

Parameters:

sample – The transformed sample to which to apply augmentations.
label – The class info pertaining to sample.
is_training – (boolean) True if operating in training mode.
kwargs – Any additional parameters.

Returns:

A 2-tuple containing transformed sample and label.

abstract pre_transform(sample, label, is_training, **kwargs)

Implement this method in the derived class to apply any pre-transformation augmentations to a single input to the model (during training and validation).

Parameters:

sample – The untransformed sample to which to apply augmentations.
label – The class info pertaining to sample.
is_training – (boolean) True if operating in training mode.
kwargs – Any additional parameters.

Returns:

A 2-tuple containing transformed sample and label.

abstract transform(sample, label, is_training, **kwargs)

This function must be implemented in the derived class.

It should contain logic to apply any transformations to a single input to the model (during training and validation).

Parameters:

sample – The sample that must be ‘transformed’ before consumption by a model.
label – The class info pertaining to sample.
is_training – (boolean) True if operating in training mode.
kwargs – Any additional parameters.

Returns:

A 2-tuple containing transformed sample and label.

property class_names: List of names (str) of the classes in the application.

property data_shape: The shape of an input sample.

property num_classes: The number of classes in the application.

property training_samples: List of per-class training samples available.

property training_samples_per_class: List of per-class validation samples available.

property validation_samples: Total number of training samples available.

property validation_samples_per_class: Total number of validation samples available.