nicholsoptions

Create list of Nichols plot options

Description

Use the nicholsoptions command to create a NicholsOptions object to customize your Nichols plot appearance. You can also use the command to override the plot preference settings in the MATLAB^® session in which you create the Nichols plots.

Creation

Syntax

plotoptions = nicholsoptions

plotoptions = nicholsoptions('cstprefs')

Description

plotoptions = nicholsoptions returns a default set of plot options for use with the nicholsplot command. You can use these options to customize the Nichols plot appearance using the command line. This syntax is useful when you want to write a script to generate plots that look the same regardless of the preference settings of the MATLAB session in which you run the script.

plotoptions = nicholsoptions('cstprefs') initializes the plot options with the options you selected in the Control System Toolbox™ Preferences Editor. For more information about the editor, see Toolbox Preferences Editor. This syntax is useful when you want to change a few plot options but otherwise use your default preferences. A script that uses this syntax may generate results that look different when run in a session with different preferences.

Properties

FreqUnits — Frequency units

'rad/s' (default)

Frequency units, specified as one of the following values:

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

MagLowerLimMode — Lower magnitude limit mode

'auto' (default) | 'manual'

Lower magnitude limit mode, specified as either 'auto' or 'manual'.

MagLowerLim — Lower magnitude limit value

'-inf' (default) | scalar

Lower magnitude limit value, specified as a scalar.

PhaseUnits — Phase units

'deg' (default) | 'rad'

Phase units, specified as either 'deg' or 'rad' to change to degrees or radians, respectively.

PhaseWrapping — Enable phase wrapping

'off' (default) | 'on'

Enable phase wrapping, specified as either 'on' or 'off'. When you set PhaseWrapping to 'on', the plot wraps accumulated phase at the value specified by the PhaseWrappingBranch property.

PhaseWrappingBranch — Phase wrapping value

-180 (default) | integer

Phase wrapping value at which the plot wraps accumulated phase when PhaseWrapping is set to 'on'. By default, phase wraps into the interval [-180°,180°].

PhaseMatching — Enable phase matching

'off' (default) | 'on'

Enable phase matching, specified as either 'on' or 'off'. Turning PhaseMatching 'on' matches the phase to the value specified in PhaseMatchingValue at the frequency specified in PhaseMatchingFreq

PhaseMatchingFreq — Phase matching frequency

0 (default) | scalar

Phase matching frequency, specified as a scalar.

PhaseMatchingValue — Phase matching response value

0 (default) | scalar

Phase matching response value, specified as a scalar.

IOGrouping — Grouping of input-output pairs

'none' (default) | 'inputs' | 'outputs' | 'all'

Grouping of input-output (I/O) pairs, specified as one of the following:

• 'none' — No input-output grouping.

• 'inputs' — Group only the inputs.

• 'outputs' — Group only the outputs.

• 'all' — Group all the I/O pairs.

InputLabels — Input label style

structure (default)

Input label style, specified as a structure with the following fields:

• FontSize — Font size, specified as a scalar value greater than zero in point units. The default font size depends on the specific operating system and locale. One point equals 1/72 inch.

• FontWeight — Character thickness, specified as 'Normal' or 'bold'. MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold weight. Therefore, specifying a bold font weight can still result in the normal font weight.

• FontAngle — Character slant, specified as 'Normal' or 'italic'. Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

• Color — Text color, specified as an RGB triplet. The default color is dark grey with the RGB triplet [0.4,0.4,0.4].

• Interpreter — Text interpreter, specified as one of these values:

  • 'tex' — Interpret characters using a subset of TeX markup. This is the default value of Interpreter.

  • 'latex' — Interpret characters using LaTeX markup.

  • 'none' — Display literal characters.

OutputLabels — Output label style

structure (default)

Output label style, specified as a structure with the following fields:

• FontSize — Font size, specified as a scalar value greater than zero in point units. The default font size depends on the specific operating system and locale. One point equals 1/72 inch.

• FontWeight — Character thickness, specified as 'Normal' or 'bold'. MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold weight. Therefore, specifying a bold font weight can still result in the normal font weight.

• FontAngle — Character slant, specified as 'Normal' or 'italic'. Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

• Color — Text color, specified as an RGB triplet. The default color is dark grey with the RGB triplet [0.4,0.4,0.4].

• Interpreter — Text interpreter, specified as one of these values:

  • 'tex' — Interpret characters using a subset of TeX markup. This is the default value of Interpreter.

  • 'latex' — Interpret characters using LaTeX markup.

  • 'none' — Display literal characters.

InputVisible — Toggle display of inputs

{'on'} (default) | {'off'} | cell array

