core package

Submodules

core.DeepTransferClassification module

class core.DeepTransferClassification(**kwargs)

Bases: object

This class represents a deep transfer learning classification experiment with customizable settings. It is designed to facilitate and automate the creation, training, and evaluation of various models using optional data augmentation, regularization, and metric tracking. The class provides default settings which can be updated using keyword arguments for a flexible and customizable experiment configuration.

export_all(results, base_path='exports', export_model=True, additive=True)

Wrapper function to export the results, model, and configuration of the training and testing process.

Args:

results (dict): The results of the training and testing process. base_path (str, optional): The base path for saving the exported files. Defaults to “exports”. export_model (bool, optional): Whether to save the model architecture and weights. Defaults to True. additive (bool, optional): Whether to create a new folder with a random name inside the base path. Defaults to True.

export_configuration()

Return the current settings dictionary for the experiment.

get_kwargs()

Get the default configuration settings for the model training and evaluation pipeline.

Returns:

dict: A dictionary containing the default configuration settings for the pipeline, with the following keys:

  • ‘paths’:

    • ‘train_val_data’: str, path to training and validation data folder, default: ‘path_to_train_val_data’

      Note

      This is the expected folder configuration:

      train/
    class_A/
        image_1A.png
        image_2A.png
    class_B/
        image_1B.png
        image_2B.png
