Plotting
********

All of Octave's plotting functions use gnuplot to handle the actual graphics. Most types of plots can be generated using the basic plotting functions, which are patterned after the equivalent functions in MATLAB. The use of these functions is generally straightforward, and is the preferred method for generating plots. However, for users familiar with gnuplot, or for some specialized applications where the basic commands are inadequate, Octave also provides two low-level functions, gplot and gsplot, that behave almost exactly like the corresponding gnuplot functions plot and splot. Also note that some advanced MATLAB features from recent versions are not implemented, such as handle-graphics and related functions.

Two-Dimensional Plotting
========================

The MATLAB-style two-dimensional plotting commands are:

 -- Function File: plot (ARGS)
     This function produces two-dimensional plots.  Many different combinations of arguments are possible.  The simplest form is

          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 a single data argument is supplied, it 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 the first argument is a vector and the second is a matrix, the the vector is plotted versus the columns (or rows) of the matrix. (using whichever combination matches, with columns tried first.)

       * If the first argument is a matrix and the second is a vector, the the columns (or rows) of the matrix are plotted versus the vector. (using whichever combination matches, with columns tried first.)

       * If both arguments are vectors, the elements of Y are plotted versus the elements of X.

       * If both arguments are matrices, the columns of Y are plotted versus the columns of X.  In this case, both matrices must have the same number of rows and columns and no attempt is made to transpose the arguments to make the number of rows match.

          If both arguments are scalars, a single point is plotted.

     If the FMT argument is supplied, it is interpreted as follows.  If FMT is missing, the default gnuplot line style is assumed.

     -
          Set lines plot style (default).

     .
          Set dots plot style.

     @
          Set points plot style.

     -@
          Set linespoints plot style.

     ^
          Set impulses plot style.

     L
          Set steps plot style.

     N
          Interpreted as the plot color if N is an integer in the range 1 to 6.

     NM
          If NM is a two digit integer and M is an integer in the range 1 to 6, M is interpreted as the point style.  This is only valid in combination with the @ or -@ specifiers.

     C
          If C is one of "r", "g", "b", "m", "c", or "w", it is interpreted as the plot color (red, green, blue, magenta, cyan, or white).

     ";title;"
          Here "title" is the label for the key.

     +
     *
     o
     x
          Used in combination with the points or linespoints styles, set the point style.

     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.

semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__ bar, stairs, errorbar, replot, xlabel, ylabel, and title

 -- Built-in Function: hold ARGS
     Tell Octave to `hold' the current data on the plot when executing subsequent plotting commands.  This allows you to execute a series of plot commands and have all the lines end up on the same figure.  The default is for each new plot command to clear the plot device first. For example, the command

          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.

 -- Built-in Function: ishold
     Return 1 if the next line will be added to the current plot, or 0 if the plot device will be cleared before drawing the next line.

 -- Built-in Function: clearplot
 -- Built-in Function: clg
     Clear the plot window and any titles or axis labels.  The name 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.)

 -- Function File: shg

     Show the graph window.  Currently, this is the same as executing replot.

plot, semilogx, semilogy, loglog, polar, mesh, contour, bar, stairs, replot, xlabel, and ylabel

 -- Built-in Function: closeplot
     Close stream to the gnuplot subprocess.  If you are using X11, this will close the plot window.

 -- Built-in Function: purge_tmp_files
     Delete the temporary files created by the plotting commands.

     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.

 -- Function File: axis (LIMITS)
     Set axis limits for plots.

     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.

     Without any arguments, axis turns autoscaling on.

     With one output argument, x=axis returns the current axes (this is not yet implemented for automatic axes).

     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"
          Force a square aspect ratio.

     "equal"
          Force x distance to equal y-distance.

     "normal"
          Restore the balance.

     The following options control the way axis limits are interpreted.

     "auto"
          Set the specified axes to have nice limits around the data or all if no axes are specified.

     "manual"
          Fix the current axes limits.

     "tight"
          Fix axes to the limits of the data (not implemented).

     The option "image" is equivalent to "tight" and "equal".

     The following options affect the appearance of tic marks.

     "on"
          Turn tic marks and labels on for all axes.

     "off"
          Turn tic marks off for all axes.

     "tic[xyz]"
          Turn tic marks on for all axes, or turn them on for the specified axes and off for the remainder.

     "label[xyz]"
          Turn tic labels on for all axes, or turn them on for the specified axes and off for the remainder.

     "nolabel"
          Turn tic labels off for all axes.

     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"
          Reverse y-axis, so lower values are nearer the top.

     "xy"
          Restore y-axis, so higher values are nearer the top.

Specialized Two-Dimensional Plots
=================================

 -- Function File: bar (X, Y)
     Given two vectors of x-y data, 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.

plot, semilogx, semilogy, loglog, polar, mesh, contour, stairs, replot, xlabel, ylabel, and title

 -- Function File: contour (Z, N)
 -- Function File: contour (X, Y, Z, N)
     Make a contour plot of the three-dimensional surface described by Z.  Someone needs to improve gnuplot's contour routines before this will be very useful.

plot, semilogx, semilogy, loglog, polar, mesh, contour, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: hist (Y, X, NORM)
     Produce histogram counts or plots.

     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.

bar

 -- Function File: loglog (ARGS)
     Make a two-dimensional plot using log scales for both axes.  See the description of plot for a description of the arguments that loglog will accept.

plot, semilogy, loglog, polar, mesh, contour, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: polar (THETA, RHO, FMT)
     Make a two-dimensional plot given polar the coordinates THETA and RHO.

     The optional third argument specifies the line type.

plot, semilogx, semilogy, loglog, mesh, contour, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: semilogx (ARGS)
     Make a two-dimensional plot using a log scale for the X axis.  See the description of plot for a description of the arguments that semilogx will accept.

plot, semilogy, loglog, polar, mesh, contour, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: semilogy (ARGS)
     Make a two-dimensional plot using a log scale for the Y axis.  See the description of plot for a description of the arguments that semilogy will accept.

plot, semilogx, loglog, polar, mesh, contour, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: stairs (X, Y)
     Given two vectors of x-y data, bar produces a `stairstep' plot.

     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.

