mlreportgen.report.MATLABVariable Class

Namespace: mlreportgen.report
Superclasses: mlreportgen.report.Reporter

MATLAB variable reporter

Description

Create a reporter that reports on a MATLAB^® variable.

The mlreportgen.report.MATLABVariable class is a handle class.

Creation

Description

rptr = mlreportgen.report.MATLABVariable creates a MATLAB variable reporter based on a default template. Before adding this reporter to a report, use its properties to specify the variable name on which to report.

rptr = mlreportgen.report.MATLABVariable(variable) creates a MATLAB variable reporter for the specified MATLAB variable. To specify a local variable, specify its name, for example, MATLABVariable(x). To specify a MATLAB workspace variable, specify its name as a character vector or string scalar, for example, MATLABVariable("x"). To specify other report options, use the properties of this reporter.

rptr = mlreportgen.report.MATLABVariable(Name=Value) creates a MATLAB variable reporter with options specified by one or more Name=Value pair arguments. Name is a property name and Value is the corresponding value. You can specify several name-value arguments in any order as Name1=Value1,...,NameN=ValueN.

Input Arguments

variable — MATLAB variable name

character vector | string scalar | local variable name

MATLAB variable name, specified as a string scalar, character vector, or local variable name. To specify a local variable, specify its name, for example, MATLABVariable(x). To specify a MATLAB workspace variable, specify its name as a character vector or string scalar, for example, MATLABVariable("x"). For more information on the input, see the Variable property.

Properties

Variable — MATLAB variable name

character vector | string scalar

MATLAB variable name, specified as a character vector or string scalar. The specified variable can be any of these data types:

• Character vector

• String scalar

• Cell vector or cell array

• Logical scalar, logical vector, or logical array

• Numeric scalar, numeric array, or numeric vector

• MATLAB table

• MATLAB object vector or object array

• Simulink^® object

• Stateflow^® object

• Graphics object

• MATLAB structure, structure vector, or structure array

• Enumeration

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

Location — Location of variable

"MATLAB" (default) | "MAT-File" | "Global" | "Local" | "Model" | "User-Defined"

Location of variable, specified as one of these strings or as character vectors:

• "MATLAB" — Base workspace

• "MAT-File" — MAT-file specified in the FileName property of this reporter

• "Global" — Global name space

• "Local" — Local name space, typically the name space of the function or workspace in which this reporter was created

• "Model" — Workspace of the Simulink Report Generator™ model specified in the FileName property of this reporter

• "User-Defined" — setVariableValue method set the value to report and set this property to "User-Defined"

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

FileName — Name of file or model that contains the variable

character vector | string scalar

Name of MAT-file or Simulink model that contains the variable, specified as a string scalar or as a character vector. This property applies only if the Location property value is MAT-File or Model. If Location is MAT-File, the file name is the name of the MAT-file from which to obtain the variable. If Location is Model, the FileName is the name of the Simulink model file that contains the variable.

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

FormatPolicy — Format of variable values

"Auto" (default) | "Table" | "Paragraph" | "Inline Text"

Format of the variable values, specified as one of these strings or character vectors:

• "Auto" — Formats the variable values as a table or a paragraph, depending on the data type of the value.

  Data types formatted as a table include:

  • Cell array

  • Logical array

  • Numeric array

  • MATLAB table

  • Simulink object

  • Stateflow object

  • Graphics object

  • MATLAB structure or structure array

  • MATLAB object or object array

  • MATLAB enumeration class that defines properties

  Data types formatted as a paragraph include:

  • Cell vector

  • Logical scalar or vector

  • Numeric scalar or vector

  • Character or character vector

  • String

  • MATLAB structure vector

  • MATLAB object vector

  • MATLAB enumeration class that does not define properties

• "Table" — Formats the variable values in a table. Variables that by default appear as paragraphs are formatted instead as table entries. Variables that are hierarchically structured objects, such as a MATLAB structures, MATLAB objects, Simulink objects, Stateflow objects, or graphics objects, can have properties that are themselves objects. In that case, the hierarchy is flattened and the property value is displayed as a hyperlink to a table of the properties of that object. The object property table also has a hyperlink back to the original table.

• "Paragraph" — Format the variable values as a paragraph. Variables that by default are formatted as tables are flattened and formatted as a paragraph.

• "Inline Text" — Formats the variable in line with the surrounding text.

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

TableReporter — Table reporter for variable values

mlreportgen.report.BaseTable

Table reporter used by this MATLABVariable reporter to format variable values, specified as an mlreportgen.report.BaseTable object. To customize the appearance of the table, modify the default BaseTable reporter properties or replace it with a customized BaseTable reporter. If you add content to the Title property of the default or customized reporter, that content appears in front of the table title in the generated report.

Attributes:

GetAccess	public
SetAccess	public

ParagraphFormatter — Paragraph formatter for MATLAB variable

mlreportgen.dom.Paragraph object

Paragraph formatter object to format the value of the MATLAB variable, specified as an mlreportgen.dom.Paragraph object. To customize the appearance of the paragraph, modify the DOM Paragraph object properties or replace the object with a customized Paragraph object. If you add content to the default or replacement paragraph object, that content appears in front of the variable content in the generated report.

