src.model.deeplearn.sequencer.dl_abstract_sequencer

Classes

DLAbstractSequencer(X, y, batch_size, **kwargs)

class src.model.deeplearn.sequencer.dl_abstract_sequencer.DLAbstractSequencer(X, y, batch_size, **kwargs)

Author:: Alberto M. Esmoris Pena

A deep learning sequencer governs how the input data is fed to a neural network. The abstract sequencer for deep learning models provides common logic for different sequencers. It cannot be used directly because it is an abstract class, hence it must be extended by a concrete implementation.

Variables:

X – The input data.
y – The input reference values.
arch (Architecture) – The neural network architecture.
batch_size (int) – The number of elements per batch.
random_shuffle_indices (bool) – Flag governing whether the indexing of the elements (i.e., the order in which they are given) must be shuffled or not (typically at the end of each epoch).
getitem_method – The method that must be called by DLAbstractSequencer.__getitem__(). It might change depending on whether training or predictive mode is enabled.
on_epoch_end_method – The method that must be called by DLAbstractSequencer.on_epoc_end(). It might change depending on whether training or predictive mode is enabled.
Irandom – A cache for the random shuffle of elements’ indices.
shuffled – A cache to track whether the elements have been shuffled (True) or not (False).

__init__(X, y, batch_size, **kwargs)

Initialize the member attributes of the DLAbstractSequencer.

Parameters:

X – The input data.
y – The input reference values.
batch_size (int) – The number of elements per batch.
kwargs – The key-word specification to parametrize the sequencer.

on_epoch_end()

Logic to handle the dataset between epochs.

Note that this method can work for training, in which case it calls the DLAbstractSequencer.on_epoch_training() method (or its child/derived class override), but it can also work for predictions, in which case it calls the DLAbstractSequencer.on_epoch_predict().

See DLAbstractSequencer.on_epoch_end_training(), DLAbstractSequencer.enable_training_mode(), See DLAbstractSequencer.on_epoch_end_predict(), and DLAbstractSequencer.enable_predict_mode(),

Returns:: Nothing at all, but the internal state of the sequencer is updated.

set_input_data(X, y)

Set the input data for the sequencer. Note that this method must be overridden for any non-abstract implementation that has a different logic for setting the input data that this baseline method.

Parameters:

X – The input data.
y – The input reference values.

Returns:

Nothing at all, but the internal state of the sequencer is updated with the new input data.

get_input_data()

Get the input data of the sequencer.

Returns:: A 2-tuple with the input training data (first element) and the corresponding references (second element)
Return type:: tuple

augment(batch_X)

Augment the given batch. Note that, by default, no data augmentation is applied. However, some sequencers can override this method to provide their own data augmentation logic. Note also that, by default, the augment method is not called. Thus, sequencers providing data augmentation logic should also call this method (typically inside their getitem_training method). The data augmentation logic must be provided inside the augment method so it can be properly handled by decorators like DLOfflineSequencer.

Parameters:: batch_X – The input batch to be augmented.
Returns:: The input batch as received.

abstractmethod getitem_training(idx)

Method that provides the logic for DLAbstractSequencer.__getitem__() in training contexts. It must be overridden by any derived class of DLAbstractSequencer that aims to being concrete (non-abstract, i.e., actually callable).

Parameters:: idx (int) – The index identifying the batch that must be obtained.
Returns:: The batch corresponding to the given index as a tuple (X, y).
Return type:: tuple

on_epoch_end_training()

Method that provides the logic for DLAbstractSequencer.on_epoch_end() in training contexts. It can be overridden by any derived class of DLAbstractSequencer to change ts behavior.

The default logic to handle the dataset between epochs provided by DLAbstractSequencer is the random shuffle of the data so the input batches are given in a different order at each training epochs.

See DLAbstractSequencer.init_random_indices() and DLAbstractSequencer.apply_random_indices() methods.

Returns:: Nothing at all, but the internal state of the sequencer is updated.

enable_training_mode()

Enable the training mode of the sequencer so it can be used for training.

See DLAbstractSequencer.__getitem__() and DLAbstractSequencer.getitem_training().

Returns:: Nothing at all but the DLAbstractSequencer state is updated to operate on training mode.

abstractmethod getitem_predict(idx)

Method that provides the logic for DLAbstractSequencer.__getitem__() in prediction contexts. It must be overridden by any derived class of DLAbstractSequencer that aims to being concrete (non-abstract, i.e., actually callable).

Parameters:: idx (int) – The index identifying the batch that must be obtained.
Returns:: The batch corresponding to the given index but without references.

on_epoch_end_predict()

Method that provides the logic for DLAbstractSequencer.on_epoch_end() in prediction contexts. It can be overridden by any derived class of DLAbstractSequencer to change its behavior.

The default logic to handle the dataset between epochs provided by DLAbstractSequencer is to do nothing.

Returns:: Nothing at all, but the internal state of the sequencer is updated.

enable_predict_mode()

Enable the predict mode of the sequencer so it can be used for predictions.

See DLAbstractSequencer.__getitem__() and DLAbstractSequencer.getitem_predict().

Returns:: Nothing at all but the DLAbstractSequencer state is updated to operate on predict mode.

abstractmethod init_random_indices()

Method that must provide the logic to initialize the random indices to shuffle the data.

See DLAbstractSequencer.on_epoch_end_training().

Returns:: Nothing at all but the internal state of the DLAbstractSequencer is updated (e.g., the self.Irandom cache).

abstractmethod apply_random_indices()

Method that must provide the logic to apply the random shuffle based on the random indices computed by the DLAbstractSequencer.init_random_indices() method.

See DLAbstractSequencer.on_epoch_end_training() and DLAbstractSequencer.init_random_indices().

Returns:: Nothing at all but the internal state of the DLAbstractSequencer is updated (e.g., the self.X and self.y data).

extract_input_batch(start_idx, end_idx)

Extract the input batch inside the given indexing interval.

Note that this method can be overridden by any derived class of DLAbstractSequencer that needs to change its behavior.

Parameters:

start_idx – Start point of the indexing interval (inclusive).
end_idx – End point of the indexing interval (exclusive).

Returns:

The extracted input batch inside the indexing interval.

Return type:

list or np.ndarray

extract_reference_batch(start_idx, end_idx)

Extract the reference batch inside the given indexing interval.

Note that this method can be overridden by any derived class of DLAbstractSequencer that needs to change its behavior.

Parameters:

start_idx – Start point of the indexing interval (inclusive).
end_idx – End point of the indexing interval (exclusive).

Returns:

The extracted reference batch inside the indexing interval.

Return type:

np.ndarray

post_process_output(z_rf)

Post-process the outputs computed on the receptive fields. There might be no need for a post-processing at all, but some sequencers will need it (e.g., DLSparseConcatSequencer).

Parameters:: z_rf (np.ndarray or tf.Tensor or list) – The outputs computed on the receptive fields
Returns:: The post-processed output.
Return type:: np.ndarray or tf.Tensor or list