mltk.core.DatasetMixin

class DatasetMixin[source]

Provides generic dataset properties to the base MltkModel

Refer to te Model Specification guide for more details.

Properties

class_counts

Dictionary of samples counts for each class

class_weights

Specifies how class weights should be calculated.

dataset

The model dataset

loaded_subset

training, validation, evaluation

sample_weight

Optional Numpy array of weights for the training samples, used for weighting the loss function (during training only).

shuffle

Boolean (whether to shuffle the training data before each epoch) or str (for 'batch').

steps_per_epoch

Integer or None.

validation_batch_size

Integer or None.

validation_data

Data on which to evaluate the loss and any model metrics at the end of each epoch.

validation_freq

Only relevant if validation data is provided.

validation_split

Float between 0 and 1 Fraction of the training data to be used as validation data.

validation_steps

Only relevant if validation_data is provided and is a tf.data dataset.

x

Input data

y

Target data

Methods

__init__

load_dataset

Load the dataset

summarize_dataset

Summarize the dataset

unload_dataset

Unload the dataset

property x

Input data

It could be:

  • A Numpy array (or array-like), or a list of arrays (in case the model has multiple inputs).

  • A TensorFlow tensor, or a list of tensors (in case the model has multiple inputs).

  • A dict mapping input names to the corresponding array/tensors, if the model has named inputs.

  • A tf.data dataset. Should return a tuple of either (inputs, targets) or (inputs, targets, sample_weights).

  • A generator or keras.utils.Sequence returning (inputs, targets) or (inputs, targets, sample_weights). A more detailed description of unpacking behavior for iterator types (Dataset, generator, Sequence) is given below.

property y

Target data

Like the input data x, it could be either Numpy array(s) or TensorFlow tensor(s). It should be consistent with x (you cannot have Numpy inputs and tensor targets, or inversely). If x is a dataset, generator, or keras.utils.Sequence instance, y should not be specified (since targets will be obtained from x).

property validation_split

Float between 0 and 1 Fraction of the training data to be used as validation data. The model will set apart this fraction of the training data, will not train on it, and will evaluate the loss and any model metrics on this data at the end of each epoch. The validation data is selected from the last samples in the x and y data provided, before shuffling. This argument is not supported when x is a dataset, generator or keras.utils.Sequence instance.

property validation_data

Data on which to evaluate the loss and any model metrics at the end of each epoch. The model will not be trained on this data. Thus, note the fact that the validation loss of data provided using validation_split or validation_data is not affected by regularization layers like noise and dropout. validation_data will override validation_split. validation_data could be:

  • tuple (x_val, y_val) of Numpy arrays or tensors

  • tuple (x_val, y_val, val_sample_weights) of Numpy arrays

  • dataset For the first two cases, batch_size must be provided. For the last case, validation_steps could be provided. Note that validation_data does not support all the data types that are supported in x, eg, dict, generator or keras.utils.Sequence.

property shuffle

Boolean (whether to shuffle the training data before each epoch) or str (for ‘batch’). This argument is ignored when x is a generator. ‘batch’ is a special option for dealing with the limitations of HDF5 data; it shuffles in batch-sized chunks. Has no effect when steps_per_epoch is not None.

property class_weights

Specifies how class weights should be calculated. Default: None

This can be useful to tell the model to “pay more attention” to samples from an under-represented class.

May be one of the following:

  • If balanced is given, class weights will be given by: n_samples / (n_classes * np.bincount(y))

  • If a dictionary is given, keys are classes and values are corresponding class weights.

  • If None is given, the class weights will be uniform.

property class_counts

Dictionary of samples counts for each class

This is used for generating a summary of the dataset or when calculating class weights when my_model.class_weights=balanced.

The dictionary may contain sub-dictionaries for each subset of the dataset, e.g.:

my_model.class_counts = dict(
    training = dict(
        cat = 100,
        dog = 200,
        goat = 500
    ),
    validation = dict(
        cat = 10,
        dog = 20,
        goat = 50
    ),
    evaluation = dict(
        cat = 10,
        dog = 20,
        goat = 50
    )
)

Or it may contain just class/counts, e.g.:

my_model.class_counts = dict(
    cat = 100,
    dog = 200,
    goat = 500
)
property sample_weight

Optional Numpy array of weights for the training samples, used for weighting the loss function (during training only). You can either pass a flat (1D) Numpy array with the same length as the input samples (1:1 mapping between weights and samples), or in the case of temporal data, you can pass a 2D array with shape (samples, sequence_length), to apply a different weight to every timestep of every sample. This argument is not supported when x is a dataset, generator, or keras.utils.Sequence instance, instead provide the sample_weights as the third element of x.

