Customize Metrics Dashboard Layout and Functionality

Open Live Script

Customize the Metrics Dashboard by using the model metric programming interface. Customizing the dashboard extends your ability to use model metrics to assess that your model and code comply with size, complexity, and readability requirements. You can perform these Metrics Dashboard customizations:

Configure compliance metrics to obtain compliance and issues metric data on your Model Advisor configuration.
Customize the dashboard layout by adding custom metrics, removing widgets, and configuring existing widgets.
Categorize metric data as compliant, warning, and noncompliant by specifying metric threshold values.

Configure Compliance Metrics

Use the Metrics Dashboard and metric APIs to obtain compliance and issues metric data on your Model Advisor configuration or on an existing check group such as the MISRA checks. For information on how to create a custom configuration file, see Use Model Advisor Configuration Editor to Customize Model Advisor. After you have set up your Model Advisor configuration, follow these steps to specify the check groups for which you want to obtain compliance and issues metric data:

1. To open the model, at the MATLAB® command prompt, enter this command:

vdp

2. Open the default configuration and save a corresponding slmetric.config.Configuration object to the base workspace.

metricconfig = slmetric.config.Configuration.openDefaultConfiguration();

3. Create a cell array, values, that specifies the Model Advisor Check Group IDs for MAAB, High-Integrity, and MISRA check groups.

The value maab corresponds to a subset of the MAAB checks.
The value hisl_do178 corresponds to a subset of the High-Integrity System checks.
The value _SYSTEM_By Task_misra_c is the Check Group ID for the MISRA check group Modeling Standards for MISRA C:2012.

values = {'maab', 'hisl_do178', '_SYSTEM_By Task_misra_c'};

To obtain the Model Advisor Check Group ID for a group of checks, open the Model Advisor Configuration Editor and select the folder that contains the desired group of checks. The Check Group ID is shown in the Information tab. For more information on the Model Advisor Configuration Editor, see Use Model Advisor Configuration Editor to Customize Model Advisor.

4. To set the configuration, pass the values cell array into the setMetricFamilyParameterValues method. The 'ModelAdvisorStandard' string is a standard string that you must supply to the setMetricFamilyParameterValues method.

setMetricFamilyParameterValues(metricconfig,'ModelAdvisorStandard', values);

5. Open the default configuration for the Metrics Dashboard layout (that is, the one that ships with the Metrics Dashboard).

dashboardconfig = slmetric.dashboard.Configuration.openDefaultConfiguration();

6. Obtain the slmetric.dashboard.Layout object from the slmetric.dashboard.Configuration object.

layout = getDashboardLayout(dashboardconfig);

7. Obtain widget objects that are in the layout object.

layoutWidget = getWidgets(layout);

8. Obtain the compliance group from the layout.

complianceGroup = layoutWidget(3);

The slmetric.dashboard.Layout object contains these objects:

An slmetric.dashboard.Container object that holds an slmetrics.dashboard.Widget object of type SystemInfo. The red number one in the diagram below indicates the SystemInfo widget.
An slmetric.dashboard.Group object that has the title SIZE.
An slmetric.dashboard.Group object that has the title MODELING GUIDELINE COMPLIANCE.
An slmetric.dashboard.Group object that has the title ARCHITECTURE.

In the diagram, the red numbers 1, 2, 3, and 4 indicate their order in the layoutWidget array.

9. The modeling guideline compliance group contains two containers. The top container contains the High Integrity and MAAB compliance and check issues widgets. The red numbers 3.1.1, 3.1.2, and 3.1.3 indicate the order of the three widgets in the first container. The second container contains the Code Analyzer Warnings and Diagnostic Warnings widgets.

Remove the High Integrity compliance widget.

complianceContainers = getWidgets(complianceGroup);
complianceContainerWidgets = getWidgets(complianceContainers(1));
complianceContainers(1).removeWidget(complianceContainerWidgets(1));

10. The Metric ID for the configured MISRA check compliance metric is 'mathworks.metrics.ModelAdvisorCheckCompliance._SYSTEM_By Task_misra_c'.

misraComplianceMetricID = 'mathworks.metrics.ModelAdvisorCheckCompliance._SYSTEM_By Task_misra_c';

The Metric ID for a configured check compliance metric is of the form <Family ID>.<Model Advisor Check Group ID>.

Metrics configured for Model Advisor compliance use the <Family ID> mathworks.metrics.ModelAdvisorCheckCompliance. Configured check compliance metrics calculate the fraction of Model Advisor checks that pass for the selected Model Advisor Check Group ID.
The Model Advisor Check Group ID, _SYSTEM_By Task_misra_c, is the Check Group ID for the MISRA check group Modeling Standards for MISRA C:2012.

For more information on configured compliance metrics, see Model Metrics.

