Plotting
********

Plotting Basics
===============

Octave makes it easy to create many different types of two- and three-dimensional plots using a few high-level functions.

If you need finer control over graphics, see Advanced Plotting.

Two-Dimensional Plots
---------------------

The plot function allows you to create simple x-y plots with linear axes.  For example,

     x = -10:0.1:10;
     plot (x, sin (x));

displays a sine wave shown in see fig:plot.  On most systems, this command will open a separate plot window to display the graph.

Figure: Simple Two-Dimensional Plot.

The function fplot also generates two-dimensional plots with linear axes using a function name and limits for the range of the x-coordinate instead of the x and y data.  For example,

     fplot (@sin, [-10, 10], 201);

produces a plot that is equivalent to the one above, but also includes a legend displaying the name of the plotted function.

(plot)

(fplot)

The functions semilogx, semilogy, and loglog are similar to the plot function, but produce plots in which one or both of the axes use log scales.

(semilogx)

(semilogy)

(loglog)

The functions bar, barh, stairs, and stem are useful for displaying discrete data.  For example,

     hist (randn (10000, 1), 30);

produces the histogram of 10,000 normally distributed random numbers shown in see fig:hist.

Figure: Histogram.

(bar)

(barh)

(hist)

(stairs)

(stem)

The contour and contourc functions produce two-dimensional contour plots from three dimensional data.

(contour)

(contourc)

The errorbar, semilogxerr, semilogyerr, and loglogerr functions produces plots with error bar markers.  For example,

     x = 0:0.1:10;
     y = sin (x);
     yp =  0.1 .* randn (size (x));
     ym = -0.1 .* randn (size (x));
     errorbar (x, sin (x), ym, yp);

produces the figure shown in see fig:errorbar.

Figure: Errorbar plot.

(errorbar)

(semilogxerr)

(semilogyerr)

(loglogerr)

Finally, the polar function allows you to easily plot data in polor coordinates.  However, the display coordinates remain rectangular and linear.  For example,

     polar (0:0.1:10*pi, 0:0.1:10*pi);

produces the spiral plot shown in see fig:polar.

Figure: Polar plot.

(polar)

The axis function may be used to change the axis limits of an existing plot.

(axis)

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

The function mesh produces mesh surface plots.  For example,

     tx = ty = linspace (-8, 8, 41)';
     [xx, yy] = meshgrid (tx, ty);
     r = sqrt (xx .^ 2 + yy .^ 2) + eps;
     tz = sin (r) ./ r;
     mesh (tx, ty, tz);

produces the familiar ``sombrero'' plot shown in see fig:mesh.  Note the use of the function meshgrid to create matrices of X and Y coordinates to use for plotting the Z data.  The ndgrid function is similar to meshgrid, but works for N-dimensional matrices.

Figure: Mesh plot.

The meshc function is similar to mesh, but also produces a plot of contours for the surface.

The plot3 function displays arbitrary three-dimensional data, without requiring it to form a surface.  For example

     t = 0:0.1:10*pi;
     r = linspace (0, 1, numel (t));
     z = linspace (0, 1, numel (t));
     plot3 (r.*sin(t), r.*cos(t), z);

displays the spiral in three dimensions shown in see fig:plot3.

Figure: Three dimensional spiral.

Finally, the view function changes the viewpoint for three-dimensional plots.

(mesh)

(meshc)

(meshgrid)

(ndgrid)

(plot3)

(view)

Plot Annotations
----------------

You can add titles, axis labels, legends, and arbitrary text to an existing plot.  For example,

     x = -10:0.1:10;
     plot (x, sin (x));
     title ("sin(x) for x = -10:0.1:10");
     xlabel ("x");
     ylabel ("sin (x)");
     text (pi, 0.7, "arbitrary text");
     legend ("sin (x)");

The functions grid and box may also be used to add grid and border lines to the plot.  By default, the grid is off and the border lines are on.

(title)

(legend)

(text)

(xlabel)

(box)

(grid)

Multiple Plots on One Page
--------------------------

Octave can display more than one plot in a single figure.  The simplest way to do this is to use the subplot function to divide the plot area into a series of subplot windows that are indexed by an integer. For example,

     subplot (2, 1, 1)
     fplot (@sin, [-10, 10]);
     subplot (2, 1, 2)
     fplot (@cos, [-10, 10]);

creates a figure with two separate axes, one displaying a sine wave and the other a cosine wave.  The first call to subplot divides the figure into two plotting areas (two rows and one column) and makes the first plot area active.  The grid of plot areas created by subplot is numbered in column-major order (top to bottom, left to right).

(subplot)

Multiple Plot Windows
---------------------

You can open multiple plot windows using the figure function. For example

     figure (1);
     fplot (@sin, [-10, 10]);
     figure (2);
     fplot (@cos, [-10, 10]);

