Base Graphical Functions

activeregion

Region associated with an ID.

Syntax

activeregion(xmin, xmax, ymin, ymax, id)
activeregion(X, Y, id)

Description

The command activeregion defines invisible regions with an ID for interactive manipulations in Sysquake. Contrary to most other graphical objects, a hit is detected when the mouse is inside the region, not close like with points and lines.

activeregion(xmin,xmax,ymin,ymax,id) defines a rectangular shape.

activeregion(X,Y,id) defines a polygonal shape. The start and end points do not have to be the same; the shape is closed automatically.

Example

Rectangular button. If an ID was given to plot without activeregion, a hit would be detected when the mouse is close to any of the four corners; with activeregion, a hit is detected when the mouse is inside the rectangle.

plot([50, 70, 70, 50, 50], [10, 10, 30, 30, 10]);
activeregion(50, 70, 10, 30, id=1);

altscale

Alternative y scale for 2D plots.

Syntax

altscale(b)

Description

altscale(b) selects an alternative y scale whose axis and labels are displayed on the right of the rectangular frame of 2D plots. Its input argument is a logical value which is true to select the alternative scale and false to revert to the primary scale.

Example

bar(1:5, rand(1, 5));
altscale(true);
plot(1:5, 3 * rand(1,5), 'R');
label('', 'y1', 'y2');
legend('y1\ny2', 'bfR');

area

Area plot.

Syntax

area(y)
area(x, y)
area(x, y, y0)
area(..., style)
area(..., style, id)

Description

With column vector arguments, area(x,y) displays the area between the horizontal axis y=0 and the points given by x and y. When the second argument is an array with as many rows as elements in x, area(x,Y) displays the contribution of each column of Y, summed along each row. When both the first and second arguments are arrays of the same size, area(X,Y) displays independent area plots for corresponding columns of X and Y without summation.

With a single argument, area(y) takes integers 1, 2, ..., n for the horizontal coordinates.

With a third argument, area(x,y,y0) displays the area between the horizontal line y=y0 and values defined by y.

The optional arguments style and id have their usual meaning. area uses default colors when argument style is missing.

Examples

Red area defined by points (1,2), (2,3), (3,1), and (5,2) above y=0; on top of it, blue area defined by points (1,2+1), (2,3+2) etc.

area([1;2;3;5],[2,1;3,2;1,5;2,1], 0, 'rb');

Two separate areas above y=0.2 defined by points (1,2), (2,3), (3,1), (5,2); and (6,1), (7,2), (8,5), and (9,1).

area([1,6;2,7;3,8;5,9],[2,1;3,2;1,5;2,1], 0.2, 'rb');

bar

Vertical bar plot.

Syntax

bar(y)
bar(x, y)
bar(x, y, w)
bar(..., kind)
bar(..., kind, style)
bar(......, id)

Description

bar(x,y) plots the columns of y as vertical bars centered around the corresponding value in x. If x is not specified, its default value is 1:size(y,2).

bar(x,y,w), where w is scalar, specifies the relative width of each bar with respect to the horizontal distance between the bars; with values smaller than 1, bars are separated with a gap, while with values larger than 1, bars overlap. If w is a vector of two components [w1,w2], w1 corresponds to the relative width of each bar in a group (columns of y), and w2 to the relative width of each group. Default values, used if w is missing or is the empty matrix [], is 0.8 for both w1 and w2.

bar(...,kind), where kind is a string, specifies the kind of bar plot. The following values are recognized:

`'grouped'`	Columns of `y` are grouped horizontally (default)
`'stacked'`	Columns of `y` are stacked vertically
`'interval'`	Bars defined with min and max val.

With 'interval', intervals are defined by two consecutive rows of y, which must have an even number of rows.

The optional arguments style and id have their usual meaning. bar uses default colors when argument style is missing.

Examples

Simple bar plot:

bar([2,4,3,6;3,5,4,1]);

Stacked bar plot:

bar(1:4, magic(4), [], 'stacked');

Interval plot:

bar(1:4, [2,4,3,1;5,6,4,6], [], 'interval');

barh

Horizontal bar plot.

Syntax

barh(x)
barh(y, x)
barh(y, x, w)
barh(..., kind)
barh(..., kind, style)
barh(..., id)

Description

barh plots a bar plot with horizontal bars. Please see bar for a description of its behavior and arguments.

Examples

Simple horizontal bar plot:

barh([2,4,3,6;3,5,4,1]);

Stacked horizontal bar plot:

barh(1:4, magic(4), [], 'stacked');

Horizontal interval plot:

barh(1:4, [2,4,3,1;5,6,4,6], [], 'interval');

circle

Add circles to the figure.

Syntax

circle(x,y,r)
circle(x,y,r,style)
circle(x,y,r,style,id)

Description

circle(x,y,r) draws a circle of radius r centered at (x,y). The arguments can be vectors to display several circles. Their dimensions must match; scalar numbers are repeated if necessary. The optional fourth and fifth arguments are the style and object ID (cf. their description above).

In mouse handlers, _x0 and _y0 correspond to the projection of the mouse click onto the circle; _nb is the index of the circle in x, y and r, and _ix is empty.

Circles are displayed as circles only if the scales along the x and y axes are the same, and linear. With different linear scales, circles are displayed as ellipses. With logarithmic scales, they are not displayed.

Examples

circle(1, 2, 5, 'r', 1);
circle(zeros(10,1), zeros(10, 1), 1:10);

colormap

Current colormap from scalar to RGB.

Syntax

colormap(clut)
clut = colormap

Description

Command colormap(clut) changes the color mapping from scalar values to RGB values used by commands such as pcolor, image and surf.

Colormaps are arrays of size n-by-3. Each row corresponds to a color; the first column is the intensity of red from 0 (no red component) to 1 (maximum intensity), the second column the intensity of green, and the third column the intensity of blue. Input values are mapped uniformly to one of the discrete color entries, 0 to the first row and 1 to the last row.

