Main Content

sigmaoptions

Sigma plot options

    Description

    Use the sigmaoptions command to create a SigmaOptions object to customize your sigma plot appearance. Use this object to customize the appearance of a Bode plot created using sigmaplot and override the plot preferences for the MATLAB® session in which you create the sigma plot.

    The options you specify for a SigmaOptions object correspond to properties of a SigmaPlot chart object.

    Creation

    Description

    plotoptions = sigmaoptions returns a default set of plot options for use with sigmaplot. You can use these options to customize sigma 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.

    example

    plotoptions = sigmaoptions("cstprefs") initializes the plot options with the options you selected in the Control System 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 might generate results that look different when run in a session with different preferences.

    example

    Properties

    expand all

    Units and Scaling

    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.

    Frequency scale, specified as either 'log' or 'linear'.

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

    Magnitude units, specified as one of the following:

    • 'dB' — Decibels

    • 'abs' — Absolute value

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

    Magnitude scale, specified as either 'log' or 'linear'.

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

    Title and Axis Labels

    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.

    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.

    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.

    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 on the plot, specified as either 'off' or 'on'.

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

    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

    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.

    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.

    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.

    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

    sigmaplotPlot singular values for frequency response of dynamic system

    Examples

    collapse all

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

    Generate a random state-space model with 5 states and create the sigma plot with chart object sp.

    rng("default")
    sys = rss(5);
    sp = sigmaplot(sys);

    MATLAB figure

    Change the units to Hz and turn on the grid.

    sp.FrequencyUnit = "Hz";
    grid on

    MATLAB figure

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

    p = sigmaoptions('cstprefs');

    Change properties of the options set by setting the frequency units to Hz and enable the grid.

    p.FreqUnits = 'Hz';
    p.Grid = 'on';
    sigmaplot(sys,p);

    MATLAB figure

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

    For this example, create a sigma 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 sigmaoptions.

    plotoptions = sigmaoptions;

    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 sigma plot using the options set plotoptions.

    h = sigmaplot(tf(1,[1,1]),plotoptions);

    MATLAB figure

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

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

    sys(s)=s2+0.1s+7.5s4+0.12s3+9s2.Continuous-time SISO dynamic system

    Create the transfer function sys.

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

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

    plotoptions = sigmaoptions;
    plotoptions.Grid = 'on';
    plotoptions.FreqScale = 'linear';
    plotoptions.Title.String = 'Singular Value Plot of Transfer Function';

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

    h = sigmaplot(sys,plotoptions);

    MATLAB figure

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

    For this example, compare the SV for the frequencies 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 the grid on. Then, create a sigma plot that includes both systems using this options set.

    plotoptions = sigmaoptions;  
    plotoptions.Grid = 'on';
    h = sigmaplot(sys_p,'b--',sys_np,'r--',w,plotoptions);
    legend('Parametric Model','Non-Parametric model');

    MATLAB figure

    Consider the following two-input, two-output dynamic system.

    H(s)=[03ss2+s+10s+1s+52s+6].

    Plot the singular value responses of H(s) and I + H(s). Set appropriate titles using the plot option set.

    H = [0, tf([3 0],[1 1 10]) ; tf([1 1],[1 5]), tf(2,[1 6])];
    opts1 = sigmaoptions;
    opts1.Grid = 'on';
    opts1.Title.String = 'Singular Value Plot of H(s)';
    h1 = sigmaplot(H,opts1);

    Use input 2 to plot the modified SV of type, I + H(s).

    opts2 = sigmaoptions;
    opts2.Grid = 'on';
    opts2.Title.String = 'Singular Value Plot of I+H(s)';
    h2 = sigmaplot(H,[],2,opts2);

    MATLAB figure

    Version History

    Introduced in R2008a