Toggle display of inputs, specified as either {'on'}, {'off'} or a cell array with multiple elements .

OutputVisible — Toggle display of outputs

{'on'} (default) | {'off'} | cell array

Toggle display of outputs, specified as either {'on'}, {'off'} or a cell array with multiple elements.

Title — Title text and style

structure (default)

Title text and style, specified as a structure with the following fields:

• String — Label text, specified as a character vector. By default, the plot is titled 'Nichols Chart'.

• FontSize — Font size, specified as a scalar value greater than zero in point units. The default font size depends on the specific operating system and locale. One point equals 1/72 inch.

• FontWeight — Character thickness, specified as 'Normal' or 'bold'. MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold weight. Therefore, specifying a bold font weight can still result in the normal font weight.

• FontAngle — Character slant, specified as 'Normal' or 'italic'. Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

• Color — Text color, specified as an RGB triplet. The default color is black specified by the RGB triplet [0,0,0].

• Interpreter — Text interpreter, specified as one of these values:

  • 'tex' — Interpret characters using a subset of TeX markup. This is the default value of Interpreter.

  • 'latex' — Interpret characters using LaTeX markup.

  • 'none' — Display literal characters.

XLabel — X-axis label text and style

structure (default)

X-axis label text and style, specified as a structure with the following fields:

• String — Label text, specified as a character vector. By default, the axis is titled based on the frequency units FreqUnits.

• FontSize — Font size, specified as a scalar value greater than zero in point units. The default font size depends on the specific operating system and locale. One point equals 1/72 inch.

• FontWeight — Character thickness, specified as 'Normal' or 'bold'. MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold weight. Therefore, specifying a bold font weight can still result in the normal font weight.

• FontAngle — Character slant, specified as 'Normal' or 'italic'. Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

• Color — Text color, specified as an RGB triplet. The default color is black specified by the RGB triplet [0,0,0].

• Interpreter — Text interpreter, specified as one of these values:

  • 'tex' — Interpret characters using a subset of TeX markup. This is the default value of Interpreter.

  • 'latex' — Interpret characters using LaTeX markup.

  • 'none' — Display literal characters.

YLabel — Y-axis label text and style

structure (default)

Y-axis label text and style, specified as a structure with the following fields:

• String — Label text, specified as a cell array of character vectors. By default, the axis is titled 'Open-Loop Gain (dB)'.

• FontSize — Font size, specified as a scalar value greater than zero in point units. The default font size depends on the specific operating system and locale. One point equals 1/72 inch.

• FontWeight — Character thickness, specified as 'Normal' or 'bold'. MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold weight. Therefore, specifying a bold font weight can still result in the normal font weight.

• FontAngle — Character slant, specified as 'Normal' or 'italic'. Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

• Color — Text color, specified as an RGB triplet. The default color is black specified by the RGB triplet [0,0,0].

• Interpreter — Text interpreter, specified as one of these values:

  • 'tex' — Interpret characters using a subset of TeX markup. This is the default value of Interpreter.

  • 'latex' — Interpret characters using LaTeX markup.

  • 'none' — Display literal characters.

TickLabel — Tick label style

structure (default)

Tick label style, specified as a structure with the following fields:

• FontSize — Font size, specified as a scalar value greater than zero in point units. The default font size depends on the specific operating system and locale. One point equals 1/72 inch.

• FontWeight — Character thickness, specified as 'Normal' or 'bold'. MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold weight. Therefore, specifying a bold font weight can still result in the normal font weight.

• FontAngle — Character slant, specified as 'Normal' or 'italic'. Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

• Color — Text color, specified as an RGB triplet. The default color is black specified by the RGB triplet [0,0,0].

Grid — Toggle grid display

'off' (default) | 'on'

Toggle grid display on the plot, specified as either 'off' or 'on'.

GridColor — Color of the grid lines

[0.15,0.15,0.15] (default) | RGB triplet

Color of the grid lines, specified as an RGB triplet. The default color is light grey specified by the RGB triplet [0.15,0.15,0.15].

XLimMode — X-axis limit selection mode

'auto' (default) | 'manual' | cell array

Selection mode for the x-axis limits, specified as one of these values:

• 'auto' — Enable automatic limit selection, which is based on the total span of the plotted data.

• 'manual' — Manually specify the axis limits. To specify the axis limits, set the XLim property.

YLimMode — Y-axis limit selection mode

'auto' (default) | 'manual' | cell array

Selection mode for the y-axis limits, specified as one of these values:

• 'auto' — Enable automatic limit selection, which is based on the total span of the plotted data.

• 'manual' — Manually specify the axis limits. To specify the axis limits, set the YLim property.