With an input argument, colormap(clut) sets the colormap to clut. With an output argument, colormap returns the current colormap.

contour

Level curves.

Syntax

contour(z)
contour(z, [xmin, xmax, ymin, ymax])
contour(z, [xmin, xmax, ymin, ymax], levels)
contour(z, [xmin, xmax, ymin, ymax], levels, style)

Description

contour(z) plots seven contour lines corresponding to the surface whose samples at equidistant points 1:size(z,2) in the x direction and 1:size(z,1) on the y direction are given by z. Contour lines are at equidistant levels. With a second non-empty argument [xmin, xmax, ymin, ymax], the samples are at equidistant points between xmin and xmax in the x direction and between ymin and ymax in the y direction.

The optional third argument levels, if non-empty, gives the number of contour lines if it is a scalar or the levels themselves if it is a vector.

The optional fourth argument is the style of each line, from the minimum to the maximum level (styles are recycled if necessary). The default style is 'kbrmgcy'.

When the style is f for a filled region, the corresponding level is filled on the side with a lower value of z. If the style argument is the single character 'f', all levels are filled with the default colors. Regions with a value of z smaller than the lowest level are left transparent; an explicit lower level should be specified to fill the whole rectangle.

Examples

A function is evaluated over a grid of two variables x and y, and is drawn with contour:

(x, y) = meshgrid(-2 + (0:40) / 10);
z = exp(-((x-0.2).^2+(y+0.3).^2)) ...
      - exp(-((x+0.5).^2+(y-0.1).^2)) + 0.1 * x;
scale equal;
contour(z, [-1,1,-1,1]);

Filled contours:

u = -2 + (0:80) / 20;
x = repmat(u, 81, 1);
y = x';
z = exp(-((x-0.2).^2+(y+0.3).^2)) ...
    - exp(-((x+0.5).^2+(y-0.1).^2)) ...
    + 0.1 * x ...
    + 0.5 * sin(y);
levels = -1:0.2:1;
scale equal;
contour(z, [-1,1,-1,1], levels, 'f');

figurestyle

Figure style.

Syntax

figurestyle(name, style)
style = figurestyle(name)

Description

figurestyle sets or gets the style of figures. The same settings apply to all subplots; settings for specific subplots are changed with subplotstyle. Styles are set or got separately for each feature of the graphics (plot background, drawing, title, etc.). They are specified with the same structures as plotset or fontset (except for 'plotmargin'), or with the corresponding named arguments.

The first argument, name, is the name of the style feature:

Name	Type	Feature
`'controlbg'`	`plotset`	Control background
`'controlfont'`	`fontset`	Font for controls
`'draw'`	`plotset`	Default line or mark plots
`'figfont'`	`fontset`	Font for text in figure
`'frame'`	`plotset`	Plot or subplot frame and ticks
`'grid'`	`plotset`	Special grids such as `hgrid`
`'hilight'`	`plotset`	Hilighted subplot frame for interactive figures
`'tickfont'`	`fontset`	Font for tick labels
`'labelfont'`	`fontset`	Font for axis labels
`'legend'`	`plotset`	Legend box (frame and background)
`'legendfont'`	`fontset`	Font for legend text
`'plotbg'`	`plotset`	Plot or subplot background
`'plotmargin'`		Plot margin size
`'scaleoverview'`	`plotset`	Scale overview rectangle
`'titlefont'`	`fontset`	Font used for plot or subplot titles
`'winbg'`	`plotset`	Background around plots or subplots
`'xygrid'`	`plotset`	Rectangular grid (or polar in polar plots)

figurestyle(name,style) changes the specified style. The style can be specified with a style structure, like what is returned by plotset or fontset, or with named arguments. Settings which are not specified keep their default values.

With a single argument, figurestyle(name) returned the current specified style.

The value for 'plotmargin' is a structure which describes the margin width around plots or subplots. It contains the following fields:

Name	Value
`Left`	left margin in multiple of a digit width
`Right`	right margin in multiple of a digit width
`Top`	top margin in multiple of line height
`Bottom`	bottom margin in multiple of line height
`CenteredLabelWidth`	see below
`CenteredLabelHeight`	see below
`FixedControlVPos`	see below

The fonts the widths are based on are the title font for Top, and the label font for the other fields. When an alternative y scale is used with altscale, the width of the right margin is based on Left instead of Right.

If field CenteredLabelWidth is larger than 0, it specifies the width of an additional margin (in multiple of a digit width) where the label of the Y axis is displayed, centered vertically. If field CenteredLabelHeight is larger than 0, it specifies the height of an additional bottom margin (in multiple of a line height) where the label of the X axis is displayed, centered horizontally. The default location of axis labels is at the end of the tick labels.

If field FixedControlVPos is false, controls (buttons, sliders etc.) are centered vertically in the subplot content area, or can be scrolled vertically by the user if they exceed the available space. If it is true, controls are aligned at the top and cannot be scrolled.

Considered as a whole, styles should be chosen such that they provide enough contrast to make all features visible. In particular, the font color should be changed when a dark background is selected. Some combinations, such as red on green, are difficult to distinguish for color-blind persons.

In Sysquake, figurestyle should not be used in figure draw handlers, because it applies to all subplots. It should typically be placed in init or menu handlers. To change the default figure styles which are used in all figures unless they are overridden by figurestyle, defaultstyle should be called instead.

Example

Blue appearance with different dark shades for the backgrounds, and large fonts.