creates two figures, with the first displaying a sine wave and the second a cosine wave.  Figure numbers must be positive integers.

(figure)

Printing Plots
--------------

The print command allows you to save plots in a variety of formats.  For example,

     print -deps foo.eps

writes the current figure to an encapsulated PostScript file called foo.eps.

(print)

(orient)

Test Plotting Functions
-----------------------

The functions sombrero and peaks provide a way to check that plotting is working.  Typing either sombrero or peaks at the Octave prompt should display a three dimensional plot.

(sombrero)

(peaks)

Advanced Plotting
=================

Graphics Objects
----------------

Plots in Octave are constructed from the following graphics objects.  Each graphics object has a set of properties that define its appearance and may also contain links to other graphics objects. Graphics objects are only referenced by a numeric index, or handle.

root figure
     The parent of all figure objects.  The index for the root figure is defined to be 0.

figure
     A figure window.

axes
     An set of axes.  This object is a child of a figure object and may be a parent of line, text, image, patch, or surface objects.

line
     A line in two or three dimensions.

text
     Text annotations.

image
     A bitmap image.

patch
     A filled polygon, currently limited to two dimensions.

surface
     A three-dimensional surface.

To determine whether an object is a graphics object index or a figure index, use the functions ishandle and isfigure.

(ishandle)

(isfigure)

The function gcf returns an index to the current figure object, or creates one if none exists.  Similarly, gca returns the current axes object, or creates one (and its parent figure object) if none exists.

(gcf)

(gca)

The get and set functions may be used to examine and set properties for graphics objects.  For example,

     get (0)
         => ans =
            {
              type = root figure
              currentfigure = [](0x0)
              children = [](0x0)
              visible = on
            }

returns a structure containing all the properties of the root figure. As with all functions in Octave, the structure is returned by value, so modifying it will not modify the internal root figure plot object.  To do that, you must use the set function.  Also, note that in this case, the currentfigure property is empty, which indicates that there is no current figure window.

The get function may also be used to find the value of a single property.  For example,

     get (gca (), "xlim")
         => [ 0 1 ]

returns the range of the x-axis for the current axes object in the current figure.

To set graphics object properties, use the set function.  For example,

     set (gca (), "xlim", [-10, 10]);

sets the range of the x-axis for the current axes object in the current figure to [-10, 10].  Additionally, calling set with a graphics object index as the only argument returns a structure containing the default values for all the properties for the given object type.  For example,

     set (gca ())

returns a structure containing the default property values for axes objects.

(get)

(set)

(ancestor)

You can create axes, line, and patch objects directly using the axes, line, and patch functions.  These objects become children of the current axes object.

(axes)

(line)

(patch)

By default, Octave refreshes the plot window when a prompt is printed, or when waiting for input.  To force an update at other times, call the drawnow function.

(drawnow)

Normally, high-level plot functions like plot or mesh call newplot to initialize the state of the current axes so that the next plot is drawn in a blank window with default property settings.  To have two plots superimposed over one another, call the hold function.  For example,

     hold ("on");
     x = -10:0.1:10;
     plot (x, sin (x));
     plot (x, cos (x));
     hold ("off");

displays sine and cosine waves on the same axes.  If the hold state is off, consecutive plotting commands like this will only display the last plot.

(newplot)

(hold)

(ishold)

To clear the current figure, call the clf function.  To bring it to the top of the window stack, call the shg function.  To delete a graphics object, call delete on its index.  To close the figure window, call the close function.

(clf)

(shg)

(delete)

(close)

(closereq)

Graphics Object Properties
--------------------------

Root Figure Properties
......................

currentfigure
     Index to graphics object for the current figure.

Figure Properties
.................

nextplot
     May be one of

     "new"

     "add"

     "replace"

     "replacechildren"

closerequestfcn
     Handle of function to call when a figure is closed.

currentaxes
     Index to graphics object of current axes.

colormap
     An N-by-3 matrix containing the color map for the current axes.

visible
     Either "on" or "off" to toggle display of the figure.

paperorientation
     Indicates the orientation for printing.  Either "landscape" or "portrait".

Axes Properties
...............

position
     A four-element vector specifying the coordinates of the lower left corner and width and height of the plot, in normalized units.  For example, [0.2, 0.3, 0.4, 0.5] sets the lower left corner of the axes at (0.2, 0.3) and the width and heigth to be 0.4 and 0.5 respectively.

title
     Index of text object for the axes title.

box
     Either "on" or "off" to toggle display of the box around the axes.

key
     Either "on" or "off" to toggle display of the legend. Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

keybox
     Either "on" or "off" to toggle display of a box around the legend.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

keypos
     An integer from 1 to 4 specifying the position of the legend.  1 indicates upper right corner, 2 indicates upper left, 3 indicates lower left, and 4 indicates lower right.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