val/
    class_A/
        image_3A.png
        image_4A.png
    class_B/
        image_3B.png
        image_4B.png

      The library uses the key words, ‘train’, ‘val’ and ‘test’ for the three sets (the same format is used for the testing data), while the external test name may vary

      If your data is not distributed in this format, you can simply use the DataSplitter from data_management.

    • ‘test_data_folder’: str or None, path to test data folder, default: None

    • ‘external_test_data_folder’: str or None, path to external test data folder, default: None

  • ‘model’:

    • ‘image_size’: tuple, target image re-size (height, width), default: (224, 224)

      Note

      These values are used to resize generators images. It is recommended to use the original input size of the chosen transfer model.

    • ‘transfer_arch’: str, transfer architecture name, default: ‘VGG19’

      Note

      Various transfer architectures are available, you can call them by name (e.g. ‘ResNet101V2’). For a list of available architectures, refer to https://keras.io/api/applications. Don’t forget to update the freeze settings from the previous architecture before loading a new one.

    • ‘pre_trained’: str, which pre-trained weights to load, default: ‘imagenet’

    • ‘before_dense’: str, layer type before dense but after

    transfer architecture layers, default: ‘Flatten’

    Note

    Currently two options exist, Flatten or GlobalAveragePooling2D.

    • ‘dense_layers’: list, number of dense layers after transfer

    architecture and ‘before_dense’ layer argument, default: [256]

    Note

    The number of dense layers is equal to the length of the list.

    • ‘dense_activations’: str, activation function for dense layers, default: ‘elu’

      Note

      For a list of available activations, refer to https://keras.io/api/layers/activations/

    • ‘initializer’: str, dense layer initializer, default: ‘he_normal’

      Note

      For a list of available initializers, refer to https://keras.io/api/layers/initializers/

    • ‘batch_norm’: bool, whether to use batch normalization between dense layers, default: False

    • ‘regularization’: str, regularization type, default: ‘Dropout’

      Note

      The regularization method to apply (‘L1’, ‘L2’, ‘Dropout+L1’, ‘Dropout+L2’, or None).

    • ‘l1_strength’: float, L1 regularization strength, default: 0.001

    • ‘l2_strength’: float, L2 regularization strength, default: 0.001

    • ‘dropout_rate’: float, dropout rate, default: 0.21

    • ‘freeze_weights’: int or None, number of layers to freeze, default: None

      Note

      If set to None, all layers will be trainable. If set to an integer, the last n layers will be frozen.

    • ‘unfreeze_block’: list or None, list of blocks or layers to unfreeze, default: [‘block5’]

      Note

      If set to None, all layers will be trainable. If set to a list, the specified blocks or layer names (as strings) will be unfrozen, e.g., [‘block1’, ‘block2’, ‘block3’].

    • ‘freeze_up_to’: str or None, freeze layers up to a specific block, default: ‘flatten’

      Note

      If set to None, all layers will be trainable. If set to a string, all layers up to the specified block or layer will be frozen. When using both ‘freeze_up_to’ and ‘unfreeze_block’, it is possible to selectively unfreeze layers or blocks within the ‘freeze_up_to’ range.

    • ‘show_freeze_status’: bool, whether to show layer freeze status, default: True

    • ‘number_of_targets’: int, number of target classes

      Warning

      This argument is automatically updated based on the number of classes in the training data. Do not modify it unless you are certain about the consequences.

    • ‘target_type’: str or None, target type

      Warning

      This argument is automatically updated based on the number of classes in the training data. Do not change, unless you know what you are doing.

  • ‘training’:

    • ‘epochs’: int, number of epochs, default: 12

    • ‘batch_size’: int, batch size, default: 32

    • ‘learning_rate’: float, learning rate, default: 2e-5

    • ‘optimizer_name’: str, optimizer name, default: ‘Adam’

      Note

      Provide name of the optimizer you want to use. For a list of available optimizers, refer to https://keras.io/api/optimizers/

    • ‘add_optimizer_params’: dict, additional optimizer parameters, default: {}

      Note

      Add additional parameters to the optimizer other than learning rate. For a list of available parameters, refer to https://keras.io/api/optimizers/

      For example given the Adam optimizer, you may add: {‘beta_1’: 0.8, ‘beta_2’: 0.8, ‘epsilon’: 1e-05, ‘clipnorm’: 0.8} Or any parameter shown in the documentation: https://keras.io/api/optimizers/adam/

    • ‘class_weights’: bool, whether to use class weights, default: True

    • ‘metrics’: list, list of compatible evaluation metrics, default: [‘accuracy’]

      Note

      For a list of available metrics, refer to https://keras.io/api/metrics/

    • ‘augmentation’: str, data augmentation type, default: ‘basic’

      Note

      The available augmentation options are:

      augmentation_options = {
    'no_aug': ImageDataGenerator (
        preprocessing_function=preprocess_input
    ) ,
    'basic': ImageDataGenerator (
        preprocessing_function=preprocess_input ,
        shear_range=0.2 ,
        zoom_range=0.2 ,
        horizontal_flip=True
    ) ,
    'advanced': ImageDataGenerator (
        preprocessing_function=preprocess_input ,
        rotation_range=40 ,
        width_shift_range=0.2 ,
        height_shift_range=0.2 ,
        shear_range=0.2 ,
        zoom_range=0.2 ,
        horizontal_flip=True ,
        fill_mode='nearest'
    ) ,
    'advanced_with_blur': ImageDataGenerator (
        preprocessing_function=preprocess_input_with_blur ,
        rotation_range=40 ,
        width_shift_range=0.2 ,
        height_shift_range=0.2 ,
        shear_range=0.2 ,
        zoom_range=0.2 ,
        horizontal_flip=True ,
        fill_mode='nearest'
    ) ,
    'custom': ImageDataGenerator (
        preprocessing_function=custom_aug_with_preprocess_input
    )
}

      The library always retrieves the appropriate pre-processing function for the selected transfer learning architecture, along with the specified augmentation. This includes the ‘preprocess_input_with_blur’ option, which introduces varying levels of blur as an additional augmentation technique. The ‘custom’ augmentation option enables you to supply your own augmentation without fetching the corresponding pre-processing function for the transfer architecture.

    • ‘custom_augmentation’: callable or None, custom keras augmentation, default: None

      Note

      The user provided augmentation. More about augmentation:https://tinyurl.com/augTFKeras

      Warning

      This is only applicable when the ‘augmentation’ argument is set to ‘custom’.

    • ‘callback’: list or None, list of callbacks, default: None

      Note

      User provided callbacks and/or available callbacks from https://keras.io/api/callbacks/

    • ‘early_stop’: float or None, whether to use early stopping epochs set as

    a fraction of total epochs, default: False

    Note

    For example, if there are 100 epochs and early_stop is set to 0.1, early stopping will

    be triggered if the model does not improve for 10 consecutive epochs.

    • ‘warm_pretrain_dense’: bool, whether to warm pretrain dense layers, default: True

      Note

      Pre-train dense layers with a frozen transfer model, then unfreeze and train as specified

      (to mitigate destructive effects on unfrozen transfer architecture). It is recommended to use this approach only if there are blocks or layers specified unfrozen in the transfer architecture.

    • ‘warm_pretrain_epochs’: int, number of warm pretraining epochs, default: 5

  • ‘evaluation’:

    • ‘evaluate_mode’: bool, whether to use evaluation mode, default: False

      Note

      If True, training will not begin.

    • ‘auto_mode’: bool, whether to use automatic evaluation, default: True

      Note

      If True, final test on the best epoch will be performed automatically.

    • ‘preloaded_weights_path’: str or None, path to user preloaded weights file, default: None

      Note

      If provided, the model will be loaded with the provided weights.

  • ‘saving’:

    • ‘save_weights’: bool, whether to save model weights, default: True

    • ‘save_weights_folder’: str, path to save weights folder, default: ‘path_to_save_weights’

    • ‘save_best_weights’: str, which metric to use to save the best

    weights (if ‘all’ no metric is used), default: ‘val_loss’ - ‘save_weights_silent’: bool, whether to silently save weights, default: False

  • ‘misc’:

    • ‘show_summary’: bool, whether to display model summary, default: True

    • ‘plot_curves’: bool, whether to plot validation curves, default: True

    • ‘show_min_max_plot’: bool, whether to show min-max values within validation curves, default: True

    • ‘plot_conf’: bool, whether to plot confusion matrix, default: True

      Note

      The confusion matrix is normalized (rows), and automaticaly uses label names if available.

      The matrix also adjusts depending on the number of classes.

