nyquistoptions

Create list of Nyquist plot options

Description

Use the nyquistoptions command to create a NyquistOptions object to customize Nyquist plot appearance. Use this object to customize the appearance of a Nyquist plot created using nyquistplot and override the plot preferences for the MATLAB^® session in which you create the Nyquist plot.

The options you specify for a NyquistOptions object correspond to properties of a NyquistPlot chart object.

Creation

Syntax

plotoptions = nyquistoptions

plotoptions = nyquistoptions("cstprefs")

Description

plotoptions = nyquistoptions returns a default set of plot options for use with nyquist. You can use these options to customize the Nyquist 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 = nyquistoptions("cstprefs") initializes the plot options with the options you selected in the Control System Toolbox™ and System Identification Toolbox™ Preferences Editor. For more information about the editor, see Specify Toolbox Preferences for Linear Analysis Plots. 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 can generate results that look different when run in a session with different preferences.

Properties

Response

ShowFullContour — Option to show response for negative frequencies

'on' (default) | 'off'

Option to show response for negative frequencies, specified as either 'on' or 'off'.

This option corresponds to the ShowNegativeFrequencies property of the chart object.

ConfidenceRegionNumberSD — Number of standard deviations to use to plot the confidence region

1 (default) | scalar

Number of standard deviations to use to plot the confidence region, specified as a scalar. This option is applicable to identified models only.

This option corresponds to the Characteristics.ConfidenceRegion.NumberOfStandardDeviations property of the chart object.

Dependencies

This option is supported only for identified models, which require System Identification Toolbox software.

ConfidenceRegionDisplaySpacing — Frequency spacing of confidence ellipses

5 (default) | positive integer

Frequency spacing of confidence ellipses used to plot the confidence region, specified as a scalar. The default value is 5, which means the confidence ellipses are shown at every 5th frequency sample.

Dependencies

This option is supported only for identified models, which require System Identification Toolbox software.

Units

FreqUnits — Frequency units

'rad/s' (default) | 'Hz' | 'rpm' | 'auto' | ...

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'

You can also specify 'auto' which uses frequency 'rad/TimeUnit', where TimeUnit is the TimeUnit property of the input system.

This option corresponds to the FrequencyUnit property of the chart object.

MagUnits — Magnitude units

'dB' (default) | 'abs'

Magnitude units, specified as one of the following:

• 'dB' — Decibels

• 'abs' — Absolute value

This option corresponds to the MagnitudeUnit property of the chart object.

PhaseUnits — Phase units

'deg' (default) | 'rad'

Phase units, specified as one of the following:

• 'deg' — Degrees

• 'rad' — Radians

This option corresponds to the PhaseUnit property of the chart object.

Inputs and Outputs

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' — Do not group inputs or outputs.

• 'inputs' — Group only inputs.

• 'outputs' — Group only outputs.

• 'all' — Group all input-output pairs.

This option corresponds to the IOGrouping property of the chart object.

InputLabels — Input label style

structure

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.

This option corresponds to the InputLabels property of the chart object.

OutputLabels — Output label style

structure

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.

This option corresponds to the OutputLabels property of the chart object.

InputVisible — Option to display inputs

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

Option to display inputs, specified as {'on'}, {'off'}, or a cell array with multiple elements.

This option corresponds to the InputVisible property of the chart object.

OutputVisible — Option to display outputs

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

Option to display outputs, specified as {'on'}, {'off'}, or a cell array with multiple elements.

This option corresponds to the OutputVisible property of the chart object.

Title and Axis Labels

Title — Title text and style

structure

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 'Bode Diagram'.

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

This option corresponds to the Title property of the chart object.

XLabel — X-axis label text and style

structure

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.

This option corresponds to the XLabel property of the chart object.

YLabel — Y-axis label text and style

structure

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 label is a 1x2 cell array with 'Magnitude' and 'Phase'.

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

This option corresponds to the YLabel property of the chart object.

TickLabel — Tick label style

structure

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

Grid — Toggle grid display

'off' (default) | 'on'

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

This option corresponds to the GridVisible property of the chart object.

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

Axis Limits

XLimMode — X-axis limit selection mode

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

X-axis limit selection mode, specified as one of the following 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 option.

This option corresponds to the XLimitsMode property of the chart object.

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

This option corresponds to the YLimitsMode property of the chart object.

XLim — X-axis limits

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

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

This option corresponds to the XLimits property of the chart object.

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

This option corresponds to the YLimits property of the chart object.

Object Functions

nyquistplot

Plot Nyquist response of dynamic system

Examples

Customize Nyquist Plot

For this example, use the plot handle to change the phase units to radians and to turn the grid on.

Generate a random state-space model with 5 states and create the Nyquist diagram with chart object np.

rng("default")
sys = rss(5);
np = nyquistplot(sys);

Change the phase units to radians and turn on the grid. To do so, edit properties of the chart object.

np.PhaseUnit = "rad";
grid on;

The Nyquist plot automatically updates when you modify the chart object.

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

plotoptions = nyquistoptions("cstprefs");

Change properties of the options set by setting the phase units to radians and enabling the grid.

plotoptions.PhaseUnits = "rad";
plotoptions.Grid = "on";
nyquistplot(sys,plotoptions);

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 PhaseUnits and Grid, override the toolbox preferences.

Nyquist Plot of Identified Models with Confidence Regions at Selected Points

Compare the frequency responses of identified state-space models of order 2 and 6 along with their 1-std confidence regions rendered at every 50th frequency sample.

Load the identified model data and estimate the state-space models using n4sid. Then, plot the Nyquist diagram.

load iddata1
sys1 = n4sid(z1,2); 
sys2 = n4sid(z1,6);
w = linspace(10,10*pi,256);
np = nyquistplot(sys1,sys2,w);

Both models produce about 76% fit to data. However, sys2 shows higher uncertainty in its frequency response, especially close to Nyquist frequency as shown by the plot. To see this, show the confidence region at a subset of the points at which the Nyquist response is displayed.

np.ShowNegativeFrequencies = "off";
np.Characteristics.ConfidenceRegion.DisplaySampling = 50;
np.Characteristics.ConfidenceRegion.Visible = "on";

Alternatively, to turn on the confidence region display, right-click the plot and select Characteristics > Confidence Region.

Version History

Introduced in R2011a