ArrayPlotConfiguration

(Not recommended) Control Array Plot block appearance and behavior from MATLAB

ArrayPlotConfiguration is not recommended. Use get_param (Simulink) and set_param (Simulink) to modify the Array Plot block properties. For more information, see Version History.

Description

Use the Array Plot Configuration object to control the appearance and behavior of an Array Plot block. Create a configuration object with get_param, and then change property values using the object with dot notation.

You can also modify the Array Plot block properties using get_param (Simulink) and set_param (Simulink).

Creation

MyScopeConfiguration = get_param(gcbh,'ScopeConfiguration') creates a new Array Plot Configuration object. If you do not provide the full path to the block, you must first select the block in the model.

Properties

Plot Configuration

NumInputPorts — Number of input ports

'1' (default) | character vector

Number of input ports on a scope block, specified as a character vector. The maximum number of input ports is 96.

XDataMode — Source of the x-data spacing

'Sample increment and X-offset' (default) | 'Custom'

Specify whether to use the SampleIncrement and XOffset property values to determine spacing, or specify your own custom spacing. If you specify 'Custom', you also must specify the CustomXData property values.

You can set this property only before simulation.

Data Types: char | string

SampleIncrement — x-axis spacing

'1' (default) | character vector

The spacing between samples along the x-axis, specified as a finite scalar in a character vector. The input signal is only y-axis data. x-axis data is set automatically based on the XOffset and SampleIncrement properties.

Example: When XOffset is 0 and SampleIncrement is 1, the x-axis values are set to 0, 1, 2, 3, 4, … .

Example: When XOffset is -1 and SampleIncrement is 0.25, the x-axis values are set to -1, -0.75, -0.5, -0.25, 0, … .

Dependency

To use this property, set XDataMode to 'Sample increment and X-offset'.

XOffset — Display offset of x-axis

'0' (default) | character vector

Display offset of x-axis, specified as a numeric scalar in a character vector. x-axis data is set automatically based on both the SampleIncrement and XOffset values. The x-offset represents the first value on the x-axis.

Example: When XOffset is 0 and SampleIncrement is 1, the x-axis values are set to 0, 1, 2, 3, 4, … .

Example: When XOffset is -1 and SampleIncrement is 0.25, the x-axis values are set to -1, -0.75, -0.5, -0.25, 0, … .

Dependency

To use this property, set XDataMode to 'Sample increment and X-offset'.

CustomXData — x-data values

'[]' (default) | character vector

Specify the desired x-data values as a numeric vector in a character vector. The row or column vector must be equal to the frame length of the inputs. If you use the default (empty vector) value, the x-data is uniformly spaced and set to (0:L–1), where L is the frame length.

Example: scopeConfiguration.XDataMode = 'Custom'; scopeConfiguration.CustomXData = 'logspace(0,log10(44100/2),1024)'

Dependency

To use this property, set XDataMode to 'Custom'.

XScale — Scale of x-axis

"Linear" (default) | "Log"

Specify whether the scale of the x-axis is "Linear" or "Log". If XOffset is a negative value, you cannot set this property to "Log".

Scope Window Use

Open the Scope tab, click Settings, and set X-Scale.

Data Types: char | string

YScale — Scale of y-axis

"Linear" (default) | "Log"

Specify whether the scale of the y-axis is "Linear" or "Log".

Scope Window Use

Open the Scope tab, click Settings, and set Y-Scale.

Data Types: char | string

Visualization

PlotType — Type of plot

"Stem" (default) | "Line" | "Stairs" | "Bar"

Type of plot to use for all the input signals displayed in the scope window, specified as one of these:

• "Stem" – The scope displays the input signal as circles with vertical lines extending down to the x-axis at each of the sampled values.

• "Line" – The scope displays the input signal as lines connecting each of the sampled values.

• "Stairs" – The scope displays the input signal as a stair-step graph. A stair-step graph is made up of only horizontal lines and vertical lines. Each horizontal line represents the signal value for a discrete sample period and is connected to two vertical lines. Each vertical line represents a change in values occurring at a sample. Stair-step graphs are useful for drawing time history graphs of digitally sampled data.

• "Bar" –– The scope displays the input signal with rectangular bars, where bar lengths are proportional to the signal values. (since R2024b)

Tunable: Yes

Scope Window Use

Open the Scope tab, click Settings, and set Plot Type.