figurestyle('winbg', FillColor='#002');
figurestyle('plotbg', FillColor='#005');
figurestyle('legend', FillColor='#00a');
figurestyle('draw', Size=18, LineWidth=4, Color='#88f');
figurestyle('grid', Size=18, LineWidth=2, Color='#66c');
figurestyle('xygrid', LineWidth=2, Color='#66c');
figurestyle('frame', LineWidth=3, Color='#44f');
figurestyle('figfont', Size=20, Color='white');
figurestyle('controlfont', Size=20, Color='white');
figurestyle('legendfont', Size=20, Color='white');
figurestyle('titlefont', Size=32, Bold=true, Color='white');
figurestyle('tickfont', Size=18, Color='white');
figurestyle('labelfont', Size=18, Color='white');

fontset

Options for fonts.

Syntax

options = fontset
options = fontset(name1=value1, ...)
options = fontset(name1, value1, ...)
options = fontset(options0, name1, value1, ...)

Description

fontset(name1,value1,...) creates the font description used by text. Options are specified with name/value pairs, where the name is a string which must match exactly the names in the table below. Case is significant. Alternatively, options can be given with named arguments. Options which are not specified have a default value. The result is a structure whose fields correspond to each option. Without any input argument, fontset creates a structure with all the default options. Options can also be passed directly to text or math as named arguments.

When its first input argument is a structure, fontset adds or changes fields which correspond to the name/value pairs which follow.

Here is the list of permissible options (empty arrays mean "automatic"):

Name	Default	Meaning
`Font`	`''`	font name
`Size`	`10`	character size in points
`Bold`	`false`	true for bold font
`Italic`	`false`	true for italic font
`Underline`	`false`	true for underline characters
`Color`	`[0,0,0]`	text color

The default font is used if the font name is not recognized. The color is specified as an empty array (black), a scalar (gray) or a 3-element vector (RGB) of class double (0=black, 1=maximum brightness) or uint8 (0=black, 255=maximum brightness).

Examples

Default font:

fontset
  Font: ''
  Size: 10
  Bold: false
  Italic: false
  Underline: false
  Color: real 1x3

Named argument directly in text:

text(0, 0, 'Text', Font='Times', Italic=true, Bold=true)

fplot

Function plot.

Syntax

fplot(fun)
fplot(fun, limits)
fplot(fun, limits, style)
fplot(fun, limits, style, id)
fplot(fun, limits, style, id, p1, p2, ...)

Description

Command fplot(fun,limits) plots function fun, specified by its name as a string, a function reference, or an inline or anonymous function. The function is plotted for x between limit(1) and limit(2); the default limits are [-5,5].

The optional third and fourth arguments are the same as for all graphical commands.

Remaining input arguments of fplot, if any, are given as additional input arguments to function fun. They permit to parameterize the function. For example fplot('fun',[0,10],'',-1,2,5) calls fun as y=fun(x,2,5) and displays its value for x between 0 and 10.

Examples

Plot a sine:

fplot(@sin);

Plot (x+0.3)^2+a*exp(-3*x^2) in red for x between -2 and 3 with a=7.2 and an identifier of 1:

fun = inline(...
  'function y=f(x,a); y=(x+0.3)^2+a*exp(-3*x^2);');
fplot(fun, [-2,3], 'r', 1, 7.2);

Same plot with an anonymous function:

a = 7.2;
fplot(@(x) (x+0.3)^2+a*exp(-3*x^2), [-2,3], 'r', 1);

image

Raster RGB or grayscale image.

Syntax

image(gray)
image(red, green, blue)
image(rgb)
image(..., [xmin, xmax, ymin, ymax])
image(..., mode)
image(..., id)

Description

image displays a raster image (an image defined by a rectangular array of patches of colors called pixels). The raster image can be either grayscale or color. A grayscale image is defined by a double matrix of pixel values in the range 0 (black) to 1 (white), by a uint8 matrix in the range 0 (black) to 255 (white), or by a uint16 matrix in the range 0 (black) to 65535 (white). A color image is defined by three matrices of equal size, corresponding to the red, green, and blue components, or by an array with three planes along the 3rd dimension. Each component is defined between 0 (black) to 1 (maximum intensity) with double values, between 0 (black) to 255 (maximum intensity) with uint8 values, or between 0 (black) and 65535 (maximum intensity) with uint16 values. If a colormap has been defined, grayscale image rendering uses it.

The position is defined by the the minimum and maximum coordinates along the horizontal and vertical axes. The raster image is scaled to fit. The first line of the matrix or matrices is displayed at the top. The position can be specified by an argument [xmin,xmax,ymin,ymax]; by default, it is [0,size(im,2),0,size(im,1)] where im stands for the image array or one of its RGB components.

If mode is 'e', the raster image is scaled down such that each pixel has the same size; otherwise, the specified position is filled with the raster image. You should use 'e' when you want a better quality, but do not add other elements in the figure (such as marks or lines) and do not have interaction with the mouse.

Pixels on the screen are interpolated using the bilinear method if mode is '1', and the bicubic method if mode is '3'.

Examples

Two ways to display a table of 10-by-10 random color cells:

image(rand(10), rand(10), rand(10));
image(rand(10, 10, 3));

A ramp of gray shades:

image(uint8(0:255));

Operator : and function meshgrid can be used to create the x and y coordinates used to display a function z(x,y) as an image.

(X, Y) = meshgrid(-pi:0.1:pi);
Z = cos(X.^2 + Y.^2).^2;
image(Z, [-1,1,-1,1], '3');

label

Plot labels.

Syntax

label(label_x)
label(label_x, label_y)
label(label_x, label_y, label_y2)

Description

label(label_x, label_y) displays labels for the x and y axes. Its arguments are strings. The label for the y axis may be omitted.

When an alternative y scale is used with altscale, its label can be specified with a third argument.

For a dB scale, an additional label [dB] is automatically displayed below the text specified by label_y; it is not displayed if there is no label_y (or an empty label_y). If label_y is a single-space string, it is replaced by [dB] for a dB scale (i.e. [dB] is aligned correctly with the top of the figure).

With plotoption math, labels can contain MathML or LaTeX.

Examples