11. Create a custom widget for visualizing MISRA check compliance metrics.

misraWidget = complianceContainers(1).addWidget('Custom', 1);
misraWidget.Title = ('MISRA');
misraWidget.VisualizationType = 'RadialGauge';
misraWidget.setMetricIDs(misraComplianceMetricID);
misraWidget.setWidths(slmetric.dashboard.Width.Medium);

12. The bar chart widget currently visualizes the High Integrity and MAAB check groups. Point this widget to the Metric IDs for the MISRA check issues and MAAB check issues.

misraIssuesMetricID = 'mathworks.metrics.ModelAdvisorCheckIssues._SYSTEM_By Task_misra_c';
maabIssuesMetricID = 'mathworks.metrics.ModelAdvisorCheckIssues.maab';

setMetricIDs(complianceContainerWidgets(3),...
({misraIssuesMetricID,maabIssuesMetricID}));
complianceContainerWidgets(3).Labels = {'MISRA', 'MAAB'};

The Metric ID for a configured check compliance metric is of the form <Family ID>.<Model Advisor Check Group ID>.

Metrics configured for Model Advisor compliance issues use the <Family ID> mathworks.metrics.ModelAdvisorCheckIssues. Configured check compliance issues metrics calculate the number of issues reported by the selected Model Advisor Check Group ID.
The Model Advisor Check Group ID, _SYSTEM_By Task_misra_c, is the Check Group ID for the MISRA check group Modeling Standards for MISRA C:2012. maab is a Check Group ID that corresponds to a subset of MAAB checks.

For more information on configured compliance metrics, see Model Metrics.

13. To run and view the Metrics Dashboard at this point in the example, enter the following lines of code in the MATLAB Command Window. The save commands serialize the API information to XML files. The slmetric.config.setActiveConfiguration and slmetric.dashboard.setActiveConfiguration commands set the active configuration objects.

save(metricconfig,'FileName','MetricConfig.xml');
save(dashboardconfig,'Filename','DashboardConfig.xml');
slmetric.config.setActiveConfiguration(fullfile(pwd,'MetricConfig.xml'));
slmetric.dashboard.setActiveConfiguration(fullfile(pwd,'DashboardConfig.xml'));

14. To open the Metrics Dashboard, enter the following code in the MATLAB Command Window.

metricsdashboard vdp

15. Click the All Metrics button to run each of the metrics. The Metrics Dashboard displays results for the MISRA checks instead of the High Integrity checks.

16. Close the Metrics Dashboard.

Add a Custom Metric to Dashboard

Create a custom metric that counts nonvirtual blocks. To display this metric on the Metrics Dashboard, specify a widget. Add it to the size group.

1. Using the createNewMetricClass function, create a new metric class named nonvirtualblockcount. The function creates a file, nonvirtualblockcount.m, in the current working folder. The file contains a constructor and empty metric algorithm method. For this example, make sure you are in a writable folder.

className = 'nonvirtualblockcount';
slmetric.metric.createNewMetricClass(className);

2. To write the metric algorithm, open the nonvirtualblockcount.m file and add the metric to the file. For this example, the file nonvirtualblockcount_orig.m contains the logic to create a metric that counts the nonvirtual blocks. Copy this file to the to nonvirtualblockcount.m.

copyfile nonvirtualblockcount_orig.m nonvirtualblockcount.m f

3. Register the new metric in the metric repository.

[id_metric,err_msg] = slmetric.metric.registerMetric(className);

The new nonvirtual block count metric has the metric ID nonvirtualblockcount.

To view the available metrics for your metric engine, use slmetric.metric.getAvailableMetrics.

availableMetricIDs = slmetric.metric.getAvailableMetrics

4. Remove the widget that represents the Simulink® block count metric. This widget is the first one in the size group. The size group is second in the layoutWidget array.

sizeGroup = layoutWidget(2);
sizeGroupWidgets = sizeGroup.getWidgets();
sizeGroup.removeWidget(sizeGroupWidgets(1));

5. Add a widget that displays the nonvirtual block count metric. For custom widgets, the default visualization type is single value. If you want to use a different visualization type, specify a different value for the VisualizationType property.

newWidget = sizeGroup.addWidget('Custom', 1);
newWidget.Title = ('Nonvirtual Block Count');
newWidget.setMetricIDs('nonvirtualblockcount');
newWidget.setWidths(slmetric.dashboard.Width.Medium);
newWidget.setHeight(70);

6. Specify whether there are lines separating the custom widget from other widgets in the group. These commands specify that there is a line to the right of the widget.

s.top = false;
s.bottom = false;
s.left = false;
s.right = true;
newWidget.setSeparators([s, s, s, s]);

