Customizing Response Plots from the Command Line :: Customizing Response Plot Properties (Control System Toolbox™)

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 Handle Graphics^® and object-oriented concepts, namely, classes, objects, and Handle Graphics handles. See MATLAB Classes and Handle Graphics Objects in the MATLAB online documentation for more information.

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.

Example of Changing Bode Plot Units from the Command Line

You can change of the following plot from rad/s to Hz.

s = tf('s');
sys= 1/(s+1);
h= bodeplot(sys);

To change the units to Hz, type the following:

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

The units for the x-axis are now in Hz.

Note You can also change the plot units to Hz using property/value pairs by typing

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

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

BODEOPTIONS Create a BodePlotOptions object
 
    P = BODEOPTIONS returns the default BodePlotOptions object.
 
    P = BODEOPTIONS('cstprefs') initializes the BodePlotOptions 
        object
    with the Control System Toolbox preferences.
    
    Available options include:
       Title, XLabel, YLabel         Label text and style
       TickLabel                     Tick label style
       Grid   [off|on]               Show or hide the grid 
       XlimMode, YlimMode            Limit modes
       Xlim, Ylim                    Axes limits
       IOGrouping                    Grouping of input-output 
                                     pairs
          [none|inputs|output|all] 
       InputLabels, OutputLabels     Input and output label 
                                     styles
       InputVisible, OutputVisible   Visibility of input and 
                                     output channels
       FreqUnits [Hz|rad/s]          Frequency Units
       FreqScale [linear|log]        Frequency Scale
       MagUnits [dB|abs]             Magnitude Units
       MagScale [linear|log]         Magnitude Scale
       MagVisible [on|off]           Magnitude plot visibility
       MagLowerLimMode [auto|manual] Enables a lower magnitude 
                                     limit
       MagLowerLim                  Specifies the lower  
                                     magnitude limit
       PhaseUnits [deg|rad]          Phase units
       PhaseVisible [on|off]         Phase plot visibility
       PhaseWrapping [on|off]        Enables phase wrapping
       PhaseMatching [on|off]        Enables phase matching 
       PhaseMatchingFreq             Frequency for matching phase
       PhaseMatchingValue            The value to make the phase 
                                     responses close to

You can modify any of these parameters using setoptions. The next section 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])

for the system.

Changing Plot Units

Change the frequency units of a Bode plot from rad/s to Hz.

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

or, for the last three lines, substitute

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.

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	`String`
`Title.FontSize`	8	`Double`
`Title.FontWeight`	normal	`[light \| normal \| demi \| bode]`
`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	`String`
`Xlabel.FontSize`	8	`Double`
`Xlabel.FontWeight`	normal	`[light \| normal \| demi \| bode]`
`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	`String`
`Ylabel.FontSize`	8	`Double`
`Ylabel.FontWeight`	normal	`[light \| normal \| demi \| bode]`
`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 \| demo \| bode]`
`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 of strings `[auto \| manual]` that specifies the x-axis limits mode. When `XLimMode` is set to manual the limits are set to the values specified in `XLim`. When `XLimMode` 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 of strings `[auto \| manual]` that specifies the y-axis limits mode. When `YLimMode` is set to manual the limits are set to the values specified in `YLim`. When `YLimMode` 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 \| bode]`
`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 \| bode]`
`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/sec`	`[rad/sec \| Hz`
`FreqScale`	`log`	`[linear \| log]`
`MagUnits`	`dB`	`[db \| abs]`
`MagScale`	`linear`	`[linear \| log]`
`PhaseUnits`	`deg`	`[rad \| deg]`
`PhaseWrapping`	`off`	`[on \| off]`
`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/sec`	`[rad/sec \| Hz]`
`MagUnits`	`dB`	`[dB \| abs]`
`PhaseUnits`	`deg`	`[rad \| deg]`
`MagLowerLimMode`	`auto`	`[auto \| manual]`
`MagLowerLim`	`0`	double
`PhaseMatching`	off	[on \| off]
`PhaseMatchingFreq`	0	Double
`PhaseMatchingValue`	0	Double

Nyquist Charts

Property	Default Value	Description
`FreqUnits`	`rad/sec`	`[rad/sec \| Hz]`
`MagUnits`	`dB`	`[dB \| abs]`
`PhaseUnits`	`deg`	`[rad \| deg]`
`ShowFullContour`	`on`	`[on \| off]`

Pole/Zero Maps

Property	Default Value	Description
`FreqUnits`	`rad/sec`	`[rad/sec \| Hz]`

Sigma Plots

Property	Default Value	Description
`FreqUnits`	`rad/sec`	`[rad/sec \| Hz]`
`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%.

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