Documentation Center

  • Trial Software
  • Product Updates

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 Classes in the MATLAB Language and Graphics Objects in the MATLAB® online documentation for more information.

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.

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

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

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

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.

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

String

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

String

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

String

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

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]

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

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

Property Organization Reference

Was this topic helpful?