getMetrics

R2026b

Access metric results

Syntax

results = getMetrics(metricEngine,metricIDs)

results = getMetrics(metricEngine,metricIDs,Name=Value)

Description

results = getMetrics(metricEngine,metricIDs) returns metric results for the specified metric.Engine object for the metrics that you specify in metricIDs. To collect metric results for the metric.Engine, use the execute function. Then, access the results by using getMetrics.

There is also a function getMetrics (Fixed-Point Designer) in the Fixed-Point Designer™ documentation.

results = getMetrics(metricEngine,metricIDs,Name=Value) specifies options using one or more name-value arguments in addition to the input arguments in previous syntaxes. For example, you can specify the ScopeId to get metric results for a specific unit or component in your project.

Examples

Collect Metrics for Testing Artifacts in a Project

Collect metric results on the requirements-based testing artifacts in a project.

Open a project that contains models and testing artifacts. For this example, in the MATLAB^® Command Window, enter:

openExample("slcheck/ExploreTestingMetricDataInModelTestingDashboardExample");
openProject("cc_CruiseControl");

Create a metric.Engine object. You can use the metric.Engine object to collect metric results for the current project.

metricEngine = metric.Engine();

Collect results for model testing metrics by executing the metric engine. The execute function returns the collected results.

results = execute(metricEngine,"modeltesting.TestAnalysis[]")

results =

  1x44 Result array with properties:

    UserData
    Value
    MetricID
    Artifacts
    ScopeId
    ScopeAlias
    ThresholdOutcomes
    Diagnostics

Use getMetrics to access a subset of the collected results. For example, get only the results for the ratio of requirements per test.

reqsPerTest = getMetrics(metricEngine,"modeltesting.TestAnalysis[slcomp.RequirementsPerTestRatio]")

reqsPerTest =

  1x4 Result array with properties:

    UserData
    Value
    MetricID
    Artifacts
    ScopeId
    ScopeAlias
    ThresholdOutcomes
    Diagnostics

Access the metric results data by using the properties of the metric.Result objects in the array. For this metric, the Value property is a structure containing the total, linked, and unlinked requirement counts.

reqsPerTest(1).Value

ans =

  struct with fields:

       Total: 37
      Linked: 37
    Unlinked: 0

reqsPerTest(1).ScopeAlias

ans =

    "cc_ControlMode"

Display the ratio of requirements per test for each unit model in the project.

models = [reqsPerTest.ScopeAlias].';
values = [reqsPerTest.Value].';
total = [values.Total].';
linked = [values.Linked].';
unlinked = [values.Unlinked].';
T = table(models,total,linked,unlinked,VariableNames=["Model","Total","Linked","Unlinked"])

T =

  4x4 table

           Model              Total    Linked    Unlinked
    ____________________      _____    ______    ________

    "cc_ControlMode"           37        37         0
    "cc_LightControl"           5         5         0
    "cc_DriverSwRequest"       10        10         0
    "cc_ThrottleController"     0         0         0

For more information on how to collect metrics for testing artifacts, see Collect Metrics on Model Testing Artifacts Programmatically.

Collect Metrics for a Unit

Collect metrics for one unit in the project. Specify the unit and collect metrics for only the artifacts that trace to the model.

Open the project that contains the model. For this example, in the MATLAB Command Window, enter:

openExample("slcheck/ExploreTestingMetricDataInModelTestingDashboardExample");
openProject("cc_CruiseControl");

Create a metric.Engine object for the project.

metric_engine = metric.Engine();

Update the trace information for metric_engine to ensure that the artifact information is up to date.

updateArtifacts(metric_engine)

Create a variable that represents the path to the unit model cc_DriverSwRequest.

modelPath = fullfile(pwd,'models','cc_DriverSwRequest.slx');

Open the model cc_DriverSwRequest and find the digital thread URI for that model.

open_system("cc_DriverSwRequest");
storageMap = digitalthread.StorageMap.forProject();
modelURI = digitalthread.uri.simulink.fromObject(storageMap,get_param(gcs,"Handle"))

Collect results for a model testing metric by using the execute function on the engine object and limiting the scope to the cc_DriverSwRequest model.

execute(metric_engine,"modeltesting.TestAnalysis[slcomp.RequirementsPerTestRatio]",ScopeId=modelURI);

Access the collected metric results by using the getMetrics function.

results = getMetrics(metric_engine,"modeltesting.TestAnalysis[slcomp.RequirementsPerTestRatio]");
results.Value

ans =

  struct with fields:

       Total: 10
      Linked: 10
    Unlinked: 0

Get Metrics for Specific Artifact

You can scope metric results to a specific artifact by using a digital thread URI. A digital thread URI uniquely identifies an artifact, such as a model, subsystem, or block, so that the metric engine returns results only for that artifact.

Get the digital thread URI for the artifact that you want to collect metrics for. You can find digital thread URIs by using the functions in the digitalthread.uri namespace. For example, to find the digital thread URI for a subsystem that you select in a Simulink^® model:

storageMap = digitalthread.StorageMap.forProject();
subsystemURI = digitalthread.uri.simulink.fromObject(storageMap,get_param(gcb,"Handle"))

subsystemURI = 

    "mwdigitalthread://myProject/myModel.slx#addr=myModel/123"