AxesScaling — Axes scaling mode

"OnceAtStop" (default) | "Auto" | "Manual" | "Updates"

Specify when the scope scales the axes. Valid values are:

• "Auto" — The scope scales the axes as needed to fit the data, both during and after simulation.

• "Manual" — The scope does not scale the axes automatically.

• "OnceAtStop" — The scope scales the axes when the simulation stops.

• "Updates" — The scope scales the axes once and only once after a specified number of updates. To specify the number of updates, use the AxesScalingNumUpdates property.

AxesScalingNumUpdates — Number of updates before scaling

"10" (default) | integer character vector | integer string scalar

Set this property to delay auto scaling the y-axis.

Dependency

To enable this property, set AxesScaling to "Updates".

Name — Window name

'Array Plot' (default) | character vector | string scalar

Specify the name of the scope. This name appears as the title of the scope's figure window. To specify a title of a scope plot, use the Title property.

Data Types: char | string

Position — Scope window position and size in pixels

screen center (default) | [left bottom width height]

Specify, in pixels, the size and location of the scope window as a four-element vector of the form [left bottom width height]. By default, the scope window appears in the center of your screen with a width of 800 pixels and height of 450 pixels. The default values for this property may change depending on your screen resolution.

MaximizeAxes — Maximize axes control

"Auto" (default) | "On" | "Off"

Specify whether to display the scope in maximized-axes mode. In this mode, the axes are expanded to fit into the entire display. To conserve space, labels do not appear in each display. Instead, tick-mark values appear on top of the plotted data. You can select one of the following options:

• "Auto" — The axes appear maximized in all displays only if the Title and YLabel properties are empty for every display. If you enter any value in any display for either of these properties, the axes are not maximized.

• "On" — The axes appear maximized in all displays. Any values entered into the Title and YLabel properties are hidden.

• "Off" — None of the axes appear maximized.

Scope Window Use

Hover over the array plot to see the maximize axes button .

Data Types: char | string

Title — Display title

"" (default) | character vector | string scalar

Specify the display title as a character vector or string.

Scope Window Use

On the Scope tab, click Settings, and set Title.

Data Types: char | string

PlotAsMagnitudePhase — Plot signal as magnitude and phase

false (default) | true

• true – The scope plots the magnitude and phase of the input signal on two separate axes within the same active display.

• false – The scope plots the real and imaginary parts of the input signal on two separate axes within the same active display.

This property is useful for complex-valued input signals. Turning on this property affects the phase for real-valued input signals. When the amplitude of the input signal is nonnegative, the phase is 0 degrees. When the amplitude of the input signal is negative, the phase is 180 degrees.

Scope Window Use

On the Scope tab, click Settings, and select Magnitude Phase Plot.

XLabel — x-axis label

"" (default) | character vector | string scalar

Specify the text for the scope to display below the x-axis.

Scope Window Use

On the Scope tab, click Settings, and set X-Label.

Data Types: char | string

YLabel — y-axis label

"Amplitude" (default) | character vector | string scalar

Specify the text for the scope to display to the left of the y-axis.

Dependencies

This property applies only when PlotAsMagnitudePhase is false. When PlotAsMagnitudePhase is true, the two y-axis labels are read-only values "Magnitude" and "Phase", for the magnitude plot and the phase plot, respectively.

Scope Window Use

On the Scope tab, click Settings, and set Y-Label.

Data Types: char | string

YLimits — y-axis limits

[-10,10] (default) | [ymin, ymax]

Specify the y-axis limits as a two-element numeric vector, [ymin, ymax].

If PlotAsMagnitudePhase is false, the default is [-10,10]. If PlotAsMagnitudePhase is true, the default is [0,10].

Dependencies

When PlotAsMagnitudePhase is true, this property specifies the y-axis limits of only the magnitude plot. The y-axis limits of the phase plot are always [-180,180].

Scope Window Use

On the Scope tab, click Settings, and set Y-Limits as a two-element numeric vector.

ShowGrid — Display grid

true (default) | false

Set this property to true to show grid lines on the plot.

Scope Window Use

On the Scope tab, click Settings, and select Show Grid.

ShowLegend — Show legend

false (default) | true

To show a legend with the input names, set this property to true.

From the legend, you can control which signals are visible. This control is equivalent to changing the visibility in the Style dialog box. In the scope legend, click a signal name to hide the signal in the scope. To show the signal, click the signal name again. To show only one signal, right-click the signal name. To show all signals, press Esc.