step(1,[1,2,3,4]);
label('t [s]', 'y [m]');

With literal strings, the command syntax may be more convenient:

label Re Im;

dB scale with only a [dB] label:

scale logdb;
bodemag(1, [1, 2, 3]);
label('', ' ');

legend

Plot legend.

Syntax

legend(str)
legend(str, style)

Description

legend(str,style) displays legends for styles defined in string style. In string str, legends are separated by linefeed characters \n. Legends are displayed at the top right corner of the figure in a frame. All styles are permitted: symbols, lines, and filling. They are recycled if more legends are defined in str. If str is empty, no legend is displayed.

With a single input argument, legend(str) uses the default style 'k'.

With plotoption math, legend lines in first argument can contain MathML or LaTeX.

Example

Legend for two traces.

plot(1:20, [rand(1,20); randn(1,20)], '_x');
legend('Uniform random\nNormal random', '_x');

line

Plot lines.

Syntax

line(A, b)
line(V, P0)
line(..., style)
line(..., style, id)

Description

line displays one or several straight line(s). Each line is defined by an implicit equation or an explicit, parametric equation.

Implicit equation: Lines are defined by equations of the form a1 x + a2 y = b. The first argument of line is a matrix which contains the coefficients a1 in the first column and a2 in the second column. The second argument is a column vector which contains the coefficients b.

Explicit equations: Lines are defined by equations of the form P=P0+lambda*V where P0 is a point of the line, V a vector which defines its direction, and lambda a real parameter. The first argument of line is a matrix which contains the coefficients vx in the first column and vy in the second column. The second argument is a matrix which contains the coefficients x0 in the first column and y0 in the second column.

In both cases, each row corresponds to a different line. If one of the arguments has one row and the other has several (or none), the same row is duplicated to match the other size.

In figures with a logarithmic scale, only horizontal and vertical lines are allowed.

The optional third and fourth arguments are the same as for all graphical commands.

In mouse handlers, _x0 and _y0 correspond to the projection of the mouse position onto the line; _nb is the index of the line in A and b, and _ix is empty.

Examples

Vertical line at x=5:

line([1,0],5)

Draggable horizontal blue lines at y=2 and y=3:

line([0,1], [2;3], 'b', 1)

The same lines with named arguments:

line([0,1], [2;3], Color='blue', id=1)

math

Display MathML or LaTeX in a figure.

Syntax

math(x, y, string)
math(x, y, string, justification)
math(..., font)
math(..., id=id)

Description

With three arguments, math(x,y,string) renders a string as MathML or LaTeX, centered at the specified position. The third argument is assumed to be MathML unless it starts with a dollar character; in that case, it is converted to MathML as if it was processed by latex2mathml.

An optional fourth argument specifies how the MathML equation should be aligned with respect to the position (x,y). It is a string of one or two characters from the following set:

Char.	Alignment
c	Center (may be omitted)
l	Left
r	Right
t	Top
b	Bottom

For instance, 'l' means that the MathML equation is displayed to the right of the given position and is centered vertically, and 'rt', that the equation is to the bottom left of the given position.

An optional trailing argument specifies the font. It is a structure which is typically created with fontset; but only the base font size is used. Alternatively, the base font size can be specified with a named argument.

An ID can be specified with a named argument (not with a normal, unnamed argument).

The following MathML elements are supported: math, merror, mfenced, mfrac, mi, mn, mo, mpadded, mphantom, mroot, mrow, msqrt, mspace, msub, msubsup, msup, mtable, mtd, mtext, mtr.

Examples

math(0, 0, mathml([1,pi,1e30]));
math(0, 0, mathml(1e-6, Format='e', NPrec=2), Size=20);
math(0, 0, '$\\rho=\\sqrt{x^2+y^2}$');

pcolor

Pseudocolor plot.

Syntax

pcolor(C)
pcolor(X, Y, C)
pcolor(..., style)
pcolor(..., style, id)

Description

Command pcolor(C) displays a pseudocolor plot, i.e. a rectangular array where the color of each cell corresponds to the value of elements of 2-D array C. These values are real numbers between 0 and 1. The color used by pcolor depends on the current color map; the default is a grayscale from black (0) to white (1).

pcolor(X,Y,C) displays the plot on a grid whose vertex coordinates are given by arrays X and Y. Arrays X, Y and C must all have the same size.

With an additional string input argument, pcolor(...,style) specifies the style of the lines drawn between the cells.

The following argument, if it exists, is the ID used for interactivity. During interactive manipulation, the index obtained with _ix corresponds to the corner of the patch under the mouse with the smallest index.

Example

use colormaps;
n = 11;
(x, y) = meshgrid(1:n);
phi = pi/8;
X = x*cos(phi)-y*sin(phi);
Y = x*sin(phi)+y*cos(phi);
C = magic(n)/n^2;
pcolor(X, Y, C, 'k');
colormap(blue2yellow2redcm);
plotoption noframe;

plot

Generic plot.

Syntax

plot(y)
plot(x, y)
plot(..., style)
plot(..., style, id)

Description

The command plot displays graphical data in the current figure. The data are given as two vectors of coordinates x and y. If x is omitted, its default value is 1:size(y,2). Depending on the style, the points are displayed as individual marks or are linked with lines. The stairs style ('s') can be used to link two successive points with a horizontal line followed by a vertical line. If x and y are matrices, each row is considered as a separate line or set of marks; if only one of them is a matrix, the other one, a row or column vector, is replicated to match the size of the other argument.

The optional fourth argument is an identification number which is used for interactive manipulation. It should be equal or larger than 1. If present and a mousedown, mousedrag and/or mouseup handler exists, the position of the mouse where the click occurs is mapped to the closest graphical element which has been displayed with an ID; for the command plot, the closest point is considered (lines linking the points are ignored). If such a point is found at a small distance, the built-in variables _x0, _y0, and _z0 are set to the position of the point before it is moved; the variable _id is set to the ID as defined by the command plot; the variable _nb is set to the number of the row, and the variable _ix is set to the index of the column of the matrix x and y.

