Customizing Response Plots from the Command Line

Overview of Customizing Plots from the Command Line

When to Customize Plots from the Command Line

You can customize any response plot from the command line. The command line is the most efficient way to customize a large number of plots. For example, if you have a batch job that produces many plots, you can change the x-axis units automatically for all the plot with just a few lines of code.

How to Customize Plots from the Command Line

You can use the Control System Toolbox™ application program interface (API) to customize plotting options for response plots from the command line.

Note

This section assumes some very basic familiarity with MATLAB^® graphics objects. For more information, see Graphics Objects.

To customize plots from the command line:

Obtain the plot handle, which is an identifier for the plot, using the API's plotting syntax.
For example,
```
h = stepplot(sys)
```
returns the plot handle h for the step plot.
For more information on obtaining plot handles, see Obtaining Plot Handles.
Obtain the plot options handle, which is an identifier for all settable plot options. To get a plot options handle for a given plot, type
```
p = getoptions(h);
```
p is the plot options handle for plot handle h.
For more information on obtaining plot options handles, see Obtaining Plot Options Handles.
Use setoptions, along with the plot handle and the plot options handle, to access and modify many plot options.

Note

You can also use setoptions to customize plots using property/value pairs instead of the plot options handle. Using property/value pairs shortens the procedure to one line of code.

Change Bode Plot Units from the Command Line

Open Live Script

This example shows how to change the units of a Bode plot from rad/s to Hz.

Create a system and generate a Bode Plot of the system's response. The plot uses the default units, rad/s.

sys = tf(4,[1 0.5 4]);
h = bodeplot(sys);

Figure contains 2 axes objects. Axes object 1 with ylabel Magnitude (dB) contains an object of type line. This object represents sys. Axes object 2 with ylabel Phase (deg) contains an object of type line. This object represents sys.

The bodeplot command returns a plot handle that you can use to change properties of the plot.

Change the units to Hz.

p = getoptions(h);
p.FreqUnits = 'Hz';
setoptions(h,p)

The x-axis label updates to reflect the change of unit.

For more examples of customizing plots from the command line, see Examples of Customizing Plots from the Command Line.

Obtaining Plot Handles

To programmatically interact with response plot, you need the plot handle. This handle is an identifier to the response plot object. Because the Control System Toolbox plotting commands, bode, rlocus, etc., all use the plot handle internally, this API provides a set of commands that explicitly return the handle to your response plot. These functions all end with "plot," which makes them easy to identify. This table lists the functions.

Functions That Return the Plot Handle

Function	Plot
`bodeplot`	Bode magnitude and phase
`hsvplot`	Hankel singular values
`impulseplot`	Impulse response
`initialplot`	Initial condition
`iopzplot`	Pole/zero maps for input/output pairs
`lsimplot`	Time response to arbitrary inputs
`nicholsplot`	Nichols chart
`nyquistplot`	Nyquist
`pzplot`	Pole/zero
`rlocusplot`	Root locus
`sigmaplot`	Singular values of the frequency response
`stepplot`	Step response

To get a plot handle for any response plot, use the functions from the table. For example,

h = bodeplot(sys)

returns plot handle h (it also renders the Bode plot). Once you have this handle, you can modify the plot properties using the setoptions and getoptions methods of the plot object, in this case, a Bode plot handle.

Obtaining Plot Options Handles

Overview of Plot Options Handles

Once you have the plot handle, you need the plot options handle, which is an identifier for all the settable plot properties for a given response plot. There are two ways to create a plot options handle:

Retrieving a Handle — Use getoptions to get the handle.
Creating a Handle — Use <responseplot>options to instantiate a handle. See Functions for Creating Plot Options Handles for a complete list.

Retrieving a Handle

The getoptions function retrieves a plot options handle from a plot handle.

p=getoptions(h) % Returns plot options handle p for plot handle h.

If you specify a property name as an input argument, getoptions returns the property value associated with the property name.

property_value=getoptions(h,PropertyName) % Returns a property 
                                          % value.

Creating a Handle

You can create a default plot options handle by using functions in the form of

<responseplot>options

For example,

p=bodeoptions;

instantiates a handle for Bode plots. See Properties and Values Reference for a list of default values.

If you want to set the default values to the Control System Toolbox default values, pass cstprefs to the function. For example,

p = bodeoptions('cstprefs');

set the Bode plot property/value pairs to the Control System Toolbox default values.

This table lists the functions that create a plot options handle.

Functions for Creating Plot Options Handles