7. To run and view the Metrics Dashboard at this point in the example, enter the following lines of code in the MATLAB Command Window. The save commands serialize the API information to XML files. The slmetric.config.setActiveConfiguration and slmetric.dashboard.setActiveConfiguration commands set the active configuration objects.

save(metricconfig,'FileName','MetricConfig.xml');
save(dashboardconfig,'Filename','DashboardConfig.xml');
slmetric.config.setActiveConfiguration(fullfile(pwd,'MetricConfig.xml'));
slmetric.dashboard.setActiveConfiguration(fullfile(pwd,'DashboardConfig.xml'));

8. To open the Metrics Dashboard, enter the following code in the MATLAB Command Window.

metricsdashboard vdp

9. Click the All Metrics button to run each of the metrics. The Metrics Dashboard displays results for the nonvirtual block count metric instead of the Simulink block count metric.

10. Close the Metrics Dashboard.

Add Metric Thresholds

For the nonvirtual block count and MISRA metrics, specify metric threshold values. Specifying these values enables you to access the quality of your model by categorizing your metric data as follows:

Compliant — Metric data that is in an acceptable range.
Warning — Metric data that requires review.
Noncompliant — Metric data that requires you to modify your model.

1. Access the slmetric.config.ThresholdConfiguration object in the slmetric.config.Configuration object metricconfig. Create the corresponding slmetric.config.ThresholdConfiguration object (TC) in the base workspace.

TC = getThresholdConfigurations(metricconfig);

2. Add two slmetric.config.Threshold objects to TC. Each slmetric.config.Threshold object contains a default slmetric.config.Classification object that is compliant. Specify the compliant metric ranges.

T1 = addThreshold(TC, misraIssuesMetricID,'AggregatedValue');
C = getClassifications(T1);
C.Range.Start = -inf;
C.Range.End = 0;
C.Range.IncludeStart = 0;
C.Range.IncludeEnd = 1;

T2 = addThreshold(TC,misraComplianceMetricID,'AggregatedValue');
C = getClassifications(T2);
C.Range.Start = 1;
C.Range.End = inf;
C.Range.IncludeStart = 1;
C.Range.IncludeEnd = 0;

3. For each slmetric.config.Threshold object, specify the Warning ranges.

C = addClassification(T1,'Warning');
C.Range.Start = 0;
C.Range.End = inf;
C.Range.IncludeStart = 0;
C.Range.IncludeEnd = 1;

C = addClassification(T2,'Warning');
C.Range.Start = -inf;
C.Range.End = 1;
C.Range.IncludeStart = 0;
C.Range.IncludeEnd = 0;

These commands specify that if the model has MISRA check issues, the model status is warning. If the model does not have MISRA check issues, the model status is compliant.

4. Add a third slmetric.config.Threshold object to TC. Specify compliant, warning, and noncompliant ranges for this slmetric.config.Threshold object.

T3 = addThreshold(TC,'nonvirtualblockcount', 'AggregatedValue');
C = getClassifications(T3); 
C.Range.Start = -inf;
C.Range.End = 20;
C.Range.IncludeStart = 1;
C.Range.IncludeEnd = 1;

C = addClassification(T3, 'Warning');
C.Range.Start = 20;
C.Range.End = 30;
C.Range.IncludeStart = 0;
C.Range.IncludeEnd = 1;

C = addClassification(T3, 'NonCompliant');
C.Range.Start = 30;
C.Range.End = inf;
C.Range.IncludeStart = 0;
C.Range.IncludeEnd = 1;

These commands specify that the compliant range is less than or equal to 20. The warning range is from 20 up to but not including 30. The noncompliant range is greater than 30.

5. Save the configuration objects. These commands serialize the API information to XML files.

save(metricconfig,'FileName','MetricConfig.xml');
save(dashboardconfig,'Filename','DashboardConfig.xml');

6. Set the active configurations.

slmetric.config.setActiveConfiguration(fullfile(pwd, 'MetricConfig.xml'));
slmetric.dashboard.setActiveConfiguration(fullfile(pwd, 'DashboardConfig.xml'));

7. For your model, open the Metrics Dashboard.

metricsdashboard vdp

For the MISRA check compliance issues, the gauge is yellow because only 77.8% of the checks pass. A percentage less than 100% generates a warning. The bar chart also displays a yellow because the model contains three MISRA check issues. A number greater than zero generates a warning.

The Nonvirtual Block Count widget is in the compliant range because there are 11 nonvirtual blocks.

8. To reset the configuration and unregister the metric, enter the following lines of code in the MATLAB Command Window.

slmetric.metric.unregisterMetric(className);
slmetric.dashboard.setActiveConfiguration('');
slmetric.config.setActiveConfiguration('');

Customize Metrics Dashboard Layout and Functionality

Configure Compliance Metrics

Add a Custom Metric to Dashboard

Add Metric Thresholds

See Also

Topics