Attributes:

GetAccess	public
SetAccess	public

TextFormatter — Text formatter for MATLAB variable

mlreportgen.dom.Text object

Text formatter object to format MATLAB variable text values in tables or paragraphs, specified as an mlreportgen.dom.Text object. To customize the appearance of the text, modify the DOM Text object properties or replace the object with a customized Text object. If you add content to the default or replacement text object, that content appears in front of the variable content in the generated report.

Attributes:

GetAccess	public
SetAccess	public

MaxCols — Maximum number of table columns to display

32 (default) | positive integer

Maximum number of table columns to display, specified as a positive integer. For array variables reported using a table, if the number of columns is greater than the value of the MaxCols property, the table is sliced vertically. Slicing divides the table into multiple tables.

Attributes:

GetAccess	public
SetAccess	public

Data Types: int32

DepthLimit — Maximum number of nested levels to report

10 (default) | nonnegative integer

Maximum number of levels to report for a variable that is a structured object or an array of structured objects, specified as a nonnegative integer. Levels less than or equal to the value of DepthLimit are flattened into a sequence of interlinked tables (see the FormatPolicy property). Levels greater than the depth limit are not reported. If you set the DepthLimit property to 0, structured objects are not expanded.

Attributes:

GetAccess	public
SetAccess	public

Data Types: int32

ObjectLimit — Maximum number of nested objects to report

200 (default) | positive integer

Maximum number of objects in an object hierarchy to report, specified as a positive integer.

Attributes:

GetAccess	public
SetAccess	public

Data Types: int32

IncludeTitle — Whether to include title

true (default) | false

Whether to include a title, specified as true or false. The title contains the variable name and optionally, the data type. If IncludeTitle is true, the title is included. By default, the title includes only the name of the variable. To include the data type of the variable, set the ShowDataType property to true.

Attributes:

GetAccess	public
SetAccess	public

Data Types: logical

Title — Title of variable to report

[] (default) | character vector | string scalar | mlreportgen.dom.Text object | mlreportgen.dom.InternalLink object | mlreportgen.dom.ExternalLink object

Title of variable to report, specified as a character vector, string scalar, mlreportgen.dom.Text object, mlreportgen.dom.InternalLink object, or mlreportgen.dom.ExternalLink object.

If the FormatPolicy property is set to "Inline Text" and the Title property is set to:

• A DOM object, the formatting specified by the DOM object is ignored

• An mlreportgen.dom.InternalLink or mlreportgen.dom.ExternalLink object, the link text is used for the title, but the title is not a link

In both cases, to format the title, use the TextFormatter property of this MATLABVariable reporter.

If you do not specify the Title property, the title is the variable name.

Attributes:

GetAccess	public
SetAccess	public

ShowDataType — Whether to show data type of variable in title

false (default) | true

Whether to show the data type of the variable in the title, specified as true or false.

Attributes:

GetAccess	public
SetAccess	public

Data Types: logical

ShowEmptyValues — Whether to show properties that have empty values

true (default) | false

Whether to show properties that have empty values, specified as a true or false. The ShowEmptyValues property applies only to MATLAB object, Simulink object, and Stateflow object variables.

Attributes:

GetAccess	public
SetAccess	public

Data Types: logical

ShowDefaultValues — Whether to show properties that use default values

true (default) | 0

Whether to show properties that use the default value, specified as true or false. The ShowDefaultValues property applies only to MATLAB object, Simulink object, and Stateflow object variables.

Attributes:

GetAccess	public
SetAccess	public

Data Types: logical

PropertyFilterFcn — Function or expression to filter properties of a reported variable

[] (default) | function handle | character vector | string scalar

Function or expression to filter the properties of a variable from a report. Specify a function as a function handle. Specify an expression as a character vector or string scalar. This property applies only to variables that contain objects. If you do not provide PropertyFilterFcn, all properties of the variable are included in the report.

If you provide a function handle, the associated function must:

• Take these arguments:

  • variableName — Name of the variable being reported

  • variableObject — The variable being reported

  • propertyName — Name of the property of the variable being reported

• Return true to filter the specified property from the report, or false to include the property in the report.

For example, this code prevents the display of the NumRegions and NumHolesproperties of a polyshape object.

import mlreportgen.report.*

rpt = mlreportgen.report.Report("variablerpt","pdf");
open(rpt);

pgon = polyshape([0 0 2 2],[2 0 0 2]);
mlVar = mlreportgen.report.MATLABVariable(pgon);
mlVar.PropertyFilterFcn = @varPropertyFilter;
add(rpt,mlVar);

close(rpt);
rptview(rpt);

function tf = varPropertyFilter(~,variableObject,propertyName)
if isa(variableObject, "polyshape")
    tf = (propertyName == "NumRegions") ||  ...
        (propertyName == "NumHoles");
    
end
end

If you provide a string scalar or a character vector, it must contain an expression. The expression:

• Can use the variables variableName, variableObject, and propertyName

• Must set the variable isFiltered to true to filter the specified property from the report, or false to include the property in the report