Function	Type of Plot Options Handle Created
`bodeoptions`	Bode phase and magnitude
`hsvoptions`	Hankel singular values
`nicholsoptions`	Nichols plot
`nyquistoptions`	Nyquist plot
`pzoptions`	Pole/zero plot
`sigmaoptions`	Sigma (singular values) plot
`timeoptions`	Time response (impulse, step, etc.)

Which Properties Can You Modify?

Use

help <responseplot>options

to see a list of available property value pairs that you can modify. For example,

help bodeoptions

You can modify any of these parameters using setoptions. The next topic provides examples of modifying various response plots.

See Properties and Values Reference for a complete list of property/value pairs for response plots.

Examples of Customizing Plots from the Command Line

Manipulating Plot Options Handles

There are two fundamental ways to manipulate plot option handles:

Dot notation — Treat the handle like a MATLAB structure.
Property value pairs — Specify property/value pairs explicitly as input arguments to setoptions.

For some examples, both dot notation and property/value pairs approaches are shown. For all examples, use

sys = tf(1,[1 1]);

Changing Plot Units

Change the frequency units of a Bode plot from rad/s to Hz. To do so, extract the options p from the plot handle, edit the options, and assign them back to the plot.

h = bodeplot(sys);
p = getoptions(h); 
p.FreqUnits = 'Hz'; 
setoptions(h,p)

Alternatively, instead of extracting p, set the options of h directly.

setoptions(h,'FreqUnits','Hz')

Create Plots Using Existing Plot Options Handle

You can use an existing plot options handle to customize a second plot:

h1 = bodeplot(sys);
p1 = getoptions(h1);
h2 = bodeplot(sys,p1);

h1 = bodeplot(sys);
h2 = bodeplot(sys2);
setoptions(h2,getoptions(h1))

Creating a Default Plot Options Handle

Instantiate a plot options handle with this code.

p = bodeoptions;

Change the frequency units and apply the changes to sys.

p.FreqUnits ='Hz';
h = bodeplot(sys,p);

Using Dot Notation Like a Structure

You can always use dot notation to assign values to properties, and change multiple plot properties at once.

h1 = bodeplot(sys);
p1 = getoptions(h1);
p1.FreqUnits = 'Hz';
p1.Title.String  =  'My Title';
setoptions(h1,p1)

Setting Property Pairs in setoptions

Instead of using dot notation, specify frequency units as property/value pairs in setoptions.

h1 = bodeplot(sys)
setoptions(h1,'FreqUnits','Hz')

Verify that the units have changed from rad/s to Hz.

getoptions(h1,'FreqUnits') % Returns frequency units for h1.

ans =

Hz

Properties and Values Reference

Property/Value Pairs Common to All Response Plots

The following tables discuss property/value pairs common to all response plots.

Title

Property	Default Value	Description
`Title.String`	none	Plot title, such as `'My Response Plot'`.
`Title.FontSize`	8	`Double`
`Title.FontWeight`	normal	`[light \| normal \| demi]`
`Title.FontAngle`	normal	`[normal \| italic \| oblique]`
`Title.Color`	[0 0 0]	`1-by-3 RGB vector`

X Label

Property	Default Value	Description
`XLabel.String`	none	X-axis label, such as `'Input Frequency'`.
`Xlabel.FontSize`	8	`Double`
`Xlabel.FontWeight`	normal	`[light \| normal \| demi]`
`XLabel.FontAngle`	normal	`[normal \| italic \| oblique]`
`Xlabel.Color`	[0 0 0]	`1-by-3 RGB vector`

Y Label

Property	Default Value	Description
`YLabel.String`	none	Y-axis label, such as `'Control Signal Magnitude'`.
`Ylabel.FontSize`	8	`Double`
`Ylabel.FontWeight`	normal	`[light \| normal \| demi]`
`YLabel.FontAngle`	normal	`[normal \| italic \| oblique]`
`Ylabel.Color`	[0 0 0]	`1-by-3 RGB vector`

Tick Label

Property	Default Value	Description
`TickLabel.FontSize`	8	`Double`
`TickLabel.FontWeight`	normal	`[light \| normal \| demi]`
`TickLabel.FontAngle`	normal	`[normal \| italic \| oblique]`
`Ticklabel.Color`	[0 0 0]	`1-by-3 RGB vector`

Grid and Axis Limits

