train_dl_classifier_batchT_train_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch (Operator)

Name

train_dl_classifier_batchT_train_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch — Perform a training step of a deep-learning-based classifier on a batch of images.

Warning

train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch is obsolete and is only provided for reasons of backward compatibility. New applications should use the common CNN-based operator train_dl_model_batchtrain_dl_model_batchTrainDlModelBatchTrainDlModelBatchTrainDlModelBatchtrain_dl_model_batch.

Signature

train_dl_classifier_batch(BatchImages : : DLClassifierHandle, BatchLabels : DLClassifierTrainResultHandle)

Herror T_train_dl_classifier_batch(const Hobject BatchImages, const Htuple DLClassifierHandle, const Htuple BatchLabels, Htuple* DLClassifierTrainResultHandle)

void TrainDlClassifierBatch(const HObject& BatchImages, const HTuple& DLClassifierHandle, const HTuple& BatchLabels, HTuple* DLClassifierTrainResultHandle)

void HDlClassifierTrainResult::HDlClassifierTrainResult(const HImage& BatchImages, const HDlClassifier& DLClassifierHandle, const HTuple& BatchLabels)

void HDlClassifierTrainResult::TrainDlClassifierBatch(const HImage& BatchImages, const HDlClassifier& DLClassifierHandle, const HTuple& BatchLabels)

static void HOperatorSet.TrainDlClassifierBatch(HObject batchImages, HTuple DLClassifierHandle, HTuple batchLabels, out HTuple DLClassifierTrainResultHandle)

public HDlClassifierTrainResult(HImage batchImages, HDlClassifier DLClassifierHandle, HTuple batchLabels)

void HDlClassifierTrainResult.TrainDlClassifierBatch(HImage batchImages, HDlClassifier DLClassifierHandle, HTuple batchLabels)

def train_dl_classifier_batch(batch_images: HObject, dlclassifier_handle: HHandle, batch_labels: Sequence[Union[str, int]]) -> HHandle

Description

train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch performs a training step of the deep-learning-based classifier contained in DLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandledlclassifier_handle. The classifier handle DLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandledlclassifier_handle has to be read previously using read_dl_classifierread_dl_classifierReadDlClassifierReadDlClassifierReadDlClassifierread_dl_classifier. In order to apply training steps, classes have to be specified using set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParamset_dl_classifier_param. Other hyperparameters such as the learning rate and the momentum are also important for a successful training. They are set using set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParamset_dl_classifier_param.

The training step is done on basis of a single batch of images from the training dataset, thus the images BatchImagesBatchImagesBatchImagesBatchImagesbatchImagesbatch_images with labels BatchLabelsBatchLabelsBatchLabelsBatchLabelsbatchLabelsbatch_labels. The number of images within the batch needs to be a multiple of the 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" where the parameter 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" is limited by the amount of available GPU memory. In order to process more images in one training step, the classifier parameter 'batch_size_multiplier'"batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier" can be set to a value greater than 1. The number of images being passed to the training operator needs to be equal to 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" times 'batch_size_multiplier'"batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier". Note that a training step calculated for a batch and a 'batch_size_multiplier'"batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier" greater 1 is an approximation of a training step calculated for the same batch but with a 'batch_size_multiplier'"batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier" equal to 1 and an accordingly greater 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size". As an example, the loss calculated with a 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" of 4 and a 'batch_size_multiplier'"batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier" of 2 is usually not equal to the loss calculated with a 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" of 8 and a 'batch_size_multiplier'"batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier" of 1, although the same number of images is used for training in both cases. However, the approximation generally delivers comparably good results, so it can be utilized if you wish to train with a larger number of images than your GPU allows. In some rare cases the approximation with a 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" of 1 and an accordingly large 'batch_size_multiplier'"batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier""batch_size_multiplier" does not show the expected performance which for example can happen when the pretrained network 'pretrained_dl_classifier_resnet50.hdl'"pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl" is used. Setting the 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" to a value greater than 1 can help to solve this issue.

Note that the images in BatchImagesBatchImagesBatchImagesBatchImagesbatchImagesbatch_images must fulfill certain conditions regarding, for example, the image size and gray value range, depending on the chosen network. Please have a look at read_dl_classifierread_dl_classifierReadDlClassifierReadDlClassifierReadDlClassifierread_dl_classifier and set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParamset_dl_classifier_param for more information. The labels in BatchLabelsBatchLabelsBatchLabelsBatchLabelsbatchLabelsbatch_labels can be handed over as an array of strings, or as an array of indices corresponding to the position of the label within the array of classes (counting from 0) set before via 'classes'"classes""classes""classes""classes""classes" with set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParamset_dl_classifier_param. Information about the results of the training step as the value of the loss are stored in DLClassifierTrainResultHandleDLClassifierTrainResultHandleDLClassifierTrainResultHandleDLClassifierTrainResultHandleDLClassifierTrainResultHandledlclassifier_train_result_handle and can be accessed using get_dl_classifier_train_resultget_dl_classifier_train_resultGetDlClassifierTrainResultGetDlClassifierTrainResultGetDlClassifierTrainResultget_dl_classifier_train_result.

