All of Octave's plotting functions use gnuplot to handle the
actual graphics. There are two low-level functions, gplot and
gsplot, that behave almost exactly like the corresponding
gnuplot functions plot and splot. A number of
other higher level plotting functions, patterned after the graphics
functions found in MATLAB version 3.5, are also available.
These higher level functions are all implemented in terms of the two
low-level plotting functions.
The ranges, using, title, and style arguments are optional, and the using, title and style qualifiers may appear in any order after the expression. You may plot multiple expressions with a single command by separating them with commas. Each expression may have its own set of qualifiers.
The optional item ranges has the syntax
[ x_lo : x_up ] [ y_lo : y_up ]
and may be used to specify the ranges for the axes of the plot,
independent of the actual range of the data. The range for the y axes
and any of the individual limits may be omitted. A range [:]
indicates that the default limits should be used. This normally means
that a range just large enough to include all the data points will be
used.
The expression to be plotted must not contain any literal matrices
(e.g. [ 1, 2; 3, 4 ]) since it is nearly impossible to
distinguish a plot range from a matrix of data.
See the help for gnuplot for a description of the syntax for the
optional items.
By default, the gplot command plots the second column of a matrix
versus the first. If the matrix only has one column, it is taken as a
vector of y-coordinates and the x-coordinate is taken as the element
index, starting with zero. For example,
gplot rand (100,1) with linespoints
will plot 100 random values and connect them with lines. When
gplot is used to plot a column vector, the indices of the
elements are taken as x values.
If there are more than two columns, you can choose which columns to plot with the using qualifier. For example, given the data
x = (-10:0.1:10)'; data = [x, sin(x), cos(x)];
the command
gplot [-11:11] [-1.1:1.1] \ data with lines, data using 1:3 with impulses
will plot two lines. The first line is generated by the command
data with lines, and is a graph of the sine function over the
range -10 to 10. The data is taken from the first two columns of
the matrix because columns to plot were not specified with the
using qualifier.
The clause using 1:3 in the second part of this plot command
specifies that the first and third columns of the matrix data
should be taken as the values to plot.
In this example, the ranges have been explicitly specified to be a bit larger than the actual range of the data so that the curves do not touch the border of the plot.
gset and gshow commands from gnuplot are available,
as is replot.
Note that in Octave 2.0, the set and show commands were
renamed to gset and gshow in order to allow for
compatibility with the MATLAB graphics and GUI commands in a future
version of Octave. (For now, the old set and show
commands do work, but they print an annoying warning message to try to
get people to switch to using gset and gshow.)
The gset and gshow commands allow you to set and show
gnuplot parameters. For more information about the gset
and gshow commands, see the documentation for set and
show in the gnuplot user's guide (also available on line
if you run gnuplot directly, instead of running it from Octave).
The replot command allows you to force the plot to be
redisplayed. This is useful if you have changed something about the
plot, such as the title or axis labels. The replot command also
accepts the same arguments as gplot or gsplot (except for
data ranges) so you can add additional lines to existing plots.
For example,
gset term tek40 gset output "/dev/plotter" gset title "sine with lines and cosine with impulses" replot "sin (x) w l"
will change the terminal type for plotting, add a title to the current plot, add a graph of sin (x) to the plot, and force the new plot to be sent to the plot device. This last step is normally required in order to update the plot. This default is reasonable for slow terminals or hardcopy output devices because even when you are adding additional lines with a replot command, gnuplot always redraws the entire plot, and you probably don't want to have a completely new plot generated every time something as minor as an axis label changes.
The command shg is equivalent to executing replot without
any arguments.
@anchor{doc-automatic_replot}
automatic_replot to a nonzero value. Since this is fairly
inefficient, the default value is 0.
Note that NaN values in the plot data are automatically omitted, and Inf values are converted to a very large value before calling gnuplot.
The MATLAB-style two-dimensional plotting commands are:
@anchor{doc-plot}
plot (y)
where the argument is taken as the set of y coordinates and the x coordinates are taken to be the indices of the elements, starting with 1.
If more than one argument is given, they are interpreted as
plot (x, y, fmt ...)
where y and fmt are optional, and any number of argument sets may appear. The x and y values are interpreted as follows:
If the fmt argument is supplied, it is interpreted as follows. If fmt is missing, the default gnuplot line style is assumed.
@ or -@ specifiers.
"r", "g", "b", "m",
"c", or "w", it is interpreted as the plot color (red,
green, blue, magenta, cyan, or white).
"title" is the label for the key.
The color line styles have the following meanings on terminals that support color.
Number Gnuplot colors (lines)points style 1 red * 2 green + 3 blue o 4 magenta x 5 cyan house 6 brown there exists
The fmt argument can also be used to assign key titles. To do so, include the desired title between semi-colons after the formatting sequence described above, e.g. "+3;Key Title;" Note that the last semi-colon is required and will generate an error if it is left out.
Here are some plot examples:
plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+")
This command will plot y with points of type 2 (displayed as
`+') and color 1 (red), y2 with lines, y3 with lines of
color 4 (magenta) and y4 with points displayed as `+'.
plot (b, "*")
This command will plot the data in the variable b will be plotted
with points displayed as `*'.
t = 0:0.1:6.3; plot (t, cos(t), "-;cos(t);", t, sin(t), "+3;sin(t);");
This will plot the cosine and sine functions and label them accordingly in the key.
@anchor{doc-hold}
hold on
turns the hold state on. An argument of off turns the hold state
off, and hold with no arguments toggles the current hold state.
@anchor{doc-ishold}
@anchor{doc-clearplot}
clg is aliased to clearplot for compatibility with
MATLAB.
The commands gplot clear, gsplot clear, and replot
clear are equivalent to clearplot. (Previously, commands like
gplot clear would evaluate clear as an ordinary expression
and clear all the visible variables.)
@anchor{doc-shg}
Show the graph window. Currently, this is the same as executing replot without any arguments.
@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour, bar, stairs, gplot, gsplot, replot, xlabel, and ylabel}
@anchor{doc-closeplot}
gnuplot subprocess. If you are using X11,
this will close the plot window.
@anchor{doc-purge_tmp_files}
Octave creates temporary data files for gnuplot and then sends
commands to gnuplot through a pipe. Octave will delete the
temporary files on exit, but if you are doing a lot of plotting you may
want to clean up in the middle of a session.
A future version of Octave will eliminate the need to use temporary files to hold the plot data.
@anchor{doc-axis}
The argument limits should be a 2, 4, or 6 element vector. The first and second elements specify the lower and upper limits for the x axis. The third and fourth specify the limits for the y axis, and the fifth and sixth specify the limits for the z axis.
If your plot is already drawn, then you need to use replot before
the new axis limits will take effect. You can get this to happen
automatically by setting the built-in variable automatic_replot
to a nonzero value.
Without any arguments, axis turns autoscaling on.
The vector argument specifying limits is optional, and additional string arguments may be used to specify various axis properties. For example,
axis ([1, 2, 3, 4], "square");
forces a square aspect ratio, and
axis ("labely", "tic");
turns tic marks on for all axes and tic mark labels on for the y-axis only.
The following options control the aspect ratio of the axes.
"square"
"equal"
"normal"
The following options control the way axis limits are interpreted.
"auto"
"manual"
"tight"
The option "image" is equivalent to "tight" and
"equal".
The following options affect the appearance of tic marks.
"on"
"off"
"tic[xyz]"
"label[xyz]"
"nolabel"
Note, if there are no tic marks for an axis, there can be no labels.
The following options affect the direction of increasing values on the axes.
"ij"
"xy"
@anchor{doc-bar}
bar produces a bar graph.
If only one argument is given, it is taken as a vector of y-values and the x coordinates are taken to be the indices of the elements.
If two output arguments are specified, the data are generated but not plotted. For example,
bar (x, y);
and
[xb, yb] = bar (x, y); plot (xb, yb);
are equivalent.
@anchor{doc-contour}
gnuplot's contour routines
before this will be very useful.
@anchor{doc-hist}
With one vector input argument, plot a histogram of the values with 10 bins. The range of the histogram bins is determined by the range of the data.
Given a second scalar argument, use that as the number of bins.
Given a second vector argument, use that as the centers of the bins, with the width of the bins determined from the adjacent values in the vector.
If third argument is provided, the histogram is normalised such that the sum of the bars is equal to norm.
Extreme values are lumped in the first and last bins.
With two output arguments, produce the values nn and xx such
that bar (xx, nn) will plot the histogram.
@anchor{doc-loglog}
plot for a description of the arguments that
loglog will accept.
@anchor{doc-polar}
The optional third argument specifies the line type.
@anchor{doc-semilogx}
plot for a description of the arguments
that semilogx will accept.
@anchor{doc-semilogy}
plot for a description of the arguments
that semilogy will accept.
@anchor{doc-stairs}
If only one argument is given, it is taken as a vector of y-values and the x coordinates are taken to be the indices of the elements.
If two output arguments are specified, the data are generated but not plotted. For example,
stairs (x, y);
and
[xs, ys] = stairs (x, y); plot (xs, ys);
are equivalent.
@anchor{doc-errorbar}
errorbar (y, ey)
where the first argument is taken as the set of y coordinates and the second argument ey is taken as the errors of the y values. x coordinates are taken to be the indices of the elements, starting with 1.
If more than two arguments are given, they are interpreted as
errorbar (x, y, ..., fmt ...)
where after x and y there can be up to four error parameters such as ey, ex, ly, uy etc., depending on the plot type. Any number of argument sets may appear, as long as they are separated with a format string fmt.
If y is a matrix, x and error parameters must also be matrices having same dimensions. The columns of y are plotted versus the corresponding columns of x and errorbars are drawn from the corresponding columns of error parameters.
If fmt is missing, yerrorbars ("~") plot style is assumed. If the fmt argument is supplied, it is interpreted as in normal plots (See __pltopt__). In addition the following plot styles are supported by errorbar:
Examples:
errorbar(x, y, ex, ">")
xerrorbar plot of y versus x with x errorbars drawn from x-ex to x+ex.
errorbar(x, y1, ey, "~", x, y2, ly, uy)
Two yerrorbar plots with y1 and y2 versus x. Errorbars for y1 are drawn from y1-ey to y1+ey, errorbars for y2 from y2-ly to y2+uy.
errorbar(x, y, lx, ux, ly, uy, "~>")
xyerrorbar plot of y versus x where x errorbars are drawn from x-lx to x+ux and y errorbars from y-ly to y+uy.
@seealso{semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__, bar, stairs, gplot, gsplot, replot, xlabel, ylabel, and title}
@anchor{doc-loglogerr}
loglogerr (x, y, ey, fmt)
which produces a double logarithm plot of y versus x with errors in the y-scale defined by ey and the plot format defined by fmt. See errorbar for available formats and additional information.
@seealso{errorbar, semilogxerr, semilogyerr, polar, mesh, contour, __pltopt__, bar, stairs, gplot, gsplot, replot, xlabel, ylabel, and title}
@anchor{doc-semilogxerr}
semilogxerr (x, y, ey, fmt)
which produces a semi-logarithm plot of y versus x with errors in the y-scale defined by ey and the plot format defined by fmt. See errorbar for available formats and additional information.
@seealso{errorbar, loglogerr semilogyerr, polar, mesh, contour, __pltopt__, bar, stairs, gplot, gsplot, replot, xlabel, ylabel, and title}
@anchor{doc-semilogyerr}
semilogyerr (x, y, ey, fmt)
which produces a semi-logarithm plot of y versus x with errors in the y-scale defined by ey and the plot format defined by fmt. See errorbar for available formats and additional information.
@seealso{errorbar, loglogerr semilogxerr, polar, mesh, contour, __pltopt__, bar, stairs, gplot, gsplot, replot, xlabel, ylabel, and title}
The ranges, using, title, and style arguments are optional, and the using, title and style qualifiers may appear in any order after the expression. You may plot multiple expressions with a single command by separating them with commas. Each expression may have its own set of qualifiers.
The optional item ranges has the syntax
[ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]
and may be used to specify the ranges for the axes of the plot,
independent of the actual range of the data. The range for the y and z
axes and any of the individual limits may be omitted. A range
[:] indicates that the default limits should be used. This
normally means that a range just large enough to include all the data
points will be used.
The expression to be plotted must not contain any literal matrices (e.g.
[ 1, 2; 3, 4 ]) since it is nearly impossible to distinguish a
plot range from a matrix of data.
See the help for gnuplot for a description of the syntax for the
optional items.
By default, the gsplot command plots each column of the
expression as the z value, using the row index as the x value, and the
column index as the y value. The indices are counted from zero, not
one. For example,
gsplot rand (5, 2)
will plot a random surface, with the x and y values taken from the row and column indices of the matrix.
If parametric plotting mode is set (using the command
gset parametric, then gsplot takes the columns of the
matrix three at a time as the x, y and z values that define a line in
three space. Any extra columns are ignored, and the x and y values are
expected to be sorted. For example, with parametric set, it
makes sense to plot a matrix like
1 1 3 2 1 6 3 1 9 1 2 2 2 2 5 3 2 8 1 3 1 2 3 4 3 3 7
but not rand (5, 30).
The MATLAB-style three-dimensional plotting commands are:
@anchor{doc-mesh}
meshdom and
a matrix z corresponding to the x and y coordinates of
the mesh. If x and y are vectors, then a typical vertex
is (x(j), y(i), z(i,j)). Thus, columns of z
correspond to different x values and rows of z correspond
to different y values.
@anchor{doc-meshgrid}
@anchor{doc-meshdom}
Note: this function is provided for compatibility with older versions
of MATLAB. You should use meshgrid instead.
@anchor{doc-grid}
"on" or "off". If it is
omitted, "on" is assumed.
@anchor{doc-title}
replot to redisplay it with the new title.
@anchor{doc-bottom_title}
@anchor{doc-xlabel}
replot to redisplay it with the new
labels.
The following functions all require a version of gnuplot that
supports the multiplot feature.
@anchor{doc-mplot}
plot function that works with
the multiplot version of gnuplot to plot multiple plots per page.
This plot version automatically advances to the next subplot position
after each set of arguments are processed.
See the description of the plot function for the various options.
@anchor{doc-multiplot}
If the arguments are non-zero, multiplot will set up multiplot
mode with xn, yn subplots along the x and y
axes. If both arguments are zero, multiplot closes multiplot
mode.
@anchor{doc-oneplot}
@anchor{doc-plot_border}
"blank"
"all"
"north"
"south"
"east"
"west"
The arguments may be abbreviated to single characters. Without any
arguments, plot_border turns borders off.
@anchor{doc-subplot}
gnuplot in multiplot mode and plots in location
given by index (there are cols by rows subwindows).
Input:
If only one argument is supplied, then it must be a three digit value specifying the location in digits 1 (rows) and 2 (columns) and the plot index in digit 3.
The plot index runs row-wise. First all the columns in a row are filled and then the next row is filled.
For example, a plot with 4 by 2 grid will have plot indices running as follows:
+-----+-----+-----+-----+ | 1 | 2 | 3 | 4 | +-----+-----+-----+-----+ | 5 | 6 | 7 | 8 | +-----+-----+-----+-----+
@anchor{doc-subwindow}
multiplot function, otherwise this command just becomes an alias
to multiplot
@anchor{doc-top_title}
@anchor{doc-figure}
gnuplot@anchor{doc-gnuplot_binary}
"gnuplot". See section Installing Octave.
@anchor{doc-gnuplot_has_frames}
@anchor{doc-graw}
@anchor{doc-gnuplot_command_plot}
@anchor{doc-gnuplot_command_replot}
@anchor{doc-gnuplot_command_splot}
@anchor{doc-gnuplot_command_using}
@anchor{doc-gnuplot_command_with}
@anchor{doc-gnuplot_command_axes}
@anchor{doc-gnuplot_command_title}
@anchor{doc-gnuplot_command_end}
Go to the first, previous, next, last section, table of contents.