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

@node Plotting
@chapter Plotting

All of Octave's plotting functions use @code{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 @sc{Matlab}. The use of these functions is generally
straightforward, and is the preferred method for generating plots.
However, for users familiar with @code{gnuplot}, or for some
specialized applications where the basic commands are inadequate,
Octave also provides two low-level functions, @code{gplot} and
@code{gsplot}, that behave almost exactly like the corresponding
@code{gnuplot} functions @code{plot} and @code{splot}. Also note that
some advanced @sc{Matlab} features from recent versions are not
implemented, such as handle-graphics and related functions.

@menu
* Two-Dimensional Plotting::    
* Specialized Two-Dimensional Plots::  
* Three-Dimensional Plotting::  
* Plot Annotations::            
* Multiple Plots on One Page::  
* Multiple Plot Windows::       
@c *Exporting Plots::
* Low-Level plotting commands::
* Interaction with gnuplot::    
@end menu

@node Two-Dimensional Plotting
@section Two-Dimensional Plotting

The @sc{Matlab}-style two-dimensional plotting commands are:

@cindex plotting
@cindex graphics

@DOCSTRING(plot)

@DOCSTRING(hold)

@DOCSTRING(ishold)

@DOCSTRING(clearplot)

@DOCSTRING(shg)

@DOCSTRING(closeplot)

@DOCSTRING(purge_tmp_files)

@DOCSTRING(axis)

@node Specialized Two-Dimensional Plots
@section Specialized Two-Dimensional Plots

@DOCSTRING(bar)

@DOCSTRING(contour)

@DOCSTRING(hist)

@DOCSTRING(loglog)

@DOCSTRING(polar)

@DOCSTRING(semilogx)

@DOCSTRING(semilogy)

@DOCSTRING(stairs)

@DOCSTRING(errorbar)

@DOCSTRING(loglogerr)

@DOCSTRING(semilogxerr)

@DOCSTRING(semilogyerr)

@node Three-Dimensional Plotting
@section Three-Dimensional Plotting

The @sc{Matlab}-style three-dimensional plotting commands are:

@DOCSTRING(mesh)

@DOCSTRING(meshgrid)

@DOCSTRING(meshdom)

@node Plot Annotations
@section Plot Annotations

@DOCSTRING(grid)

@DOCSTRING(title)

@DOCSTRING(xlabel)

@DOCSTRING(top_title)

@node Multiple Plots on One Page
@section Multiple Plots on One Page

The following functions all require a version of @code{gnuplot} that
supports the multiplot feature.

@DOCSTRING(mplot)

@DOCSTRING(multiplot)

@DOCSTRING(oneplot)

@DOCSTRING(plot_border)

@DOCSTRING(subplot)

@DOCSTRING(subwindow)

@node Multiple Plot Windows
@section Multiple Plot Windows

@DOCSTRING(figure)

@c @node Exporting Plots
@c XXX FIXME XXX -- add info about getting paper copies of plots.

@node Low-Level plotting commands
@section Low-Level plotting commands

@deffn {Command} gplot @var{ranges} @var{expression} @var{using} @var{title} @var{style}
Generate a 2-dimensional plot.

The @var{ranges}, @var{using}, @var{title}, and @var{style} arguments
are optional, and the @var{using}, @var{title} and @var{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 @var{ranges} has the syntax

@example
[ x_lo : x_up ] [ y_lo : y_up ]
@end example

@noindent
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 @code{[:]}
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. @code{[ 1, 2; 3, 4 ]}) since it is nearly impossible to
distinguish a plot range from a matrix of data.

See the help for @code{gnuplot} for a description of the syntax for the
optional items.

By default, the @code{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,

@example
gplot rand (100,1) with linespoints
@end example

@noindent
will plot 100 random values and connect them with lines.  When
@code{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 @var{using} qualifier. For
example, given the data

@example
x = (-10:0.1:10)';
data = [x, sin(x), cos(x)];
@end example

@noindent
the command

@example
gplot [-11:11] [-1.1:1.1] \
  data with lines, data using 1:3 with impulses
@end example

@noindent
will plot two lines.  The first line is generated by the command
@code{data with lines}, and is a graph of the sine function over the
range @minus{}10 to 10.  The data is taken from the first two columns of
the matrix because columns to plot were not specified with the
@var{using} qualifier.

The clause @code{using 1:3} in the second part of this plot command
specifies that the first and third columns of the matrix @code{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.
@end deffn

@deffn {Command} gsplot @var{ranges} @var{expression} @var{using} @var{title} @var{style}
Generate a 3-dimensional plot.

The @var{ranges}, @var{using}, @var{title}, and @var{style} arguments
are optional, and the @var{using}, @var{title} and @var{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 @var{ranges} has the syntax

@example
[ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]
@end example

@noindent
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
@code{[:]} 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.
@code{[ 1, 2; 3, 4 ]}) since it is nearly impossible to distinguish a
plot range from a matrix of data.

See the help for @code{gnuplot} for a description of the syntax for the
optional items.

By default, the @code{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,

@example
gsplot rand (5, 2)
@end example

@noindent
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
@kbd{gset parametric}, then @code{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 @code{parametric} set, it
makes sense to plot a matrix like
@iftex
@tex
$$
\left[\matrix{
1 & 1 & 3 & 2 & 1 & 6 & 3 & 1 & 9 \cr
1 & 2 & 2 & 2 & 2 & 5 & 3 & 2 & 8 \cr
1 & 3 & 1 & 2 & 3 & 4 & 3 & 3 & 7}\right]
$$
@end tex
@end iftex
@ifinfo

@example
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
@end example
@end ifinfo

@noindent
but not @code{rand (5, 30)}.
@end deffn

@deffn {Command} replot options
The @code{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 @code{replot} command also
accepts the same arguments as @code{gplot} or @code{gsplot} (except for
data ranges) so you can add additional lines to existing plots.  

For example,

@example
gset term tek40
gset output "/dev/plotter"
gset title "sine with lines and cosine with impulses"
replot "sin (x) w l"
@end example

will change the terminal type for plotting, add a title to the current
plot, add a graph of
@iftex
@tex
$\sin(x)$
@end tex
@end iftex
@ifinfo
sin (x) 
@end ifinfo
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.

@findex shg
The command @code{shg} is equivalent to executing @code{replot}.
@end deffn

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

@c XXX FIXME XXX -- add info about what to do to get plots on remote X
@c terminals.  People often forget how to properly set DISPLAY and run
@c xhost.


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

@DOCSTRING(gnuplot_binary)

@DOCSTRING(gnuplot_has_frames)

@DOCSTRING(gnuplot_command_plot)

@DOCSTRING(gnuplot_command_replot)

@DOCSTRING(gnuplot_command_splot)

@DOCSTRING(gnuplot_command_using)

@DOCSTRING(gnuplot_command_with)

@DOCSTRING(gnuplot_command_axes)

@DOCSTRING(gnuplot_command_title)

@DOCSTRING(gnuplot_command_end)