@c Copyright (C) 1996, 1997, 2007 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Plotting
@chapter Plotting
@cindex plotting
@cindex graphics

@menu
* Plotting Basics::             
* Advanced Plotting::           
@end menu

@node Plotting Basics
@section 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 @ref{Advanced Plotting}.

@menu
* Two-Dimensional Plots::       
* Three-Dimensional Plotting::  
* Plot Annotations::            
* Multiple Plots on One Page::  
* Multiple Plot Windows::       
* Printing Plots::              
* Test Plotting Functions::     
@end menu

@node Two-Dimensional Plots
@subsection Two-Dimensional Plots

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

@example
@group
x = -10:0.1:10;
plot (x, sin (x));
@end group
@end example

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

@float Figure,fig:plot
@image{plot,8cm}
@caption{Simple Two-Dimensional Plot.}
@end float

The function @code{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,

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

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

@DOCSTRING(plot)

@DOCSTRING(fplot)

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

@DOCSTRING(semilogx)

@DOCSTRING(semilogy)

@DOCSTRING(loglog)

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

@example
@group
hist (randn (10000, 1), 30);
@end group
@end example

@noindent
produces the histogram of 10,000 normally distributed random numbers
shown in @ref{fig:hist}.

@float Figure,fig:hist
@image{hist,8cm}
@caption{Histogram.}
@end float

@DOCSTRING(bar)

@DOCSTRING(barh)

@DOCSTRING(hist)

@DOCSTRING(stairs)

@DOCSTRING(stem)

The @code{contour} and @code{contourc} functions produce two-dimensional
contour plots from three dimensional data.

@DOCSTRING(contour)

@DOCSTRING(contourc)

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

@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);
@end example

@noindent
produces the figure shown in @ref{fig:errorbar}.

@float Figure,fig:errorbar
@image{errorbar,8cm}
@caption{Errorbar plot.}
@end float

@DOCSTRING(errorbar)

@DOCSTRING(semilogxerr)

@DOCSTRING(semilogyerr)

@DOCSTRING(loglogerr)

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

@example
polar (0:0.1:10*pi, 0:0.1:10*pi);
@end example

@noindent
produces the spiral plot shown in @ref{fig:polar}.

@float Figure,fig:polar
@image{polar,8cm}
@caption{Polar plot.}
@end float

@DOCSTRING(polar)

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

@DOCSTRING(axis)

@node Three-Dimensional Plotting
@subsection Three-Dimensional Plotting

The function @code{mesh} produces mesh surface plots.  For example,

@example
@group
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);
@end group
@end example

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

@float Figure,fig:mesh
@image{mesh,8cm}
@caption{Mesh plot.}
@end float

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

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

@example
@group
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);
@end group
@end example

@noindent
displays the spiral in three dimensions shown in @ref{fig:plot3}.

@float Figure,fig:plot3
@image{plot3,8cm}
@caption{Three dimensional spiral.}
@end float

Finally, the @code{view} function changes the viewpoint for
three-dimensional plots.

@DOCSTRING(mesh)

@DOCSTRING(meshc)

@DOCSTRING(meshgrid)

@DOCSTRING(ndgrid)

@DOCSTRING(plot3)

@DOCSTRING(view)

@node Plot Annotations
@subsection Plot Annotations

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

@example
@group
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)");
@end group
@end example