property steps_per_epoch

Integer or None. Total number of steps (batches of samples) before declaring one epoch finished and starting the next epoch. When training with input tensors such as TensorFlow data tensors, the default None is equal to the number of samples in your dataset divided by the batch size, or 1 if that cannot be determined. If x is a tf.data dataset, and ‘steps_per_epoch’ is None, the epoch will run until the input dataset is exhausted. When passing an infinitely repeating dataset, you must specify the steps_per_epoch argument. This argument is not supported with array inputs.

property validation_steps

Only relevant if validation_data is provided and is a tf.data dataset. Total number of steps (batches of samples) to draw before stopping when performing validation at the end of every epoch. If ‘validation_steps’ is None, validation will run until the validation_data dataset is exhausted. In the case of an infinitely repeated dataset, it will run into an infinite loop. If ‘validation_steps’ is specified and only part of the dataset will be consumed, the evaluation will start from the beginning of the dataset at each epoch. This ensures that the same validation samples are used every time.

property validation_batch_size

Integer or None. Number of samples per validation batch. If unspecified, will default to batch_size. Do not specify the validation_batch_size if your data is in the form of datasets, generators, or keras.utils.Sequence instances (since they generate batches).

property validation_freq

Only relevant if validation data is provided. Integer or collections_abc.Container instance (e.g. list, tuple, etc.). If an integer, specifies how many training epochs to run before a new validation run is performed, e.g. validation_freq=2 runs validation every 2 epochs. If a Container, specifies the epochs on which to run validation, e.g. validation_freq=[1, 2, 10] runs validation at the end of the 1st, 2nd, and 10th epochs.

property loaded_subset

training, validation, evaluation

Type:

The currently loaded dataset subset

property dataset

The model dataset

The value of this is dependent on the implementation of this model’s load_dataset() method.

By default, this may be one of the following:

def my_dataset_loader(subset: str, test:bool, **kwargs):
    # Arguments:
    #    subset: The dataset subset: training, validation or evaluation
    #    test: If true then only load a few samples for testing
    # Returns, one of the following:
    #    - None, in this case the function is expected to set the my_model.x, my_model.y, and/or my_model.validation_data properties
    #    - x - The x samples, in this case the my_model.x properties will be automatically set
    #    - (x, y) - The x samples and y labels. In this case the my_model.x and my_model.y properties will be automatically set
    #    - (x, None, validation_data) - The x samples and validation_data. In this case the my_model.x and my_model.validation_data properties will be automatically set
    ...
  • A reference to a Python class instance, the class should have a method named “load_dataset” that has a similar signature as the function above

  • A reference to a Python module, the module should have a function named “load_dataset” that has a similar signature as the function above

If this model’s load_dataset() API is overridden then it may have a different value. For instance, the mltk.core.AudioDatasetMixin and mltk.core.ImageDatasetMixin override this property. Refer to their documentation for more details.

load_dataset(subset, test=False, **kwargs)[source]

Load the dataset

This is automatically invoked by the MLTK during the train, quantize and evaluation operations. It loads the model dataset and configures the model properties:

  • my_model.loaded_subset

  • my_model.x

  • my_model.y

  • my_model.validation_data

By default, this does the following:

  1. Sets the loaded_subset property

  2. Clears the x, y, validation_data properties

  3. Calls dataset

  4. Sets the x, y and/or validation_data properties based on the return value of dataset

The API may be overridden by:

Parameters:
  • subset (str) – The dataset subset: training, validation or evaluation

  • test (bool) – If true then only load a few samples for testing

Returns:

  • None, in this case the caller is expected to set the my_model.x, my_model.y, and/or my_model.validation_data properties

  • x - The x samples. In this case this API will automatically set the my_model.x properties

  • (x, y) - The x samples and y labels. In this case this API will automatically set the my_model.x and my_model.y properties

  • (x, None, validation_data) - The x samples and validation_data. In this case this API will automatically set the my_model.x and my_model.validation_data properties

Return type:

One of the following

unload_dataset()[source]

Unload the dataset

summarize_dataset()[source]

Summarize the dataset

If my_model.dataset is provided then this attempts to call my_model.dataset.summarize_dataset(). If my_model.dataset is not provided or does not have the summarize_dataset() method, then this attempts to generate a summary from my_model.class_counts.

Return type:

str