plot, semilogx, semilogy, loglog, polar, mesh, contour, bar, replot, xlabel, ylabel, and title

 -- Function File: errorbar (ARGS)
     This function produces two-dimensional plots with errorbars. Many different combinations of arguments are possible.  The simplest form is

          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:

     ~
          Set yerrorbars plot style (default).

     >
          Set xerrorbars plot style.

     ~>
          Set xyerrorbars plot style.

     #
          Set boxes plot style.

     #~
          Set boxerrorbars plot style.

     #~>
          Set boxxyerrorbars plot style.

     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.

semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: loglogerr (ARGS)
     This function produces two-dimensional plots on double logarithm axis with errorbars. Many different combinations of arguments are possible. The most used form is

          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.

errorbar, semilogxerr, semilogyerr, polar, mesh, contour, __pltopt__, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: semilogxerr (ARGS)
     This function produces two-dimensional plots on a semilogarithm axis with errorbars. Many different combinations of arguments are possible. The most used form is

          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.

errorbar, loglogerr semilogyerr, polar, mesh, contour, __pltopt__, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: semilogyerr (ARGS)
     This function produces two-dimensional plots on a semilogarithm axis with errorbars. Many different combinations of arguments are possible. The most used form is

          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.

errorbar, loglogerr semilogxerr, polar, mesh, contour, __pltopt__, bar, stairs, replot, xlabel, ylabel, and title

Three-Dimensional Plotting
==========================

The MATLAB-style three-dimensional plotting commands are:

 -- Function File: mesh (X, Y, Z)
     Plot a mesh given matrices X, and Y from 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.

plot, semilogx, semilogy, loglog, polar, meshgrid, meshdom, contour, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: [XX, YY] = meshgrid (X, Y)
 -- Function File: [XX, YY] = meshgrid (X)
     Given vectors of X and Y coordinates, return two matrices corresponding to the X and Y coordinates of a mesh.  The rows of XX are copies of X, and the columns of YY are copies of Y.

sombrero, plot, semilogx, semilogy, loglog, polar, mesh, meshdom, contour, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: meshdom (X, Y)
     Given vectors of X and Y coordinates, return two matrices corresponding to the X and Y coordinates of the mesh.

     Note: this function is provided for compatibility with older versions of MATLAB.  You should use meshgrid instead.

Plot Annotations
================

 -- Function File: grid (ARG)
     For two-dimensional plotting, force the display of a grid on the plot. The argument may be either "on" or "off".  If it is omitted, "on" is assumed.

