experimentTrial

R2026b

Outcome of experiment trial

Since R2026b

expand all in page

    Description

    An ExperimentTrial object contains detailed information about one trial in an experiment result. Each result contains one or more trials, where each trial represents one set of parameter values. Use an ExperimentTrial object to review the status, parameter values, metrics, outputs, and visualizations for a trial. For example:

    trial = experimentTrial("MyProject","Experiment1","Result1",1);
trial.Status
trial.Parameter.LearningRate
trial.Metric.TrainingLoss

    You can also access trials by indexing into the Trials property of an ExperimentResult object.

    Creation

    Syntax

    trial = experimentTrial(projectFolder,experimentName,resultName,trialNumber)

    Description

    trial = experimentTrial(projectFolder,experimentName,resultName,trialNumber) creates an ExperimentTrial object from the existing trial of an experiment run, either from the Experiment Manager app or from the runExperiment function.

    example

    Input Arguments

    expand all

    Path to the project PRJ file or project root folder, specified as a string scalar or character vector. You can specify an absolute or relative path. The project must contain one or more Experiment Manager experiments.

    Example: "C:\Projects\MyProject\MyProject.prj"

    Example: "C:\Projects\MyProject"

    Example: "MyProject"

    Name of the experiment that contains the trial, specified as a string scalar or character vector. To query the names of experiments in a project, use the experimentNames function.

    Example: "Experiment1"

    Name of the experiment result that contains the trial, specified as a string scalar or character vector. To query the names of results for an experiment, use the experimentResultNames function.

    Example: "Result1"

    Trial number, specified as a positive integer that does not exceed the number of trials in the result.

    Example: 5

    Properties

    expand all

    This property is read-only.

    Absolute path to the project root folder, represented as a string scalar.

    This property is read-only.

    Name of the experiment, represented as a string scalar.

    This property is read-only.

    Name of the experiment result, represented as a string scalar.

    This property is read-only.

    Trial number, represented as a positive integer.

    This property is read-only.

    Status of trial execution, represented as one of these enumeration values:

    • complete — Trial completed successfully.

    • canceled — Trial was canceled before completion. Canceling an experiment trial does not save the current trial result and immediately ends execution.

    • stopped — Trial was stopped before completion. Stopping an experiment trial saves the current trial result and ends experiment execution.

    • discarded — Trial was discarded.

    • error — An error occurred during the trial. Trial error information is stored in the Error property.

    This property is read-only.

    Trial error information, represented as an MException object. If the trial encountered an error, Error contains the error details. If the trial completed successfully, the Error property is empty.

    This property is read-only.

    Parameter values used for the trial, represented as a Parameter object whose properties correspond to the parameter names configured in the experiment. For example, to access the value of the LearningRate parameter in the trial, use val = trial.Parameter.LearningRate.

    This property is read-only.

    Additional trial information, represented as an Information object whose properties depend on the experiment type.

    Experiment TypeProperties of Information Object
    Built-in training

    • Epoch

    • Iteration

    • Solver

    • LearnRateSchedule

    • LearnRate

    • OutputNetwork

    • HardwareResource

    Custom trainingInformation fields that you set using the Info property of the experiments.Monitor (Deep Learning Toolbox) object
    General purposeNo information is recorded.

    This property is read-only.

    Metric values for the trial, represented as a Metric object whose properties correspond to the metric names.

    Experiment TypeProperties of Metric Object
    Built-in training

    • TrainingAccuracy

    • TrainingLoss

    • ValidationAccuracy

    • ValidationLoss

    Custom trainingMetric names that you define using the Metrics property of the experiments.Monitor (Deep Learning Toolbox) object
    General purposeNo metrics are recorded.

    This property is read-only.

    Trial output artifacts, represented as an Output object whose properties depend on the experiment type.

    Experiment TypeProperties of Output Object
    Built-in training

    • TrainedNetwork

    • TrainingInformation

    Custom trainingField names of the structure returned by the training function
    General purposeOutput variable names defined in the experiment function

    This property is read-only.

    Trial visualizations, represented as a Visualization object. The available visualizations depend on the experiment type.

    Experiment TypeVisualizations
    Built-in training

    • Training Plot

    • Confusion Matrix, Training Data

    • Confusion Matrix, Validation Data

    Custom trainingCustom figures created in the training function
    General purposeCustom figures created in the experiment function

    To see which visualizations are available, access the figure names, which are stored as a string array in the FigureNames property.

    vis = trial.Visualization;
names = vis.FigureNames

    To open the visualizations, use the openfig function.

    figs = openfig(vis,names)

    If the trial encountered an error, was canceled, or was discarded, the Visualization property is empty.

    Examples

    collapse all

    To examine the values of trial parameters, you can create an ExperimentTrial object from an existing experiment result and access its properties.

    Create an ExperimentTrial object for the third trial in an existing experiment result. The result can come from an experiment run in the Experiment Manager app or from a previous call to runExperiment.

    trial3 = experimentTrial("MyProject","Experiment1","Result1",3)
    trial3 = 

  ExperimentTrial with properties:

     ProjectFolder: "C:\Projects\MyProject"
    ExperimentName: "Experiment1"
        ResultName: "Result1"
            Number: 3
            Status: complete
             Error: [0×0 MException]
         Parameter: [1×1 matlab.experiment.trial.Parameter]
       Information: [0×0 matlab.experiment.trial.Information]
            Metric: [0×0 matlab.experiment.trial.Metric]
            Output: [1×1 matlab.experiment.trial.Output]
     Visualization: [0×0 matlab.experiment.trial.Visualization]

    View the parameter values used for this trial.

    p = trial3.Parameter
    p = 

  Parameter with properties:

    y: 5
    x: 1

    View the available figures for a trial and open them.

    Create an ExperimentTrial object, and view the names of the visualizations for that trial.

    trial1 = experimentTrial("MyProject","Experiment1","Result1",1);
vis = trial1.Visualization
names = vis.FigureNames
    names = 

  2×1 string array

    "Custom Figure 1"
    "Custom Figure 2"

    Open one of the figures using the openfig function with the Visualization object and the figure name.

    fig = openfig(vis,names(1));

    Open multiple figures at the same time by specifying a string array.

    figs = openfig(vis,names);

    Retrieve the trained network and training information from a built-in training experiment (Deep Learning Toolbox™).

    For built-in training experiments, the trained network and training information are stored in the Output property of the ExperimentTrial object. You can use the trained network for prediction or further training.

    trial1 = experimentTrial("MyProject","Experiment1","Result1",1);
net = trial1.Output.TrainedNetwork
    net = 

  dlnetwork with properties:

         Layers: [6×1 nnet.cnn.layer.Layer]
    Connections: [5×2 table]
     Learnables: [6×3 table]
          State: [2×3 table]
     InputNames: {'imageinput'}
    OutputNames: {'softmax'}
    Initialized: 1

    info = trial1.Output.TrainingInformation
    info = 

  TrainingInfo with properties:

           TrainingHistory: [40×4 table]
         ValidationHistory: [9×2 table]
    OutputNetworkIteration: 10
                StopReason: "Max epochs completed"

    Version History

    Introduced in R2026b

    See Also

    Functions

    Objects

    Apps

    Topics