kwargs

Return the default settings dictionary for the experiment, including paths, model settings, training settings, evaluation settings, saving settings, and miscellaneous settings.

model_feature_extract(layer_index=-2, layer_name=None)

Perform feature extraction for train, validation, test, and external test generators using the specified layer.

Args:

layer_index (int, optional): Index of the desired layer for feature extraction. Defaults to -2. layer_name (str, optional): Name of the desired layer for feature extraction. Defaults to None.

Returns:

X_train (np.ndarray): Extracted features for the training set. y_train (np.ndarray): Labels for the training set. X_val (np.ndarray): Extracted features for the validation set. y_val (np.ndarray): Labels for the validation set. X_test (np.ndarray): Extracted features for the test set, or None if no test generator is provided. y_test (np.ndarray): Labels for the test set, or None if no test generator is provided. X_test_external (np.ndarray): Extracted features for the external test set, or None if no external test generator is provided. y_test_external (np.ndarray): Labels for the external test set, or None if no external test generator is provided.

model_predict(path_to_folder, batch_size=32, verbose=True, sort_by='variance')

Predict the classes of images in a folder using the trained model.

Args:

path_to_folder (str): Path to the directory containing images. batch_size (int, optional): Number of image samples per batch. Defaults to 32. verbose (bool, optional): Whether to print results during prediction. Defaults to True. sort_by (str, optional): Method to sort the predicted results. Defaults to ‘variance’.

Returns:

results (list): A list of dictionaries containing the prediction results.

run()

Run the main pipeline, including initialization, training or evaluating, and processing the test results.

Returns:

model (tensorflow.python.keras.engine.functional.Functional): The trained or evaluated Keras model. results (dict): A dictionary containing training results and configuration.

Module contents