Property	Default Value	Description
`grid`	`off`	`[on \| off]`
`Xlim`	`{[]}`	A cell array of 1-by-2 doubles that specifies the x-axis limits when `XLimMode` is set to manual. When `XLim` is scalar, scalar expansion is applied; otherwise the length of the cell array must equal the number of columns (i.e., number of system inputs) for the plot. The 1-by-2 doubles must be a strictly increasing pair `[xmin, xmax]`.
`XLimMode`	`{'auto'}`	A cell array where each entry is either `'auto'` or `'manual'`. These entries specify the x-axis limits mode of the corresponding axis. When `XLimMode` is set to manual the limits are set to the values specified in `XLim`. When `XLim` is scalar, scalar expansion is applied; otherwise the length of the cell array must equal the number of columns (i.e., number of system inputs) for the plot.
`YLim`	`{[]}`	A cell array of 1-by-2 doubles specifies the y-axis limits when `YLimMode` is set to manual. When `YLim` is scalar, scalar expansion is applied; otherwise the length of the cell array must equal the number of rows (i.e., number of system outputs) for the plot. The 1-by-2 doubles must be a strictly increasing pair [`ymin, ymax]`.
`YLimMode`	`{'auto'}`	A cell array where each entry is either `'auto'` or `'manual'`. These entries specify the y-axis limits mode of the corresponding axis. When `YLimMode` is set to manual the limits are set to the values specified in `YLim`. When `YLim` is scalar, scalar expansion is applied; otherwise the length of the cell array must equal the number of rows (i.e., number of system outputs) for the plot.

I/O Grouping

Property	Default Value	Description
`IOGrouping`	none	`[none \| inputs \| outputs \| all]` Specifies input/output groupings for responses.

Property

Default Value

Description

IOGrouping

none

[none | inputs | outputs | all]

Specifies input/output groupings for responses.

Input Labels

Property	Default Value	Description
`InputLabels.FontSize`	8	`Double`
`InputLabels.FontWeight`	normal	`[light \| normal \| demi]`
`InputLabels.FontAngle`	normal	`[normal \| italic \| oblique]`
`InputLabels.Color`	[0 0 0]	`1-by-3 RGB vector`

Output Labels

Property	Default Value	Description
`OutputLabel.FontSize`	8	`Double`
`OutputLabels.FontWeight`	normal	`[light \| normal \| demi]`
`OutputLabels.FontAngle`	normal	`[normal \| italic \| oblique]`
`OutputLabels.Color`	[0 0 0]	`1-by-3 RGB vector`

Input/Output Visible

Property	Default Value	Description
`InputVisible`	{on}	`[on \| off]` A cell array that specifies the visibility of each input channel. If the value is a scalar, scalar expansion is applied.
`OutputVisible`	{on}	`[on \| off]` A cell array that specifies the visibility of each output channel. If the value is a scalar, scalar expansion is applied.

Property

Default Value

Description

InputVisible

{on}

[on | off]

A cell array that specifies the visibility of each input channel. If the value is a scalar, scalar expansion is applied.

OutputVisible

{on}

[on | off]

A cell array that specifies the visibility of each output channel. If the value is a scalar, scalar expansion is applied.

Bode Plots

Property	Default Value	Description
`FreqUnits`	`rad/s`	Available Options `'Hz'` `'rad/s'` `'rpm'` `'kHz'` `'MHz'` `'GHz'` `'rad/nanosecond'` `'rad/microsecond'` `'rad/millisecond'` `'rad/minute'` `'rad/hour'` `'rad/day'` `'rad/week'` `'rad/month'` `'rad/year'` `'cycles/nanosecond'` `'cycles/microsecond'` `'cycles/millisecond'` `'cycles/hour'` `'cycles/day'` `'cycles/week'` `'cycles/month'` `'cycles/year'`
`FreqScale`	`log`	`[linear \| log]`
`MagUnits`	`dB`	`[db \| abs]`
`MagScale`	`linear`	`[linear \| log]`
`PhaseUnits`	`deg`	`[rad \| deg]`
`PhaseWrapping`	`off`	`[on \| off]` When you set `PhaseWrapping` to `'on'`, the plot wraps accumulated phase at the value specified by the `PhaseWrappingBranch` property.
`PhaseWrappingBranch`	–180	`Double` Phase value at which the plot wraps accumulated phase when `PhaseWrapping` is set to `'on'`
`MagVisible`	`on`	`[on \| off]`
`PhaseVisible`	`on`	`[on \| off]`
`MagLowerLimMode`	`auto`	`[auto \| manual]` Enables a manual lower magnitude limit specification by `MagLowerLim`.
`MagLowerLim`	0	`Double` Specifies the lower magnitude limit when `MagLowerLimMode` is set to `manual`.
`PhaseMatching`	`off`	`[on \| off]` Enables adjusting phase effects for phase response.
`PhaseMatchingFreq`	0	`Double`
`PhaseMatchingValue`	0	`Double`

Hankel Singular Values

Property	Default Value	Description
`Yscale`	`linear`	`[linear \| log]`
`AbsTol`	`0`	`Double` See `hsvd` and `stabsep` for details.
`RelTol`	`1*e-08`	`Double` See `hsvd` and `stabsep` for details.
`Offset`	`1*e-08`	`Double` See `hsvd` and `stabsep` for details.

Nichols Plots

Property	Default Value	Description
`FreqUnits`	`rad/s`	Available Options `'Hz'` `'rad/s'` `'rpm'` `'kHz'` `'MHz'` `'GHz'` `'rad/nanosecond'` `'rad/microsecond'` `'rad/millisecond'` `'rad/minute'` `'rad/hour'` `'rad/day'` `'rad/week'` `'rad/month'` `'rad/year'` `'cycles/nanosecond'` `'cycles/microsecond'` `'cycles/millisecond'` `'cycles/hour'` `'cycles/day'` `'cycles/week'` `'cycles/month'` `'cycles/year'`
`MagUnits`	`dB`	`[dB \| abs]`
`PhaseUnits`	`deg`	`[rad \| deg]`
`MagLowerLimMode`	`auto`	`[auto \| manual]`
`MagLowerLim`	`0`	double
`PhaseWrapping`	`off`	`[on \| off]` When you set `PhaseWrapping` to `'on'`, the plot wraps accumulated phase at the value specified by the `PhaseWrappingBranch` property.
`PhaseWrappingBranch`	–180	double Phase value at which the plot wraps accumulated phase when `PhaseWrapping` is set to `'on'`
`PhaseMatching`	off	[on \| off]
`PhaseMatchingFreq`	0	double
`PhaseMatchingValue`	0	double

Nyquist Charts

Property	Default Value	Description
`FreqUnits`	`rad/s`	Available Options `'Hz'` `'rad/s'` `'rpm'` `'kHz'` `'MHz'` `'GHz'` `'rad/nanosecond'` `'rad/microsecond'` `'rad/millisecond'` `'rad/minute'` `'rad/hour'` `'rad/day'` `'rad/week'` `'rad/month'` `'rad/year'` `'cycles/nanosecond'` `'cycles/microsecond'` `'cycles/millisecond'` `'cycles/hour'` `'cycles/day'` `'cycles/week'` `'cycles/month'` `'cycles/year'`
`MagUnits`	`dB`	`[dB \| abs]`
`PhaseUnits`	`deg`	`[rad \| deg]`
`ShowFullContour`	`on`	`[on \| off]`

Pole/Zero Maps

Property	Default Value	Description
`FreqUnits`	`rad/s`	Available Options `'Hz'` `'rad/s'` `'rpm'` `'kHz'` `'MHz'` `'GHz'` `'rad/nanosecond'` `'rad/microsecond'` `'rad/millisecond'` `'rad/minute'` `'rad/hour'` `'rad/day'` `'rad/week'` `'rad/month'` `'rad/year'` `'cycles/nanosecond'` `'cycles/microsecond'` `'cycles/millisecond'` `'cycles/hour'` `'cycles/day'` `'cycles/week'` `'cycles/month'` `'cycles/year'`
`TimeUnits`	`seconds`	Available Options `'nanoseconds'` `'microseconds'` `'milliseconds'` `'seconds'` `'minutes'` `'hours'` `'days'` `'weeks'` `'months'` `'years'`

Sigma Plots

Property	Default Value	Description
`FreqUnits`	`rad/s`	Available Options `'Hz'` `'rad/s'` `'rpm'` `'kHz'` `'MHz'` `'GHz'` `'rad/nanosecond'` `'rad/microsecond'` `'rad/millisecond'` `'rad/minute'` `'rad/hour'` `'rad/day'` `'rad/week'` `'rad/month'` `'rad/year'` `'cycles/nanosecond'` `'cycles/microsecond'` `'cycles/millisecond'` `'cycles/hour'` `'cycles/day'` `'cycles/week'` `'cycles/month'` `'cycles/year'`
`FreqScale`	`log`	`[linear \| log]`
`MagUnits`	`dB`	`[dB \| abs]`
`MagScale`	`linear`	`[linear \| log]`

Time Response Plots

Property	Default Value	Description
`Normalize`	`off`	`[on \| off]` Normalize the y-scale of all responses in the plot.
`SettleTimeThreshold`	`0.02`	`Double` Specifies the settling time threshold. `0.02 = 2%`.
`RiseTimeLimits`	`[0.1, 0.9]`	`1-by-2 double` Specifies the limits used to define the rise time. `[0.1, 0.9]` is 10% to 90%.
`TimeUnits`	`seconds`	Available Options `'nanoseconds'` `'microseconds'` `'milliseconds'` `'seconds'` `'minutes'` `'hours'` `'days'` `'weeks'` `'months'` `'years'`