Get the metrics for that specific subsystem by passing the artifact URI to the ScopeId argument.

metricID = "sldesignlayer.SimulinkDesignInfo";
results = getMetrics(metric_engine,metricID,ScopeId=subsystemURI)

results = 

  Result with properties:

             UserData: ''
                Value: [1×1 struct]
             MetricID: 'sldesignlayer.SimulinkDesignInfo'
            Artifacts: [1×1 struct]
              ScopeId: "mwdigitalthread://myProject/myModel.slx#addr=myModel/308"
           ScopeAlias: "mySubsystem"
    ThresholdOutcomes: [1×0 metric.threshold.ThresholdOutcome]
          Diagnostics: []

The metric engine only gets the metric results for the specified artifact.

Input Arguments

metricEngine — Metric engine object

metric.Engine object

Metric engine object for which you want to access metric results, specified as a metric.Engine object.

metricIDs — Metric identifiers

character vector | cell array of character vectors | string | string array

Metric identifiers for metrics that you want to collect, specified as a character vector, cell array of character vectors, string, or string array.

You can use the function getAvailableMetricIds to return a list of available metric identifiers.

For information on the metrics and their identifiers, see:

• Model Design Metrics

• Model Maintainability Metrics

• Model Testing Metrics

• Code Testing Metrics

• Project Model Testing Metrics

Example: 'slcomp.OverallCyclomaticComplexity'

Example: {'slcomp.OverallMATLABeLOC', 'slcomp.OverallSignalLines'}

Example: 'TestCasesPerRequirementDistribution'

Example: {'slcomp.mt.TestStatus', 'slcomp.mt.CoverageBreakdown'}

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: results = getMetrics(metric_engine,metricID,ScopeId=subsystemURI)

ScopeId — Digital thread URI for artifact

string scalar

Digital thread URI for the artifact that you want to get metric results for, specified as a string scalar.

A digital thread URI is a stable identifier for an artifact, such as a model file, or a sub-file artifact, such as a block. The digital thread uses these URIs as a consistent way to refer to artifacts across tools and inside metric results. Use digitalthread.uri.simulink.fromObject to get the URI for a model or element within a model. File-level URIs from digitalthread.uri.fromFilePath are not supported as ScopeId values.

Note

If you specify both ScopeId and ArtifactScope, ScopeId takes precedence.

Note

For table metrics (metrics that use the bracket notation, such as "modeldesign.SimulinkMaintainability[slcomp.BlockDistribution]"), specifying ScopeId does not limit the scope of the table metric itself. The table metric still collects results across all scopes. The ScopeId argument only limits the collection of dependent metrics that the table metric imports. For non-table metrics, ScopeId limits the collection to the specified artifact.

Example: "mwdigitalthread://myProject/myModel.slx#addr=myModel/###"

Data Types: string

ThresholdSetId — Threshold set identifier

string scalar

Since R2026b

Threshold set identifier, specified as a string scalar. Use this argument to classify metric results according to a specific threshold set. The threshold set determines how metric values are classified into compliance categories.

The shipping threshold sets are "Testing" and "ReqBasedTesting". You can also specify custom threshold sets that you create by using metric.config.Configuration.copyThresholdSet on a metric.config.Configuration object.

Example: "Testing"

Example: "MyTestingThresholds"

Data Types: string

Output Arguments

results — Metric results

array of metric.Result objects

Metric results, returned as an array of metric.Result objects.

Alternative Functionality

App

You can also view metric results by using the dashboard user interface.

• For the model design metrics, use the Model Design Dashboard. For more information, see Model Design Metrics.

• For the model maintainability metrics, use the Model Maintainability dashboard. For more information, see Monitor Design Complexity Using Model Maintainability Dashboard.

• For the model testing metrics, use the Model Testing Dashboard. For more information, see Explore Status and Quality of Testing Activities Using Model Testing Dashboard.

• For the code testing metrics, use the SIL Code Testing or PIL Code Testing dashboard. For more information see, View Status of Code Testing Activities for Software Units in Project.

Version History

Introduced in R2020b

R2026b: Classify metric results by threshold set using the ThresholdSetId argument

In R2026b, you can specify the ThresholdSetId name-value argument to classify metric results according to a specific threshold set. You can use shipping threshold sets or custom threshold sets that you create by using metric.config.Configuration.copyThresholdSet.

R2026b: Scope metric results to a specific artifact by using the ScopeId argument

In R2026b, you can scope metric results to a single artifact by using the new ScopeId argument. Use ScopeId to replace ArtifactScope.

In releases prior to R2026b, you use the ArtifactScope argument by specifying:

• The full path to a project file, such as a model file.

• The identifier of the object inside the project file, such as a block diagram name.

For example:

Prior to R2026a	R2026 and later
modelPath = fullfile(pwd,'myModel.slx'); results = getMetrics(metricEngine,metricID,ArtifactScope={modelPath,'myModel'});	open_system("myModel"); storageMap = digitalthread.StorageMap.forProject(); modelURI = digitalthread.uri.simulink.fromObject(storageMap,get_param(gcs,"Handle")); results = getMetrics(metricEngine,metricID,ScopeId=modelURI)

R2026b: Scope metric results to a specific artifact by using the ScopeId argument

In R2026b, you can scope metric execution and results to a single artifact by using the new ScopeId argument.