Note that an epoch generally consists of a large number of batches and that a successful training involves many epochs. Therefore train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch has to be applied several times with different batches. For a more detailed explanation, we refer to Legacy / DL Classification.

During training, a nonlinear optimization algorithm minimizes the value of the loss function. The later one is determined based on the prediction of the neural network on the current batch of images. The algorithm used for optimization is stochastic gradient descent (SGD). It updates the layers' weights of the previous iteration to the new values at iteration as follows:

Here, is the learning rate, for the momentum, and for the classification result of the deep learning-based classifier which depends on the network weights and the input batch . The variable is used to involve the influence of the momentum . The loss function used here is the Multinomial Logistic Loss in combination with a quadratic regularization term ,

Here, is a one-hot encoded target vector that encodes the label of the -th image of the batch containing -many images, and shall be understood to be a vector such that is applied on each component of . The regularization term is a weighted -norm involving all weights except for biases. Its influence can be controlled through . In the above formula, denotes the hyperparameter 'weight_prior'"weight_prior""weight_prior""weight_prior""weight_prior""weight_prior" that can be set with set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParamset_dl_classifier_param. In order to gain more insight, you can retrieve the current value of the total loss function as well as individual contributions using get_dl_classifier_train_resultget_dl_classifier_train_resultGetDlClassifierTrainResultGetDlClassifierTrainResultGetDlClassifierTrainResultget_dl_classifier_train_result.

For an explanation of the concept of deep-learning-based classification see the introduction of chapter Deep Learning / Classification. The workflow involving this legacy operator is described in the chapter Legacy / DL Classification.

Attention

The operator train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch internally calls functions that might not be deterministic. Therefore, results from multiple calls of train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch can slightly differ, although the same input values have been used.

To run this operator, cuDNN and cuBLAS are required. For further details, please refer to the “Installation Guide”, paragraph “Requirements for Deep Learning and Deep-Learning-Based Methods”.

Execution Information

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters

BatchImagesBatchImagesBatchImagesBatchImagesbatchImagesbatch_images (input_object)  (multichannel-)image(-array) objectHImageHObjectHImageHobject (real)

Images comprising the batch.

DLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandledlclassifier_handle (input_control)  dl_classifier HDlClassifier, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the deep-learning-based classifier.

BatchLabelsBatchLabelsBatchLabelsBatchLabelsbatchLabelsbatch_labels (input_control)  string-array HTupleSequence[Union[str, int]]HTupleHtuple (string / integer) (string / int / long) (HString / Hlong) (char* / Hlong)

Corresponding labels for each of the images.

Default value: []

List of values: []

DLClassifierTrainResultHandleDLClassifierTrainResultHandleDLClassifierTrainResultHandleDLClassifierTrainResultHandleDLClassifierTrainResultHandledlclassifier_train_result_handle (output_control)  dl_classifier_train_result HDlClassifierTrainResult, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the training results from the deep-learning-based classifier.

Result

If the parameters are valid, the operator train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch returns the value TRUE. If necessary, an exception is raised.

Possible Predecessors

read_dl_classifierread_dl_classifierReadDlClassifierReadDlClassifierReadDlClassifierread_dl_classifier, set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParamset_dl_classifier_param, get_dl_classifier_paramget_dl_classifier_paramGetDlClassifierParamGetDlClassifierParamGetDlClassifierParamget_dl_classifier_param

Possible Successors

get_dl_classifier_train_resultget_dl_classifier_train_resultGetDlClassifierTrainResultGetDlClassifierTrainResultGetDlClassifierTrainResultget_dl_classifier_train_result, apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierApplyDlClassifierapply_dl_classifier, clear_dl_classifier_train_resultclear_dl_classifier_train_resultClearDlClassifierTrainResultClearDlClassifierTrainResultClearDlClassifierTrainResultclear_dl_classifier_train_result, clear_dl_classifierclear_dl_classifierClearDlClassifierClearDlClassifierClearDlClassifierclear_dl_classifier

Alternatives

train_dl_model_batchtrain_dl_model_batchTrainDlModelBatchTrainDlModelBatchTrainDlModelBatchtrain_dl_model_batch, train_class_mlptrain_class_mlpTrainClassMlpTrainClassMlpTrainClassMlptrain_class_mlp, train_class_svmtrain_class_svmTrainClassSvmTrainClassSvmTrainClassSvmtrain_class_svm

See also

apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierApplyDlClassifierapply_dl_classifier

Module

Deep Learning Training