XLim — X-axis limits

'{[1,10]}' (default) | cell array of two-element vector of the form [min,max] | cell array

X-axis limits, specified as a cell array of two-element vector of the form [min,max].

YLim — Y-axis limits

'{[1,10]}' (default) | cell array of two-element vector of the form [min,max] | cell array

Y-axis limits, specified as a cell array of two-element vector of the form [min,max].

Object Functions

nicholsplot

Plot Nichols frequency responses with additional plot customization options

Examples

Customize Nichols Plot using Plot Handle

For this example, use the plot handle to change the title, turn on the grid, and set axis limits.

Generate a random state-space model with 5 states and create the Nichols plot with plot handle h.

rng("default")
sys = rss(5);
h = nicholsplot(sys);

Change the title, enable the grid, and set axis limits. To do so, edit properties of the plot handle, h using setoptions.

Title.String = 'Nichols Frequency Response';
setoptions(h,'Title',Title,'Grid','on', 'XLim',{[-2,4]},'YLim',{[3.3,4.3]});

The Nichols plot automatically updates when you call setoptions.

Alternatively, you can also use the nicholsoptions command to specify the required plot options. First, create an options set based on the toolbox preferences.

plotoptions = nicholsoptions('cstprefs');

Change the desired properties of the options set.

plotoptions.Title.String = 'Nichols Frequency Response';
plotoptions.Grid = 'on';
plotoptions.XLim = {[-2,4]};
plotoptions.YLim = {[3.3,4.3]};
nicholsplot(sys,plotoptions);

You can use the same option set to create multiple Nichols plots with the same customization. Depending on your own toolbox preferences, the plot you obtain might look different from this plot. Only the properties that you set explicitly, in this example Title, Grid, XLim and YLim, override the toolbox preferences.

Custom Nichols Plot Settings Independent of Preferences

For this example, create a Nichols plot that uses 15-point red text for the title. This plot should look the same, regardless of the preferences of the MATLAB session in which it is generated.

First, create a default options set using nicholsoptions.

plotoptions = nicholsoptions;

Next, change the required properties of the options set plotoptions.

plotoptions.Title.FontSize = 15;
plotoptions.Title.Color = [1 0 0];
plotoptions.FreqUnits = 'Hz';
plotoptions.Grid = 'on';

Now, create a Nichols plot using the options set plotoptions.

nicholsplot(tf(1,[1,1]),{0,15},plotoptions);

Because plotoptions begins with a fixed set of options, the plot result is independent of the toolbox preferences of the MATLAB session.

Customized Nichols Plot of Transfer Function

For this example, create a Nichols plot of the following continuous-time SISO dynamic system. Then, turn the grid on and rename the plot.

$$sys(s)=\frac{s^2+0.1s+7.5}{s^4+0.12s^3+9s^2}.$$

Create the transfer function sys.

sys = tf([1 0.1 7.5],[1 0.12 9 0 0]);

Next, create the options set using nicholsoptions and change the required plot properties.

plotoptions = nicholsoptions;
plotoptions.Grid = 'on';
plotoptions.Title.String = 'Nichols Plot of Transfer Function';

Now, create the Nichols plot with the custom option set plotoptions.

nicholsplot(sys,plotoptions)

nicholsplot automatically selects the plot range based on the system dynamics.

Nichols Response of Identified Parametric and Nonparametric Models

For this example, compare the Nichols response of a parametric model, identified from input/output data, to a non-parametric model identified using the same data. Identify parametric and non-parametric models based on the data.

Load the data and create the parametric and non-parametric models using tfest and spa, respectively.

load iddata2 z2;
w = linspace(0,10*pi,128);
sys_np = spa(z2,[],w);
sys_p = tfest(z2,2);

spa and tfest require System Identification Toolbox™ software. The model sys_np is a non-parametric identified model while, sys_p is a parametric identified model.

Create an options set to turn phase matching and the grid on. Then, create a Nichols plot that includes both systems using this options set.

plotoptions = nicholsoptions;  
plotoptions.PhaseMatching = 'on';
plotoptions.Grid = 'on';
plotoptions.XLim = {[-240,0]};
h = nicholsplot(sys_p,'r.-.',sys_np,'b.-.',w,plotoptions);
legend('Parametric Model','Non-Parametric model');

Set Options for Nichols Plot

Create an options set, and set the phase units and grid option.

P = nicholsoptions; 
P.PhaseUnits = 'rad';
P.Grid = 'on';

Use the options set to generate a Nichols plot. Not the phase units and grid in the plot.

h = nicholsplot(tf(1,[1,.2,1,0]),P);

Version History

Introduced in R2008a