Examples

Sine between 0 and 2 pi:

x = 2 * pi * (0:100) * 0.01;
y = sin(x);
plot(x, y);

Ten random crosses:

plot(rand(1,10), rand(1,10), 'x');

Two traces with different styles:

plot(rand(2, 10),
     {Color='red', LineWidth=2;
      Marker='[]', MarkerFaceColor='navy', LineStyle='-'});

A complete SQ file for displaying a red triangle whose corners can be moved interactively on Sysquake:

variables x, y     // x and y are 1-by-3 vectors
init (x,y) = init  // init handler
figure "Triangle"
  draw drawTri(x, y)
  mousedrag (x, y) = dragTri(x, y, _ix, _x1, _y1)
functions
{@
function (x,y) = init
  x = [-1,1,0];
  y = [-1,-1,2];
  subplots('Triangle');
function drawTri(x,y)
  scale('equal', [-3, 3, -3, 3]);
  plot(x, y, FillColor='red', id=1);
function (x, y) = dragTri(x, y, ix, x1, y1)
  if isempty(ix)
    cancel;  // not a click over a point
  end
  x(ix) = x1;
  y(ix) = y1;
@}

plotoption

Set plot options such as axis, labels, grids, and legend position.

Syntax

plotoption(str1, str2, ...)
plotoption opt1 opt2 ...

Description

plotoption sets the initial value of the plot options the user can change. Its arguments, character strings, can each take one of the following values.

'frame': Rectangular frame with tick marks and a white background around the plot (default).
'noframe': No frame, no tickmarks, no white background.
'label': Subplot name above the frame (default).
'nolabel': No subplot name.
'legend': Legend (if it has been set with legend).
'nolegend': Hidden legend.
'trlegend': Legend in top right corner (default).
'tllegend': Legend in top left corner.
'brlegend': Legend in bottom right corner.
'bllegend': Legend in bottom left corner.
'margin': Margin for title and labels (default).
'nomargin': No margin.
'math': MathML or LaTeX rendering in title, label, legend, and controls like button and slider. The string (or substring in legend) is parsed as MathML if the first character is '<', or as LaTeX if it is '$'. Otherwise, it is displayed as if it was the text content of an <mtext> element, to guarantee that there is no font mismatch with mathematical expressions.
'nomath': No math (default).
'xticks': Ticks and labels for the x axis.
'noxticks': No ticks and labels for the x axis.
'yticks': Ticks and labels for the y axis.
'noyticks': No ticks and labels for the y axis.
'xyticks': Ticks and labels for the x and y axes (default).
'noxyticks': No ticks and labels for the x and y axes.
'xgrid': Grid of vertical lines for the x axis.
'noxgrid': No grid for the x axis.
'ygrid': Grid of horizontal lines for the y axis.
'noygrid': No grid for the y axis.
'xygrid': Grid of vertical and horizontal lines for the x and y axes.
'noxygrid': No grid for the x and y axes (default).
'grid': Normal details for grids displayed by sgrid, zgrid, etc. (default).
'nogrid': Removal of grids displayed by sgrid, zgrid, etc.
'fullgrid': More details for grids displayed by sgrid, zgrid, etc.
'fill3d': In 3D graphics, zoom in so that the bounding box fills the figure.

Examples

Display of a photographic image without frame:

plotoption noframe;
image(photo);

Math in a title:

plotoption math;
title '$\\hbox{Solution of}\\;\\dot{x}=f(x,t)$';

plotset

Options for plot style.

Syntax

options = plotset
options = plotset(name1, value1, ...)
options = plotset(options0, name1, value1, ...)

Description

plotset(name1,value1,...) creates the style option argument used by functions which display graphics, such as plot and line. Options are specified with name/value pairs, where the name is a string which must match exactly the names in the table below. Case is significant. Options which are not specified have a default value. The result is a structure whose fields correspond to each option. Without any input argument, plotset creates a structure with the default style.

When its first input argument is a structure, plotset adds or changes fields which correspond to the name/value pairs which follow.

Here is the list of permissible options:

Name	Default	Meaning
`ArrowEnd`	`false`	arrow at end
`ArrowStart`	`false`	arrow at start
`Color`	`[]`	line color
`Fill`	`false`	fill
`FillColor`	`[]`	filling color
`LineStyle`	`''`	line style
`LineWidth`	`[]`	line width
`Marker`	`''`	marker style
`MarkerEdgeColor`	`[]`	marker edge color
`MarkerFaceColor`	`[]`	marker face (filling) color
`Stairs`	`false`	stairs
`Stems`	`false`	stems

Colors are specified by value or by name. An empty array means the default color (usually black for lines and marker edge, none for filling, and white for marker face). A scalar number represents a shade of gray, an array of 3 numbers an RGB color. An additional element (last element of array of 2 or 4 numbers) represents the alpha component (transparency) where 0 is completely transparent; it is ignored on some platforms. Color type can be uint8 from 0 to 255, uint16 from 0 to 65535, or single or double from 0 to 1. In all cases, 0 represents black and the largest value, the maximum brightness.

Color names can be one of the following:

Name	Value as `uint8`
`'black'`	`[0,0,0]`
`'blue'`	`[0,0,255]`
`'green'`	`[0,128,0]`
`'cyan'`	`[0,255,255]`
`'red'`	`[255,0,0]`
`'magenta'`	`[255,0,255]`
`'yellow'`	`[255,255,0]`
`'white'`	`[255,255,255]`
`'aqua'`	`[0,255,255]`
`'darkgray'`	`[169,169,169]`
`'darkgrey'`	`[169,169,169]`
`'darkgreen'`	`[0,64,0]`
`'fuchsia'`	`[255,0,255]`
`'gray'`	`[128,128,128]`
`'grey'`	`[128,128,128]`
`'lime'`	`[0,255,0]`
`'maroon'`	`[128,0,0]`
`'navy'`	`[0,0,128]`
`'olive'`	`[128,128,0]`
`'orange'`	`[255,165,0]`
`'purple'`	`[128,0,128]`
`'silver'`	`[192,192,192]`
`'teal'`	`[0,128,128]`

