ocrTrainingOptions

Options for training OCR model

Since R2023a

Description

The ocrTrainingOptions object specifies training options for an optical character recognition (OCR) model.

Creation

Syntax

ocrOptions = ocrTrainingOptions(Name=Value)

Description

ocrOptions = ocrTrainingOptions(Name=Value) creates an ocrTrainingOptions object. Specify one or more properties using name-value arguments to configure a set of training options, and then use them with the trainOCR function to train an OCR model. For example, CharacterSetSource="base-model" sets the source of the character set to use during OCR training to the base model.

Properties

OutputLocation — Folder in which to store the output model file

pwd (default) | string scalar | character vector

Folder in which to store the output model file, specified as a string scalar or character vector. If the folder already contains a file with the name specified by the modelName argument of the trainOCR function, then the trainOCR function overwrites it during training.

CharacterSetSource — Source of character set for text recognition training

"auto" (default) | "base-model" | "ground-truth-data"

Source of the character set for text recognition training, specified as "auto", "base-model", or "ground-truth-data".

• "auto" — Training uses the character set of the base model when resuming from a checkpoint. Otherwise, training selects a character set as defined by the ground truth data.

• "base-model" — Training uses the character set of the base model specified in the trainOCR function. Use this option to fine-tune the base model used on the ground truth data.

• "ground-truth-data" — To use the character set defined by the ground truth data specified in the trainOCR function.

MaxEpochs — Maximum number of epochs used for training

5 (default) | positive integer

Maximum number of epochs used for training, specified as a positive integer.

InitialLearnRate — Initial learning rate used for training

1.0000e-03 (default) | numeric scalar

Initial learning rate used for training, specified as a numeric scalar. Decreasing the initial learning rate can increase training time. However, increasing the rate too much can result in the training being unable to converge.

Verbose — Progress information display

true or 1 (default) | false or 0

Progress information display, specified as a numeric or logical 1 (true) or 0 (false).

VerboseFrequency — Number of iterations between progress displays

50 (default) | positive integer

Number of iterations between progress displays, specified as a positive integer. This argument only applies when you set Verbose to true.

CheckpointPath — Path to save check point models

"" (default) | character vector | string

Path to save check point models, specified as a character vector or a string. When you set CheckpointPath to "", the trainOCR function does not save checkpoints.

CheckpointFrequency — Frequency for saving check point models

1 (default) | positive integer

Frequency for saving check point models, specified as a positive integer. This argument only applies when you specify a path by using CheckpointPath.

CheckpointFrequencyUnit — Unit of check point frequency

"epoch" (default)

Unit of check point frequency, specified as "epoch" or "iteration". When you set this value to "epoch", the trainOCR function saves a checkpoint every CheckpointFrequecy epochs. When you set this value to "iteration", the trainOCR function saves a checkpoint every CheckpointFrequecy iterations.

ValidationData — Data to use for validation during training

[] (default) | datastore object

Data to use for validation during training, specified as a datastore object with the same format as the trainingData input argument of the trainOCR function.

ValidationFrequency — Number of iterations between evaluations of validation metrics

50 (default) | positive integer

Number of iterations between evaluations of validation metrics, specified as a positive integer.

ValidationPatience — Validation loss tolerance

Inf (default) | positive integer

Validation loss tolerance, specified as Inf or a positive integer. This value specifies the consecutive number of iterations for which the validation loss can be greater than or equal to the previous smallest loss before the network stops training.

OutputNetwork — Network returned when training ends

"auto" (default) | "best-training-loss" | "best-validation-loss" | "last-iteration"

Network returned when training ends, specified as "auto", "best-training-loss", "best-validation-loss", or "last-iteration".

• "auto" — Returns "best-validation-loss" when you specify the ValidationData property. Otherwise, returns "best-training-loss".

• "best-training-loss" — Returns the network at the iteration corresponding to the best training loss.

• "best-validation-loss" — Returns the network at the iteration corresponding to the best validation loss. To use this option, you must specify the ValidationData property.

• "last-iteration" — Returns the network corresponding to the last training iteration.

SolverName — Name of solver to use for training

"adam" (default) | "sgdm"

Name of the solver to use for training, specified as "adam" or "sgdm".

GradientDecayFactor — Exponential decay rate for gradient moving average in the adam solver

0.5 (default) | scalar in range [0, 1)

Exponential decay rate for the gradient moving average in the adam solver, specified as a scalar in the range [0, 1).

The GradientDecayFactor corresponds to β₁, as defined by Kingma and Bar [1].

SquareGradientDecayFactor — Exponential decay rate for squared gradient moving average in adam solver

0.999 (default) | scalar in the range [0, 1)

Exponential decay rate for the squared gradient moving average in the adam solver, specified by a scalar in the range [0, 1).

The GradientDecayFactor corresponds to β₁, as defined by Kingma and Bar [1].

Momentum — Contribution of gradient step from previous iteration to current iteration of training

0.5 (default) | scalar in range [0, 1]

Contribution of the gradient step from the previous iteration to the current iteration of training, specified as a scalar in the range [0, 1]. This argument applies only when using the sgdm solver.

Shuffle — Control shuffling of training data

"once" (default) | "never"

Control shuffling of training data, specified as "once" or "never".

Examples

Specify Options For OCR Training

Create a directory to save the trained OCR model.

outputDir = "OCRModel";
if ~exist(outputDir, "dir")
    mkdir(outputDir);
end

Create a directory to save checkpoints.

checkpointsDir = "Checkpoints";
if ~exist(checkpointsDir, "dir")
    mkdir(checkpointsDir);
end

Create a set of options for training an OCR model.

• Set the gradient decay factor for ADAM optimization to 0.9.

• Use an initial learning rate of 20e-4.

• Set the maximum number of epochs for training to 15.

• Set the verbose frequency to 100 iterations.

• Specify the output directory.

• Specify the checkpoint path to enable saving checkpoints.

ocrOptions = ocrTrainingOptions(GradientDecayFactor=0.9,...
    InitialLearnRate=20e-4,...
    MaxEpochs=15,...
    VerboseFrequency=100,...
    OutputLocation=outputDir,...
    CheckpointPath=checkpointsDir)

ocrOptions = 
  ocrTrainingOptions with properties:

               OutputLocation: "OCRModel"
                    MaxEpochs: 15
             InitialLearnRate: 0.0020
                      Verbose: 1
             VerboseFrequency: 100
               CheckpointPath: "Checkpoints"
          CheckpointFrequency: 1
      CheckpointFrequencyUnit: "epoch"
               ValidationData: []
          ValidationFrequency: 50
           ValidationPatience: Inf
                OutputNetwork: "auto"
                   SolverName: "adam"
          GradientDecayFactor: 0.9000
    SquareGradientDecayFactor: 0.9990
                     Momentum: 0.5000
                      Shuffle: "once"
           CharacterSetSource: "auto"

References

[1] Kingma, Diederik P., and Jimmy Ba. "Adam: A Method for Stochastic Optimization". arXiv, January 29, 2017. https://doi.org/10.48550/arXiv.1412.6980.

Version History

Introduced in R2023a