dataaspectratio
     A two-element vector specifying the relative height and width of the data displayed in the axes.  Setting dataaspectratio to 1, 2] causes the length of one unit as displayed on the y axis to be the same as the length of 2 units on the x axis.  Setting dataaspectratio also forces the dataaspectratiomode property to be set to "manual".

dataaspectratiomode
     Either "manual" or "auto".

xlim
ylim
zlim
clim
     Two-element vectors defining the limits for the x, y, and z axes and the Setting one of these properties also forces the corresponding mode property to be set to "manual".

xlimmode
ylimmode
zlimmode
climmode
     Either "manual" or "auto".

xlabel
ylabel
zlabel
     Indices to text objects for the axes labels.

xgrid
ygrid
zgrid
     Either "on" or "off" to toggle display of grid lines.

xminorgrid
yminorgrid
zminorgrid
     Either "on" or "off" to toggle display of minor grid lines.

xtick
ytick
ztick
     Setting one of these properties also forces the corresponding mode property to be set to "manual".

xtickmode
ytickmode
ztickmode
     Either "manual" or "auto".

xticklabel
yticklabel
zticklabel
     Setting one of these properties also forces the corresponding mode property to be set to "manual".

xticklabelmode
yticklabelmode
zticklabelmode
     Either "manual" or "auto".

xscale
yscale
zscale
     Either "linear" or "log".

xdir
ydir
zdir
     Either "forward" or "reverse".

xaxislocation
yaxislocation
     Either "top" or "bottom" for the x axis and "left" or "right" for the y axis.

view
     A three element vector specifying the view point for three-dimensional plots.

visible
     Either "on" or "off" to toggle display of the axes.

nextplot
     May be one of

     "new"

     "add"

     "replace"

     "replacechildren"

outerposition
     A four-element vector specifying the coordinates of the lower left corner and width and height of the plot, in normalized units.  For example, [0.2, 0.3, 0.4, 0.5] sets the lower left corner of the axes at (0.2, 0.3) and the width and heigth to be 0.4 and 0.5 respectively.

Line Properties
...............

xdata
ydata
zdata
ldata
udata
xldata
xudata
     The data to be plotted.  The ldata and udata elements are for errobars in the y direction, and the xldata and xudata elements are for errorbars in the x direction.

color
     The RGB color of the line, or a color name.  See Colors.

linestyle
linewidth
     See Line Styles.

marker

markeredgecolor

markerfacecolor

markersize
     See Marker Styles.

keylabel
     The text of the legend entry corresponding to this line.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

Text Properties
...............

string
     The character string contained by the text object.

units
     May be "normalized" or "graph".

position
     The coordinates of the text object.

rotation
     The angle of rotation for the displayed text, measured in degrees.

horizontalalignment
     May be "left", "center", or "right".

color
     The color of the text.  See Colors.

Image Properties
................

cdata
     The data for the image.  Each pixel of the image corresponds to an element of cdata.  The value of an element of cdata specifies the row-index into the colormap of the axes object containing the image.  The color value found in the color map for the given index determines the color of the pixel.

xdata
ydata
     Two-element vectors specifing the range of the x- and y- coordinates for the image.

Patch Properties
................

cdata
xdata
ydata
zdata
     Data defining the patch object.

facecolor
     The fill color of the patch.  See Colors.

facealpha
     A number in the range [0, 1] indicating the transparency of the patch.

edgecolor
     The color of the line defining the patch.  See Colors.

linestyle
linewidth
     See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     See Marker Styles.

Surface Properties
..................

xdata
ydata
zdata
     The data determining the surface.  The xdata and ydata elements are vectors and zdata must be a matrix.

keylabel
     The text of the legend entry corresponding to this surface.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

Colors
------

Colors may be specified as RGB triplets with values ranging from zero to one, or by name.  Recognized color names include "blue", "black", "cyan", "green", "magenta", "red", "white", and "yellow".

Line Styles
-----------

Line styles are specified by the folowing properties:

linestyle
     May be one of

     "-"
          Solid lines.

     "--"
          Dashed lines.

     ":"
          Points.

     "-."
          A dash-dot line.

linewidth
     A number specifying the width of the line.  The default is 1.  A value of 2 is twice as wide as the default, etc.

Marker Styles
-------------

Marker styles are specified by the folowing properties:

marker
     A character indicating a plot marker to be place at each data point, or "none", meaning no markers should be displayed.

markeredgecolor
     The color of the edge around the marker, or "auto", meaning that the edge color is the same as the face color.  See Colors.

markerfacecolor
     The color of the marker, or "none" to indicate that the marker should not be filled.  See Colors.

markersize
     A number specifying the size of the marker.  The default is 1.  A value of 2 is twice as large as the default, etc.

Interaction with gnuplot
------------------------

(gnuplot_binary)

(gnuplot_use_title_option)