experimentResult

R2026b

Result of executed experiment

Since R2026b

expand all in page

    Description

    An ExperimentResult object contains the configuration details and outcomes of a single execution of an experiment. Each experiment can have multiple results, and each result contains one or more ExperimentTrial objects. Use an ExperimentResult object to review the strategy, execution status, result summary table, and outcome of individual trials.

    result = experimentResult("MyProject","Experiment1","Result1");
result.Status
result.ResultSummary
result.Trials(1)

    Creation

    There are two ways to create an ExperimentResult object:

    • Run an experiment and return the corresponding result object by using the runExperiment function.

    • Create a result object from an existing result of an experiment run by using the experimentResult function (described here).

    Syntax

    result = experimentResult(projectFolder,experimentName,resultName)

    Description

    result = experimentResult(projectFolder,experimentName,resultName) creates an ExperimentResult object from an existing result 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 result, 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 to retrieve, specified as a string scalar or character vector. To query the names of results for an experiment, use the experimentResultNames function.

    Example: "Result1"

    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.

    Strategy for exploring experiment parameters, represented as one of these values:

    • "exhaustive-sweep" — Runs all combinations of parameter values

    • "bayesian-optimization" — Uses Bayesian optimization to choose parameter values that optimize a metric that you specify

    • "random-sampling" — Randomly samples parameter combinations from the ranges that you specify

    Select the strategy in the Experiment Manager app as part of the experiment configuration.

    This property is read-only.

    Status of experiment execution, represented as one of these enumerations:

    • complete — All trials completed successfully.

    • error — An experiment-level error occurred before trials could run. Experiment error information is stored in the Error property.

    • trialerror — The experiment ran, but one or more trials encountered errors.

    This property is read-only.

    Experiment error information, represented as an MException object. If an experiment-level error occurred, Error contains the error details. If the experiment ran successfully (even if individual trials had errors), the Error property is empty.

    This property is read-only.

    Summary of experiment results, represented as a table. The columns of the table depend on the experiment configuration and can include:

    • Trial status and details

    • Parameter values for each trial

    • Metric values computed for each trial

    • Trial information (for built-in and custom training experiments)

    This table has the same structure as the results table displayed in the Experiment Manager app. Use the summary table to compare trials at a glance before accessing individual trials using the Trials property.

    This property is read-only.

    Trial results, represented as an array that contains one ExperimentTrial object for each experiment trial. The number of trials depends on the experiment strategy and parameter configuration. For an exhaustive sweep, the number of trials equals the total number of parameter combinations.

    Examples

    collapse all

    List available results for an experiment, and then retrieve and examine one result.

    List the available results for an experiment.

    resultNames = experimentResultNames("MyProject","Experiment1")
    resultNames =

  2x1 string array

    "Result1"
    "Result2"

    Retrieve the first result. A result is created each time you run an experiment using the Experiment Manager app or the runExperiment function.

    result = experimentResult("MyProject","Experiment1",resultNames(1))
    result = 

  ExperimentResult with properties:

     ProjectFolder: "C:\Projects\MyProject"
    ExperimentName: "Experiment1"
        ResultName: "Result1"
          Strategy: "exhaustive-sweep"
            Status: complete
             Error: [0x0 MException]
     ResultSummary: [4x3 table]
            Trials: [4x1 matlab.experiment.trial.ExperimentTrial]

    View the result summary table. Each row corresponds to one trial. Alternatively, you can view the result summary table in the Experiment Manager app.

    T = result.ResultSummary
    T =

  4×3 table

            Experiment Details             Parameters    Outputs
    ___________________________________    __________    _______

    Trial      Status      Elapsed Time      x    y         z   
    _____    __________    ____________      _    _         _   
                                                                
      1      "Complete"      00:00:04        1    4         5   
      2      "Complete"      00:00:05        2    4         6   
      3      "Complete"      00:00:05        1    5         6   
      4      "Complete"      00:00:04        2    5         7

    Access a trial from a result using indexing. Alternatively, you can access a trial by specifying the trial number with the experimentTrial function.

    result = experimentResult("MyProject","Experiment1","Result1");
trial3 = result.Trials(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: [1×1 matlab.experiment.trial.Visualization]

    Version History

    Introduced in R2026b

    See Also

    Functions

    Objects

    Apps

    Topics