Main Content

experiments.Monitor

Update results table and training plots for custom training experiments

Since R2021a

    Description

    When running a custom training experiment in Experiment Manager, use an experiments.Monitor object to track the progress of the training, update information fields in the results table, record values of the metrics used by the training, and produce training plots. For more information on custom training experiments, see Configure Custom Training Experiment.

    Creation

    When you run a custom training experiment, Experiment Manager creates an experiments.Monitor object for each trial of your experiment. Access the object as the second input argument of the training function.

    Properties

    expand all

    Metric column names, specified as a string, character vector, string array, or cell array of character vectors. Valid names begin with a letter, and can contain letters, digits, and underscores. These names appear as column headers in the experiment results table. Additionally, each metric appears in its own training subplot. To plot more than one metric in a single subplot, use the function groupSubPlot.

    Example: monitor.Metrics = ["TrainingLoss","ValidationLoss"];

    Data Types: char | string

    Information column names, specified as a string, character vector, string array, or cell array of character vectors. Valid names begin with a letter, and can contain letters, digits, and underscores. These names appear as column headers in the experiment results table. The values in the information columns do not appear in the training plot.

    Example: monitor.Info = ["GradientDecayFactor","SquaredGradientDecayFactor"];

    Data Types: char | string

    This property is read-only.

    Request to stop trial, specified as a numeric or logical 1 (true) or 0 (false). The value of this property changes to true when you click Stop in the Experiment Manager toolstrip or the results table.

    Data Types: logical

    Training progress percentage, specified as a numeric scalar or dlarray object between 0 and 100.

    Example: monitor.Progress = 17;

    Horizontal axis label in the training plot, specified as a string or character vector.

    Set this value before calling the function recordMetrics.

    Example: monitor.XLabel = "Iteration";

    Data Types: char | string

    Training status for a trial, specified as a string or character vector.

    Example: monitor.Status = "Loading Data";

    Data Types: char | string

    Since R2022b

    This property is read-only.

    Metric column values, specified as a structure. Use the Metrics property to specify the field names for the structure. Each field is a matrix that contains the custom training loop step values and metric values recorded by the recordMetrics function.

    Data Types: struct

    Since R2022b

    This property is read-only.

    Information column values, specified as a structure. Use the Info property to specify the field names for the structure. Each field is a column vector that contains the values updated by the updateInfo function.

    Data Types: struct

    Object Functions

    groupSubPlotGroup metrics in experiment training plot
    recordMetricsRecord metric values in experiment results table and training plot
    updateInfoUpdate information columns in experiment results table

    Examples

    collapse all

    Use an experiments.Monitor object to track the progress of the training, display information and metric values in the experiment results table, and produce training plots for custom training experiments.

    Before starting the training, specify the names of the information and metric columns of the Experiment Manager results table.

    monitor.Info = ["GradientDecayFactor","SquaredGradientDecayFactor"];
    monitor.Metrics = ["TrainingLoss","ValidationLoss"];

    Specify the horizontal axis label for the training plot. Group the training and validation loss in the same subplot.

    monitor.XLabel = "Iteration";
    groupSubPlot(monitor,"Loss",["TrainingLoss","ValidationLoss"]);

    Update the values of the gradient decay factor and the squared gradient decay factor for the trial in the results table.

    updateInfo(monitor, ...
        GradientDecayFactor=gradientDecayFactor, ...
        SquaredGradientDecayFactor=squaredGradientDecayFactor);

    After each iteration of the custom training loop, record the value of training and validation loss for the trial in the results table and the training plot.

    recordMetrics(monitor,iteration, ...
        TrainingLoss=trainingLoss, ...
        ValidationLoss=validationLoss);

    Update the training progress for the trial based on the fraction of iterations completed.

    monitor.Progress = 100 * (iteration/numIterations);

    Tips

    • Both information and metric columns display values in the results table for your experiment. Additionally, the training plot shows a record of the metric values. Use information columns for text and for numerical values that you want to display in the results table but not in the training plot.

    • An experiments.Monitor object has the same properties and object functions as a TrainingProgressMonitor object. Therefore, you can easily adapt your custom training loop plotting code for use in an Experiment Manager setup script. For more information, see Prepare Plotting Code for Custom Training Experiment.

    Version History

    Introduced in R2021a

    expand all