For example, this code filters the NumHoles property of polyshape object from the report.

import mlreportgen.report.*

rpt = mlreportgen.report.Report("variablerpt","pdf");
open(rpt);


pgon = polyshape([0 0 2 2],[2 0 0 2]);
mlVar = mlreportgen.report.MATLABVariable(pgon);
mlVar.PropertyFilterFcn = "isFiltered = " + ...
            "isa(variableObject, "polyshape") && " + ...
            "propertyName == "NumHoles";";
add(rpt,mlVar);

close(rpt);
rptview(rpt);

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string | function_handle

NumericFormat — Format or precision used to display noninteger numeric values

[] (default) | character vector | string scalar | positive integer

Format or precision used to display noninteger numeric values.

Specify a format as a string scalar or a character vector. See the formatSpec argument on the sprintf reference page.

Specify precision as a positive integer. See the precision argument on the num2str reference page.

Example: "%.2f" displays double values with two digits to the right of the decimal place.

Example: 2 displays a maximum number of two significant digits.

Attributes:

GetAccess	public
SetAccess	public

Data Types: int32 | char | string

TemplateSrc — Source of template for this reporter

character vector | string scalar | reporter or report | DOM document or document part

Source of the template for this reporter, specified in one of these ways:

• Character vector or string scalar that specifies the path of the file that contains the template for this reporter

• Reporter or report whose template this reporter uses or whose template library contains the template for this reporter

• Document Object Model (DOM) document or document part whose template this reporter uses or whose template library contains the template for this reporter

The specified template must be the same type as the report to which you append this reporter. For example, for a Microsoft^® Word report, TemplateSrc must be a Word reporter template. If the TemplateSrc property is empty, this reporter uses the default reporter template for the output type of the report.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

TemplateName — Name of template for this reporter

character vector | string scalar

Name of the template for this reporter, specified as a character vector or string scalar. The template for this reporter must be in the template library of the template specified by the TemplateSrc property of this reporter.

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

LinkTarget — Hyperlink target for this reporter

[] (default) | character vector | string scalar | mlreportgen.dom.LinkTarget object

Hyperlink target for this reporter, specified as a character vector or string scalar that specifies the link target ID, or an mlreportgen.dom.LinkTarget object. A character vector or string scalar value converts to a LinkTarget object. The link target immediately precedes the content of this reporter in the output report.

Attributes:

GetAccess	public
SetAccess	public

Methods

Public Methods

Method	Purpose
getVariableValue	Get MATLAB variable value
setVariableValue	Set the value to report for a variable
mlreportgen.report.MATLABVariable.createTemplate	template = mlreportgen.report.MATLABVariable.createTemplate(path,type) Create reporter template Input Arguments path, Target path and file name for template file type, Template type, specified as "html", "docx", or "pdf" Return Values template — Path and file name of the template copy, returned as a string scalar. For more information, see the equivalent method for the Reporter class, mlreportgen.report.Reporter.createTemplate.
mlreportgen.report.MATLABVariable.customizeReporter	reporter = mlreportgen.report.MATLABVariable.customizeReporter(classpath) Create reporter derived from mlreportgen.report.MATLABVariable class Return Values reporter — Path and file name of the new reporter class, returned as a string scalar. For more information, see the equivalent method for the Reporter class, mlreportgen.report.Reporter.customizeReporter.
mlreportgen.report.MATLABVariable.getClassFolder	path = mlreportgen.report.MATLABVariable.getClassFolder Get location of folder that contains mlreportgen.report.MATLABVariable class definition file Return Values path — Class definition file location, returned as a character vector. For more information, see the equivalent method for the Reporter class, mlreportgen.report.Reporter.getClassFolder.
copy	Create copy of reporter object and make deep copies of certain property values
getImpl	Get implementation of reporter

Examples

Report Variables Using Direct Names or Strings

This example shows how to report on MATLAB variables. The local variable uses only its name as input to the MATLABVariable class and the workspace variable uses a string. The first part of the example uses default property settings and the second part changes the display to a table.

Note

Before you run this example, create this variable in the base MATLAB workspace:

workspace_var = ["Workspace variable input ",...
   "specified as a string"];

rpt = mlreportgen.report.Report("MyReport","pdf");

local_var = ["Local variable input specified ",...
   "using its variable name"];

chapter = mlreportgen.report.Chapter();
chapter.Title = "MATLAB Variable Reporter Example";

% Format using default paragraphs
rptr_local1 = mlreportgen.report.MATLABVariable...
   (local_var);
rptr_workspace1 = mlreportgen.report.MATLABVariable...
   ("workspace_var");

add(chapter,rptr_local1)
add(chapter,rptr_workspace1)

% Format as a table
rptr_local2 = mlreportgen.report.MATLABVariable...
   (local_var);
rptr_workspace2 = mlreportgen.report.MATLABVariable...
   ("workspace_var");
rptr_local2.FormatPolicy = "Table";
rptr_workspace2.FormatPolicy = "Table";

add(chapter,rptr_local2)
add(chapter,rptr_workspace2)
add(rpt,chapter)
 
close(rpt)
rptview(rpt)

Version History

Introduced in R2018b