Option LineStyle is an empty string for the default line style (solid line unless FillColor is set), or one of the following one-character strings:

Dash Pattern	`LineStyle`
solid	`'_'` (underscore)
dashed	`'-'` (hyphen)
dotted	`':'`
dash-dot	`'!'`
hidden	`' '` (space)

Option Marker is an empty string for the default symbol (usually no symbol, or a cross for plotroots), or one of the following strings:

Marker Shape	`Marker`
none	`' '` (space)
point	`'.'`
circle	`'o'`
cross	`'x'`
plus	`'+'`
star	`'*'`
triangle up	`'^'`
triangle down	`'v'`
triangle left	`'<'`
triangle right	`'>'`
square	`'[]'` or `'['`
diamond	`'<>'`

An explicit Fill=true is usefull only for filling with the default color or colors, with functions such contour. Otherwise, specifying a filling color with FillColor implies Fill=true.

When Stems is true, a marker is drawn for each point and is linked with a vertical line which connects it to the origin (in 2D plots, y=0 for linear scale or y=1 for logarithmic scale; in 3D plots, z=0). In polar plots, stems connects points to x=y=0.

Functions which support multiple styles, such as plot where each trace can have a different style, accept a structure array or a list of structures. If there are less elements in the style array or list than there are traces to plot, styles are recycled, restarting from the first one. If there are too many, superfluous styles are ignored.

When Stairs is true, for functions wihich support it, points are connected with a horizontal line followed by a vertical line.

Examples

Default options:

plotset
  ArrowEnd: false
  ArrowStart: false
  Color: []
  FillColor: []
  LineStyle: ''
  LineWidth: []
  Marker: ''
  MarkerEdgeColor: []
  MarkerFaceColor: []

Plot of 5 random lines defined by 10 points each, odd and even ones with different styles:

data = rand(5, 10);
styleOdd = plotset(ArrowStart=true,
  LineWidth=2,
  Color='red',
  Size=0);
styleEven = plotset(ArrowEnd=true,
  LineWidth=2,
  Size=10,
  Color='blue',
  MarkerEdgeColor='black',
  MarkerFaceColor='yellow');
plot(data, {styleOdd, styleEven});

Multiple styles can also be built directly as a structure array, without plotset; missing fields take their default values.

styles = {
  LineWidth=2, Color='red';
  LineStyle='-', Color='blue'
};
plot(data, styles);

polar

Polar plot.

Syntax

polar(theta, rho)
polar(..., style)
polar(..., style, id)

Description

Command polar displays graphical data in the current figure with polar coordinates. The data are given as two vectors of coordinates theta (in radians) and rho. Depending on the style, the points are displayed as individual marks or are linked with lines. If x and y are matrices, each row is considered as a separate line or set of marks; if only one of them is a matrix, the other one, a vector, is reused for each line.

Automatic scaling is performed the same way as for cartesian plots after polar coordinates have been converted. The figure axes, ticks and grids are specific to polar plots. Polar plots can be mixed with other graphical commands based on cartesian coordinates such as plot, line and circle.

Example

theta = 0:0.01:20*pi;
rho = exp(0.1 * theta) .* sin(5 * theta);
polar(theta, rho);

quiver

Quiver plot.

Syntax

quiver(x, y, u, v)
quiver(u, v)
quiver(..., scale)
quiver(..., style)

Description

quiver(x,y,u,v) displays vectors (u,v) starting at (x,y). If the four arguments are matrices of the same size, an arrow is drawn for each corresponding element. If x and y are vectors, they are repeated: x is transposed to a row vector if necessary and repeated to match the number of rows of u and v; and y is transposed to a column vector if necessary and repeated to match their number of columns. The absolute size of arrows is scaled with the average step of the grid given by x and y, so that they do not overlap if the grid is uniform.

If x and y are missing, their default values are [1,2,...,m] and [1,2,...,n] respectively, where m and n are the number of rows and columns of u and v.

With a 5th (or 3rd) argument, quiver(...,scale) multiplies the arrow lengths by the scalar number scale. If scale is zero, arrows are not scaled at all: u and v give directly the absolute value of the vectors.

With a 6th (or 4th) string argument, quiver(...,style) uses the specified style to draw the arrows.

Example

Force field; complex numbers are used to simplify computation.