Note

The legend only shows the first 20 signals. Any additional signals cannot be viewed or controlled from the legend.

Scope Window Use

On the Scope tab, click Legend. Alternatively, click Settings in the Scope tab, and select Show Legend.

Data Types: logical

ChannelNames — Channel names

empty cell (default) | cell array of character vectors | array of strings

Specify the input channel names as a cell array of character vectors or an array of strings. The names appear in the legend, Settings, and Measurements panels. If you do not specify names, the channels are labeled as Channel 1, Channel 2, etc.

Dependency

To see channel names, set ShowLegend to true.

Data Types: char

OpenAtSimulationStart — Flag to open scope when simulation starts

true (default) | false

Flag to open scope when simulation starts, specified as true or false.

Set this property to true to open the scope when the simulation starts. Set this property to false to prevent the scope from opening when you simulate the model.

Scope Window Use

Click Settings in the Scope tab. In the Spectrum Analyzer Settings window that opens, select Open at Simulation Start.

Data Types: logical

Examples

Change the Array Plot Block Title and Scaling From the Command Line

Modify an Array Plot block with a configuration object.

Create a new Simulink^® model with a randomly-generated name.

sysname='ArrayPlotExample';
new_system(sysname);

Add a new Array Plot block to the model.

add_block('built-in/ArrayPlot',[sysname,'/ArrayPlot'])

Call the get_param (Simulink) function to retrieve the default Array Plot block configuration properties.

scopeConfig = get_param([sysname,'/ArrayPlot'],'ScopeConfiguration')

scopeConfig = 
  ArrayPlotConfiguration with properties:

            NumInputPorts: '1'
                XDataMode: 'Sample increment and X-offset'
          SampleIncrement: '1'
                  XOffset: '0'
              CustomXData: '[]'
                   XScale: 'Linear'
                   YScale: 'Linear'
                 PlotType: 'Stem'
              AxesScaling: 'OnceAtStop'
    AxesScalingNumUpdates: '100'
                     Name: 'ArrayPlot'
                 Position: [240 262 800 500]
             MaximizeAxes: 'Auto'
     PlotAsMagnitudePhase: 0
                    Title: ''
                   XLabel: ''
                   YLabel: 'Amplitude'
                  YLimits: [-10 10]
                 ShowGrid: 1
               ShowLegend: 0
             ChannelNames: {''}
    OpenAtSimulationStart: 1
                  Visible: 0

Modify the Array Plot title and axes scaling.

scopeConfig.Title = 'My Array Plot';
scopeConfig.AxesScaling = 'Manual'

scopeConfig = 
  ArrayPlotConfiguration with properties:

            NumInputPorts: '1'
                XDataMode: 'Sample increment and X-offset'
          SampleIncrement: '1'
                  XOffset: '0'
              CustomXData: '[]'
                   XScale: 'Linear'
                   YScale: 'Linear'
                 PlotType: 'Stem'
              AxesScaling: 'OnceAtStop'
    AxesScalingNumUpdates: '100'
                     Name: 'ArrayPlot'
                 Position: [240 262 800 500]
             MaximizeAxes: 'Auto'
     PlotAsMagnitudePhase: 0
                    Title: ''
                   XLabel: ''
                   YLabel: 'Amplitude'
                  YLimits: [-10 10]
                 ShowGrid: 1
               ShowLegend: 0
             ChannelNames: {''}
    OpenAtSimulationStart: 1
                  Visible: 0

Version History

Introduced in R2013a

R2022b: Channel names support array of strings

Starting in R2022b, you can specify the ChannelNames property of the ArrayPlotConfiguration object as an array of strings.

scopeConfig = get_param(gcbh,'ScopeConfiguration')
scopeConfig.ChannelNames=["Input", "Lowpass Output"];

R2021a: ArrayPlotConfiguration is not recommended

The ArrayPlotConfiguration object is not recommended. To view and modify the Array Plot block properties from the command-line, use get_param (Simulink) and set_param (Simulink). For example, to change the number of input ports, use these commands.

modelname='ArrayPlotExample';
new_system(modelname);
add_block('built-in/ArrayPlot',[sysname,'/ArrayPlot'])
set_param([modelname,'/ArrayPlot'],'NumInputPorts','4')