Main Content

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:

  1. 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.

  2. 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.

  3. 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

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)

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 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

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);

or

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

PropertyDefault 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

PropertyDefault 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.

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.

Bode Plots

Property

Default Value

Description

FreqUnits

rad/s

 Available Options

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

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

MagUnits

dB

[dB | abs]

PhaseUnits

deg

[rad | deg]

ShowFullContour

on

[on | off]

Pole/Zero Maps

Property

Default Value

Description

FreqUnits

rad/s

 Available Options

TimeUnitsseconds

 Available Options

Sigma Plots

Property

Default Value

Description

FreqUnits

rad/s

 Available Options

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