scale equal;
z = fevalx(@plus, -5:0.5:5, 1j*(-5:0.5:5)');
z0 = 0.2+0.3j;
f = 1+20*sign(z-z0)./(max(abs(z-z0).^2,3));
x = real(z);
y = imag(z);
u = real(f);
v = imag(f);
quiver(x, y, u, v);

scale

Set the scale.

Syntax

scale([xmin,xmax,ymin,ymax])
scale([xmin,xmax])
scale([xmin,xmax,ymin,ymax,zmin,zmax])
scale(features)
scale(features, usersettablefeatures)
scale(features, [xmin,xmax,ymin,ymax])
scale(features, usersettablefeatures, [xmin,xmax,ymin,ymax])
sc = scale
(sc, type) = scale

Description

Without output argument, the scale command, which should be placed before any other graphical command, sets the scale and scale options. The last parameter contains the limits of the plot, either for both x and y axes or only for the x axis in 2D graphics, or for x, y and z axes for 3D graphics. The limits are used only if the user has not changed them by zooming.

The first parameter(s) specify some properties of the scale, and which one can be changed by the user. There are two ways to specify them: with a string or with one or two integer numbers. The recommended way is with a string. The list below enumerates the possible values.

'equal': Same linear scale for x and y axes. Typically used for representation of the complex plane, such as the roots of a polynomial or a Nyquist diagram. For 3D graphics, same effect as daspect([1,1,1]).
'pixel': Pixel (unit) linear scale for x and y axes. Used for diagrams which cannot be scaled, such as block diagrams, Venn diagrams, or special use interface. The y axis is always oriented upward.
'lock': See below.
'linlin': Linear scale for both axes.
'linlog': Linear scale for the x axis, and logarithmic scale for the y axis.
'loglin': Logarithmic scale for the x axis, and linear scale for the y axis.
'loglog': Logarithmic scale for both axes.
'lindb': Linear scale for the x axis, and dB scale for the y axis.
'logdb': Logarithmic scale for the x axis, and dB scale for the y axis.
'lindb/logdb': Linear scale for the x axis, and dB scale for the y axis. The user can choose a logarithmic scale for the x axis, and a logarithmic or linear scale for the y axis.
'loglog/set': Logarithmic scale for the x and y axes, without possibility for the user to change them.

The last-but-one setting shows how to enable the options the user can choose in Sysquake. The setting and the enabled options are separated by a dash; if a simple setting is specified, the enabled options are assumed to be the same. Enabling dB always permits the user to choose a logarithmic or linear scale, and enabling a logarithmic scale always permits to choose a linear scale. The 'equal' option cannot be combined with anything else. Changing the options in subsequent redraws is ignored, because options are under the user control.

The last setting ending with /set shows how to force options without letting the user override them. In this case, options can be changed during redraws. SQ files with customs ways to change the kind of scale must use this method.

When the properties are specified with one or two integer numbers, each bit corresponds to a property. Only the properties in bold in the table below can be set by the user, whatever the setting is.

Bit	Meaning
0	log x
2	tick on x axis
3	grid for x axis
4	labels on x axis
6	log y
7	dB y
8	tick on y axis
9	grid for y axis
10	labels on y axis
12	same scale on both axes
13	minimum grid
14	maximum grid

scale lock locks the scale as if the user had done it by hand. It fixes only the initial value; the user may change it back afterwards.

The scale is usually limited to a range of 1e-6 for linear scales and a ratio of 1e-6 for logarithmic scales. This avoids numeric problems, such as when a logarithmic scale is chosen and the data contain the value 0. In some rare cases, a large scale may be required. The 'lock' option is used to push the limits from 1e-6 to 1e-24 for both linear and logarithmic scales. A second argument must be provided:

scale('lock', [xmin,xmax,ymin,ymax]);

The command must be used in a draw handler (or from the command line interface). To add other options, use a separate scale command:

scale logdb;
scale('lock', [1e-5, 1e8, 1e-9, 1e9]);

The scale is locked, and the user may not unlock it. In the example above, note also that a single string argument can be written without quote and parenthesis if it contains only letters and digits.

With output arguments, scale returns the current scale as a vector [xmin,xmax,ymin,ymax]. If the scale is not fixed, the vector is empty. If only the horizontal scale is set, the vector is [xmin,xmax]. During a mouse drag, both the horizontal and vertical scales are fixed. The values returned by scale reflect the zoom chosen by the user. They can be used to limit the computation of data displayed by plot to the visible area. The optional second output argument type tells whether a linear or a logarithmic scale is set for axis x and y; it is a string such as 'linlin' or 'loglin'.

Examples

Here are some suggestions for the most usual graphics:

Time response	(default linlin is fine)
Bode mag	`scale logdb`
Bode phase	`scale loglin`
D bode mag	`scale('lindb/logdb',[0,pi/Ts])`
D bode phase	`scale('linlin/loglin',[0,pi/Ts])`
Poles	`scale equal`
D poles	`scale('equal',[-1,1,-1,1])`
Nyquist	`scale('equal',[-1.5,1.5,-1.5,1.5])`
Nichols	`scale lindb`

Use of scale to display a sine in the visible x range:

scale([0,10]);  % default x range between 0 and 10
sc = scale;     % maybe changed by the user (1x2 or 1x4)
xmin = sc(1);
xmax = sc(2);
x = xmin + (xmax - xmin) * (0:0.01:1);
                % 101 values between xmin and xmax
y = sin(x);
plot(x, y);

scalefactor

Change the scale displayed in axis ticks and labels.

Syntax

scalefactor(f)
f = scalefactor

Description

scalefactor(f) sets the factor used to display the ticks and the labels. Its argument f can be a vector of two or three real positive numbers to set separately the x, y, and z axes, or a real positive scalar to set the same factor for all axes. scalefactor([fx,fy]) is equivalent to scalefactor([fx,fy,1]). The normal factor value is 1, so that the ticks correspond to the graphical contents. With a different factor, the contents are displayed with the same scaling, but the ticks and labels are changed as if the graphical data had been scaled by the factor. For instance, you can plot data in radians (the standard angle unit in LME) and display ticks and labels in degrees by using a factor of 180/pi.

With an output argument, scalefactor gives the current factors as a 2-elements vector.

Example

Display the sine with a scale in degrees:

phi = 0:0.01:2*pi;
plot(phi, sin(phi));
scalefactor([180/pi, 1]);

scaleoverview

Set the scale overview rectangle.

Syntax

scaleoverview([xmin,xmax,ymin,ymax])
scaleoverview([xmin,xmax,ymin,ymax],'xy')
scaleoverview([xmin,xmax],'x')
scaleoverview([ymin,ymax],'y')

Description

scaleoverview sets the limits of a rectangular region used to provide an overview of the scale used in another plot. Typically, the same data are displayed in two subplots: one with a large, fixed displayed area (set with scale) with a smaller scale overview rectangle set with scaleoverview, and one with a smaller displayed area (set with scale) which matches the limits set with scaleoverview in the first plot. In Sysquake, scale synchronization is used to keep both subplots synchronized when the user zooms or drags the data in the second subplot or manipulates directly the scale overview rectangle.

By default, limits on axis x and y are provided. A second argument can specify which axis has limits: 'xy' (default), 'x' or 'y' (then the first argument is an array of two elements).

subplotstyle

Subplot style.

Syntax

subplotstyle(name, style)
style = subplotstyle(name)

Description

subplotstyle sets or gets the style of the current subplot. In Sysquake's SQ files, it should be used in draw handlers. It has the same arguments as figurestyle, which handles the settings globally for all subplots, or the default settings when both figurestyle and subplotstyle are used.

Example

subplot 211;
subplotstyle('plotbg', FillColor='yellow');
subplotstyle('frame', LineWidth=2);
step(1, 1:3);
subplot 212;
subplotstyle('plotbg', FillColor='orange');
step(1, 1:4);

text

Display text in a figure.

Syntax

text(x, y, string)
text(x, y, string, justification)
text(..., font)
text(..., id=id)

Description

With three arguments, text(x,y,string) displays a string centered at the specified position. An optional fourth argument specifies how the string should be aligned with respect to the position (x,y). It is a string of one or two characters from the following set:

Char.	Alignment
c	Center (may be omitted)
l	Left
r	Right
t	Top
b	Bottom

For instance, 'l' means that the string is displayed to the right of the given position and is centered vertically, and 'rt', that the string is to the bottom left of the given position.

An optional trailing argument specifies the font, size, type face, and color to use. It is a structure which is typically created with fontset. Alternatively, named arguments can be used directly, without fontset.

An ID can be specified with a named argument (not with a normal, unnamed argument).

Examples

A line is drawn between (-1,-1) and (1,1) with labels at both ends.

plot([-1,1], [-1,1]);
text(-1,-1, 'p1', 'tr');
text(1, 1, 'p2', 'bl');

Text with font specification:

font = fontset(Font='Times',
  Bold=true,
  Size=18,
  Color=[1,0,0]);
text(1.1, 4.2, 'Abc', font);

Same font with named arguments:

text(1.1, 4.2, 'Abc', font,
  Font='Times',
  Bold=true,
  Size=18,
  Color=[1,0,0]);

tickformat

Subplot tick format.

Syntax

tickformat(axis, format)

Description

tickformat(axis,format) specifies the format to be used for tick labels. The first argument, axis, specified which axis is affected: it is 1 or 'x' for the first axis (horizontal) or 2 or 'y' for the second axis (vertical, on the left or the right depending on the last call to altscale if any). Second argument, format, is a string similar to the first argument of sprintf. Only numeric formats are supported (%d, %e, %f, %g, %h, %i, %k, %n, %o, %P, %x), with their options, width and precision. Double % gives a single %, and other characters are used literally.

The format is not used if ticks are specified with function ticks.

Examples

General format with a unit for the x axis, and fixed format with two fractional digits for the y axis:

step(1, [1, 2, 3, 4]);
tickformat('x', '%g h');
tickformat('y', '%.2f');

ticks

Subplot ticks and tick labels.

Syntax

ticks(axis, majorTicks)
ticks(axis, majorTicks, minorTicks)
ticks(axis, majorTicks, minorTicks, tickLabels)

Description

ticks replaces default ticks (small scale marks along the plot frame and their labels outside the frame) with custom ones.

ticks(axis,majorTicks) specifies the value of major ticks (large ones). The first argument, axis, specified which axis is affected: it is 1 or 'x' for the first axis (horizontal) or 2 or 'y' for the second axis (vertical, on the left or the right depending on the last call to altscale if any). Second argument, majorTicks, is an array of values where ticks are displayed; the same scaling as the one applied to the plot contents is used.

With a third argument, ticks(axis,majorTicks,minorTicks) also displays minor ticks (smaller ones, typically used with a finer spacing) specified by array minorTicks.

With a fourth argument, ticks(axis,majorTicks,minorTicks,labels) displays labels at the position of major ticks. Labels are given as a string of linefeed-separated substrings, such as 'one\ntwo. If more values are specified for major ticks than for labels, labels are reused, starting from the first one. Superfluous labels are ignored. If no minor tick is displayed, argument minorTicks is optional.

Values out of range are not displayed. If axis labels are specified with function label, tick labels which would overlap are not displayed.

3D plots have always default ticks.

Examples

Bar plot where bars correspond to months:

bar([2,4,3,6]);
ticks('x', 1:4, 'Jan\nFeb\nMar\nApr');

Tick labels with units and axis label:

scale([0, 10]);
step(1, [1, 2, 3, 4]);
majorTicks = 0:2:10;
minorTicks = 0:0.5:10;
labels = sprintf('%g s\n', majorTicks);
ticks('x', majorTicks, minorTicks, labels);
ticks('y', 0:0.1:1);
label Time;

Plot without any tick and label:

step(1, [1, 2, 3, 4]);
ticks('x', []);
ticks('y', []);

title

Subplot title.

Syntax

title(string)

Description

title(string) sets or changes the title of the current subplot.

With plotoption math, the title can contain MathML or LaTeX.

Base Graphical Functions

activeregion

Syntax

Description

Example

See also

altscale

Syntax

Description

Example

See also

area

Syntax

Description

Examples

See also

bar

Syntax

Description

Examples

See also

barh

Syntax

Description

Examples

See also

circle

Syntax

Description

Examples

See also

colormap

Syntax

Description

See also

contour

Syntax

Description

Examples

See also

figurestyle

Syntax

Description

Example

See also

fontset

Syntax

Description

Examples

See also

fplot

Syntax

Description

Examples

See also

image

Syntax

Description

Examples

See also

label

Syntax

Description

Examples

See also

legend

Syntax

Description

Example

See also

line

Syntax

Description

Examples

See also

math

Syntax

Description

Examples

See also