plot, semilogx, semilogy, loglog, polar, mesh, contour, bar, stairs, replot, xlabel, ylabel, and title

 -- Function File: title (STRING)
     Specify a title for a plot.

plot, semilogx, semilogy, loglog, polar, mesh, contour, bar, stairs, replot, xlabel, and ylabel

 -- Function File: xlabel (STRING)
 -- Function File: ylabel (STRING)
 -- Function File: zlabel (STRING)
     Specify x, y, and z axis labels for the plot.  If you already have a plot displayed, use the command replot to redisplay it with the new labels.

plot, semilogx, semilogy, loglog, polar, mesh, contour, bar, stairs, replot, ylabel, and title

 -- Function File: top_title (STRING)
 -- Function File: bottom_title (STRING)
     Makes a title with text STRING at the top (bottom) of the plot.

Multiple Plots on One Page
==========================

The following functions all require a version of gnuplot that supports the multiplot feature.

 -- Function File: mplot (X, Y)
 -- Function File: mplot (X, Y, FMT)
 -- Function File: mplot (X1, Y1, X2, Y2)
     This is a modified version of the 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.

 -- Function File: multiplot (XN, YN)
     Sets and resets multiplot mode.

     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.

 -- Function File: oneplot ()
     If in multiplot mode, switches to single plot mode.

 -- Function File: plot_border (...)
     Multiple arguments allowed to specify the sides on which the border is shown.  Allowed arguments include:

     "blank"
          No borders displayed.

     "all"
          All borders displayed

     "north"
          North Border

     "south"
          South Border

     "east"
          East Border

     "west"
          West Border

     The arguments may be abbreviated to single characters.  Without any arguments, plot_border turns borders off.

 -- Function File: subplot (ROWS, COLS, INDEX)
 -- Function File: subplot (RCN)
     Sets gnuplot in multiplot mode and plots in location given by index (there are COLS by ROWS subwindows).

     The global variable __MULTIPLOT_SCALE__ should be used when the command __gnuplot_set__ size xsize, ysize has been used prior to calling subplot.

     The value of __MULTIPLOT_SCALE__ should be a vector with two elements, the first set equal to XSIZE and the second to YSIZE.

     Input:

     rows
          Number of rows in subplot grid.

     columns
          Number of columns in subplot grid.

     index
          Index of subplot where to make the next plot.

     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  |
          +-----+-----+-----+-----+

 -- Function File: subwindow (XN, YN)
     Sets the subwindow position in multiplot mode for the next plot.  The multiplot mode has to be previously initialized using the multiplot function, otherwise this command just becomes an alias to multiplot

Multiple Plot Windows
=====================

 -- Function File: figure (N)
     Set the current plot window to plot window N.  This function currently requires X11 and a version of gnuplot that supports multiple frames.  If N is not specified, the next available window number is chosen.

Low-Level plotting commands
===========================

 -- Command: gplot RANGES EXPRESSION USING TITLE STYLE
     Generate a 2-dimensional plot.

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

 -- Command: gsplot RANGES EXPRESSION USING TITLE STYLE
     Generate a 3-dimensional plot.

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

 -- Command: gset options
 -- Command: gshow options
 -- Command: replot options
     In addition to the basic plotting commands, the whole range of 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.

Note that NaN values in the plot data are automatically omitted, and Inf values are converted to a very large value before calling gnuplot.

Interaction with gnuplot
========================

 -- Built-in Variable: gnuplot_binary
     The name of the program invoked by the plot command.  The default value is "gnuplot".  See Installation.

 -- Built-in Variable: gnuplot_has_frames
     If the value of this variable is nonzero, Octave assumes that your copy of gnuplot has support for multiple frames that is included in recent 3.6beta releases.  Its initial value is determined by configure, but it can be changed in your startup script or at the command line in case configure got it wrong, or if you upgrade your gnuplot installation.

 -- Built-in Variable: gnuplot_command_plot

 -- Built-in Variable: gnuplot_command_replot

 -- Built-in Variable: gnuplot_command_splot

 -- Built-in Variable: gnuplot_command_using

 -- Built-in Variable: gnuplot_command_with

 -- Built-in Variable: gnuplot_command_axes

 -- Built-in Variable: gnuplot_command_title

 -- Built-in Variable: gnuplot_command_end