The functions @code{grid} and @code{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.

@DOCSTRING(title)

@DOCSTRING(legend)

@DOCSTRING(text)

@DOCSTRING(xlabel)

@DOCSTRING(box)

@DOCSTRING(grid)

@node Multiple Plots on One Page
@subsection 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 @code{subplot} function to divide the plot
area into a series of subplot windows that are indexed by an integer.
For example,

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

@noindent
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 @code{subplot} is
numbered in column-major order (top to bottom, left to right).

@DOCSTRING(subplot)

@node Multiple Plot Windows
@subsection Multiple Plot Windows

You can open multiple plot windows using the @code{figure} function.
For example

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

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

@DOCSTRING(figure)

@node Printing Plots
@subsection Printing Plots

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

@example
print -deps foo.eps
@end example

@noindent
writes the current figure to an encapsulated PostScript file called
@file{foo.eps}.

@DOCSTRING(print)

@DOCSTRING(orient)

@node Test Plotting Functions
@subsection Test Plotting Functions

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

@DOCSTRING(sombrero)

@DOCSTRING(peaks)

@node Advanced Plotting
@section Advanced Plotting

@menu
* Graphics Objects::
* Graphics Object Properties::  
* Managing Default Properties::  
* Colors::
* Line Styles::
* Marker Styles::
* Interaction with gnuplot::    
@end menu

@node Graphics Objects
@subsection Graphics Objects

Plots in Octave are constructed from the following @dfn{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 @dfn{handle}.

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

@item figure
A figure window.

@item 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.

@item line
A line in two or three dimensions.

@item text
Text annotations.

@item image
A bitmap image.

@item patch
A filled polygon, currently limited to two dimensions.

@item surface
A three-dimensional surface.
@end table

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

@DOCSTRING(ishandle)

@DOCSTRING(isfigure)

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

@DOCSTRING(gcf)

@DOCSTRING(gca)

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

@example
@group
get (0)
    @result{} ans =
       @{
         type = root figure
         currentfigure = [](0x0)
         children = [](0x0)
         visible = on
       @}
@end group
@end example

@noindent
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 @code{set} function.  Also, note that in this
case, the @code{currentfigure} property is empty, which indicates that
there is no current figure window.

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

@example
@group
get (gca (), "xlim")
    @result{} [ 0 1 ]
@end group
@end example

@noindent
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,

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

@noindent
sets the range of the x-axis for the current axes object in the current
figure to @samp{[-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,

@example
set (gca ())
@end example

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

@DOCSTRING(get)

@DOCSTRING(set)

@DOCSTRING(ancestor)

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

@DOCSTRING(axes)

@DOCSTRING(line)

@DOCSTRING(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
@code{drawnow} function.

@DOCSTRING(drawnow)

Normally, high-level plot functions like @code{plot} or @code{mesh} call
@code{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 @code{hold}
function.  For example,

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

@noindent
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.

@DOCSTRING(newplot)

@DOCSTRING(hold)

@DOCSTRING(ishold)

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

@DOCSTRING(clf)

@DOCSTRING(shg)

@DOCSTRING(delete)

@DOCSTRING(close)

@DOCSTRING(closereq)

@node Graphics Object Properties
@subsection Graphics Object Properties
@cindex graphics object properties

@menu
* Root Figure Properties::      
* Figure Properties::           
* Axes Properties::             
* Line Properties::             
* Text Properties::             
* Image Properties::            
* Patch Properties::            
* Surface Properties::          
@end menu

@node Root Figure Properties
@subsubsection Root Figure Properties

@table @code
@item currentfigure
Index to graphics object for the current figure.

@c FIXME -- does this work?
@c @item visible
@c Either @code{"on"} or @code{"off"} to toggle display of figures.
@end table

@node Figure Properties
@subsubsection Figure Properties

@table @code
@item nextplot
May be one of
@table @code
@item "new"
@item "add"
@item "replace"
@item "replacechildren"
@end table

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

@item currentaxes
Index to graphics object of current axes.

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

@item visible
Either @code{"on"} or @code{"off"} to toggle display of the figure.

@item paperorientation
Indicates the orientation for printing.  Either @code{"landscape"} or
@code{"portrait"}.
@end table

@node Axes Properties
@subsubsection Axes Properties

@table @code
@item 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, @code{[0.2, 0.3, 0.4, 0.5]} sets the lower left corner of the
axes at @math{(0.2, 0.3)} and the width and height to be 0.4 and 0.5
respectively.

@item title
Index of text object for the axes title.

@item box
Either @code{"on"} or @code{"off"} to toggle display of the box around
the axes.

@item key
Either @code{"on"} or @code{"off"} to toggle display of the legend.
Note that this property is not compatible with @sc{Matlab} and may be
removed in a future version of Octave.

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

@item 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 @sc{Matlab} and may be removed in a future version of
Octave.

@item dataaspectratio
A two-element vector specifying the relative height and width of the
data displayed in the axes.  Setting @code{dataaspectratio} to @samp{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
@code{dataaspectratio} also forces the @code{dataaspectratiomode}
property to be set to @code{"manual"}.

@item dataaspectratiomode
Either @code{"manual"} or @code{"auto"}.

@item xlim
@itemx ylim
@itemx zlim
@itemx 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 @code{"manual"}.

@item xlimmode
@itemx ylimmode
@itemx zlimmode
@itemx climmode
Either @code{"manual"} or @code{"auto"}.

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

@item xgrid
@itemx ygrid
@itemx zgrid
Either @code{"on"} or @code{"off"} to toggle display of grid lines.

@item xminorgrid
@itemx yminorgrid
@itemx zminorgrid
Either @code{"on"} or @code{"off"} to toggle display of minor grid lines.

@item xtick
@itemx ytick
@itemx ztick
Setting one of these properties also forces the corresponding mode
property to be set to @code{"manual"}.

@item xtickmode
@itemx ytickmode
@itemx ztickmode
Either @code{"manual"} or @code{"auto"}.

@item xticklabel
@itemx yticklabel
@itemx zticklabel
Setting one of these properties also forces the corresponding mode
property to be set to @code{"manual"}.

@item xticklabelmode
@itemx yticklabelmode
@itemx zticklabelmode
Either @code{"manual"} or @code{"auto"}.

@item xscale
@itemx yscale
@itemx zscale
Either @code{"linear"} or @code{"log"}.

@item xdir
@itemx ydir
@itemx zdir
Either @code{"forward"} or @code{"reverse"}.

@item xaxislocation
@itemx yaxislocation
Either @code{"top"} or @code{"bottom"} for the x axis and @code{"left"}
or @code{"right"} for the y axis.

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

@item visible
Either @code{"on"} or @code{"off"} to toggle display of the axes.

@item nextplot
May be one of
@table @code
@item "new"
@item "add"
@item "replace"
@item "replacechildren"
@end table

@item 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, @code{[0.2, 0.3, 0.4, 0.5]} sets the lower left corner of the
axes at @math{(0.2, 0.3)} and the width and height to be 0.4 and 0.5
respectively.
@end table

@node Line Properties
@subsubsection Line Properties

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

@item color
The RGB color of the line, or a color name.  @xref{Colors}.

@item linestyle
@itemx linewidth
@xref{Line Styles}.

@item marker
@item markeredgecolor
@item markerfacecolor
@item markersize
@xref{Marker Styles}.

@item keylabel
The text of the legend entry corresponding to this line.  Note that this
property is not compatible with @sc{Matlab} and may be removed in a
future version of Octave.
@end table

@node Text Properties
@subsubsection Text Properties

@table @code
@item string
The character string contained by the text object.

@item units
May be @code{"normalized"} or @code{"graph"}.

@item position
The coordinates of the text object.

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

@item horizontalalignment
May be @code{"left"}, @code{"center"}, or @code{"right"}.

@item color
The color of the text.  @xref{Colors}.
@end table

@node Image Properties
@subsubsection Image Properties

@table @code
@item cdata
The data for the image.  Each pixel of the image corresponds to an
element of @code{cdata}.  The value of an element of @code{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.

@item xdata
@itemx ydata
Two-element vectors specifying the range of the x- and y- coordinates for
the image.
@end table

@node Patch Properties
@subsubsection Patch Properties

@table @code
@item cdata
@itemx xdata
@itemx ydata
@itemx zdata
Data defining the patch object.

@item facecolor
The fill color of the patch.  @xref{Colors}.

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

@item edgecolor
The color of the line defining the patch.  @xref{Colors}.

@item linestyle
@itemx linewidth
@xref{Line Styles}.

@item marker
@itemx markeredgecolor
@itemx markerfacecolor
@itemx markersize
@xref{Marker Styles}.
@end table

@node Surface Properties
@subsubsection Surface Properties

@table @code
@item xdata
@itemx ydata
@itemx zdata
The data determining the surface.  The @code{xdata} and @code{ydata}
elements are vectors and @code{zdata} must be a matrix.

@item keylabel
The text of the legend entry corresponding to this surface.  Note that
this property is not compatible with @sc{Matlab} and may be removed in a
future version of Octave.
@end table

@node Managing Default Properties
@subsection Managing Default Properties

Object properties have two classes of default values, @dfn{factory
defaults} (the initial values) and @dfn{user-defined defaults}, which
may override the factory defaults.

Although default values may be set for any object, they are set in
parent objects and apply to child objects.  For example,

@example
set (0, "defaultlinecolor", "green");
@end example

@noindent
sets the default line color for all objects.  The rule for constructing
the property name to set a default value is

@example
default + @var{object-type} + @var{property-name}
@end example

This rule can lead to some strange looking names, for example
@code{defaultlinelinewidth"} specifies the default @code{linewidth}
property for @code{line} objects.

The example above used the root figure object, 0, so the default
property value will apply to all line objects.  However, default values
are hierarchical, so defaults set in a figure objects override those
set in the root figure object.  Likewise, defaults set in axes objects
override those set in figure or root figure objects.  For example,

@example
@group
subplot (2, 1, 1);
set (0, "defaultlinecolor", "red");
set (1, "defaultlinecolor", "green");
set (gca (), "defaultlinecolor", "blue");
line (1:10, rand (1, 10));
subplot (2, 1, 2);
line (1:10, rand (1, 10));
figure (2)
line (1:10, rand (1, 10));
@end group
@end example

@noindent
produces two figures.  The line in first subplot window of the first
figure is blue because it inherits its color from its parent axes
object.  The line in the second subplot window of the first figure is
green because it inherits its color from its parent figure object.  The
line in the second figure window is red because it inherits its color
from the global root figure parent object.

To remove a user-defined default setting, set the default property to
the value @code{"remove"}.  For example,

@example
set (gca (), "defaultlinecolor", "remove");
@end example

@noindent
removes the user-defined default line color setting from the current axes
object.

Getting the @code{"default"} property of an object returns a list of
user-defined defaults set for the object.  For example,

@example
get (gca (), "default");
@end example

@noindent
returns a list of user-defined default values for the current axes
object.

Factory default values are stored in the root figure object.  The
command

@example
get (0, "factory");
@end example

@noindent
returns a list of factory defaults.

@node Colors
@subsection Colors

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

@node Line Styles
@subsection Line Styles
Line styles are specified by the following properties:

@table @code
@item linestyle
May be one of
@table @code
@item "-"
Solid lines.
@item "--"
Dashed lines.
@item ":"
Points.
@item "-."
A dash-dot line.
@end table

@item 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.
@end table

@node Marker Styles
@subsection Marker Styles
Marker styles are specified by the following properties:
@table @code
@item marker
A character indicating a plot marker to be place at each data point, or
@code{"none"}, meaning no markers should be displayed.

@itemx markeredgecolor
The color of the edge around the marker, or @code{"auto"}, meaning that
the edge color is the same as the face color.  @xref{Colors}.

@itemx markerfacecolor
The color of the marker, or @code{"none"} to indicate that the marker
should not be filled.  @xref{Colors}.

@itemx 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.
@end table

@node Interaction with gnuplot
@subsection Interaction with @code{gnuplot}

@DOCSTRING(gnuplot_binary)

@DOCSTRING(gnuplot_use_title_option)