Collect Model Maintainability Metrics Programmatically

R2026b
Open Live Script

This example shows how to collect the metric data used in the Model Maintainability Dashboard, generate a report, and use the report to assess the model design artifacts.

If a model in your project is large, complex, or difficult to read, the design can be difficult to test and maintain. To determine whether you want to refactor your design, use the metric results. Refactoring helps you identify smaller testable units or restructure a model to improve readability.

Open Project

Open a project containing models that you want to analyze. For this example, open the project cc_CruiseControl.

openProject("cc_CruiseControl");

For information on how to create a project for your artifacts, see Create Project to Use Model Design and Model Testing Dashboards.

Collect Metric Results

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

metricEngine = metric.Engine;

Create an array of the metric identifiers for model maintainability. For more information on the model maintainability metrics, see Model Maintainability Metrics.

maintainabilityMetrics = getAvailableMetricIds(metricEngine, ...
    App="DashboardApp", ...
    Dashboard="ModelMaintainability");

The Model Maintainability Dashboard can collect metric results for Units and Components in your project. To control what the dashboard classifies as a unit or component, see Categorize Models in Hierarchy as Components or Units. You can collect results for each unit and component in the project or for one unit or component at a time.

For this example, suppose you want to collect results for the unit cc_ControlMode. To scope metric execution to a specific unit, you need a URI for the unit. Create a storage map for the project and use it to get the URI for cc_ControlMode.

storageMap = digitalthread.StorageMap.forProject();
load_system("cc_ControlMode");
unitURI = digitalthread.uri.simulink.fromObject(storageMap,get_param("cc_ControlMode","Handle"));

Collect metric results for all units in the project by using the execute function without the additional arguments.

results = execute(metricEngine,maintainabilityMetrics);

Collect the maintainability metric results for the unit cc_ControlMode by using the execute function with the ScopeId argument.

results = execute(metricEngine,maintainabilityMetrics,ScopeId=unitURI);

Access and View Metric Results

To access the metric results, use the getMetrics function. For this example, store the results for the metric sldesignlayer.SimulinkDesignInfo. The model maintainability metric sldesignlayer.SimulinkDesignInfo returns design information for each layer of a model, including the number of Simulink® signal lines. For more information on the model maintainability metrics, see Model Maintainability Metrics.

results_SignalLines = getMetrics(metricEngine,"sldesignlayer.SimulinkDesignInfo");

The getMetrics function returns a metric.Result object containing the metric results for the specified metric. The Value property of this object is a structure with fields such as SignalLines, Blocks, and Decisions.

Display the model layer and number of signal lines. These values are in the ScopeAlias and Value.SignalLines properties of the metric.Result object. The results might appear in a different order on your machine.

modelLayers = [results_SignalLines.ScopeAlias].';
values = [results_SignalLines.Value].';
signalLines = [values.SignalLines].';

T = table(modelLayers,signalLines,VariableNames=["Model Layer","Signal Lines"])

The code output shows that the model layer Control_Mode_StateMachine contains 60 Simulink signal lines. Based on these results, consider restructuring that model layer to improve readability.

Filter Metric Results for Specific Model Layer

To investigate the Control_Mode_StateMachine layer further, filter the metric results for that specific subsystem. Get the handle of the subsystem and convert it to a URI.

subsystemHandle = get_param("cc_ControlMode/Control_Mode_StateMachine","Handle");
subsystemURI = digitalthread.uri.simulink.fromObject(storageMap,subsystemHandle);

Retrieve the design information for this subsystem layer by using the ScopeId argument with getMetrics. The result includes the full set of design metrics, including blocks, decisions, and signal lines.

layerInfo = getMetrics(metricEngine,"sldesignlayer.SimulinkDesignInfo",ScopeId=subsystemURI);
v = layerInfo.Value

For example, you can view the Halstead complexity metrics for this subsystem, which measure the computational complexity based on operators and operands.

v.Halstead

Digital thread URIs are stable, portable identifiers for artifacts. You can convert between URIs and Simulink objects by using the conversion functions in the digitalthread.uri namespace. For example, convert the subsystem URI back to a Simulink object:

objBack = digitalthread.uri.simulink.toObject(storageMap,subsystemURI)

Do not parse digital thread URIs manually. The internal structure of URIs is subject to change in future releases. Use the conversion functions in the digitalthread.uri namespace to work with URIs.

For more information, see digitalthread.StorageMap.forProject, digitalthread.uri.fromFilePath, and digitalthread.uri.simulink.fromObject.

Generate Report

Generate a report file containing the model maintainability results collected in metricEngine. By default, the report file type is a PDF. For this example, specify the report file type as HTML.

generateReport(metricEngine,Dashboard="ModelMaintainability",Type="html-file");

To access the metric results without opening the project or dashboard, save them in a report file.

Alternatively, you can open the Model Maintainability Dashboard to see the results and explore the artifacts. To programmatically access the Model Maintainability Dashboard, enter modelDesignDashboard. Then, in the dashboard toolstrip, select Model Maintainability in the dashboard gallery.

See Also

| | | | |

Topics