Mercurial > hg > octave-lyh
diff doc/interpreter/plot.txi @ 3368:a4cd1e9d9962
[project @ 1999-11-20 17:22:48 by jwe]
author | jwe |
---|---|
date | Sat, 20 Nov 1999 17:23:01 +0000 |
parents | bfe1573bd2ae |
children | 5b77cf82393c |
line wrap: on
line diff
--- a/doc/interpreter/plot.txi +++ b/doc/interpreter/plot.txi @@ -162,12 +162,7 @@ any arguments. @end deffn -@defvr {Built-in Variable} automatic_replot -You can tell Octave to redisplay the plot each time anything about it -changes by setting the value of the builtin variable -@code{automatic_replot} to a nonzero value. Since this is fairly -inefficient, the default value is 0. -@end defvr +@DOCSTRING(automatic_replot) Note that NaN values in the plot data are automatically omitted, and Inf values are converted to a very large value before calling gnuplot. @@ -183,308 +178,38 @@ @cindex plotting @cindex graphics -@deftypefn {Function File} {} plot (@var{args}) -This function produces two-dimensional plots. Many different -combinations of arguments are possible. The simplest form is - -@example -plot (@var{y}) -@end example - -@noindent -where the argument is taken as the set of @var{y} coordinates and the -@var{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 - -@example -plot (@var{x}, @var{y}, @var{fmt} ...) -@end example - -@noindent -where @var{y} and @var{fmt} are optional, and any number of argument -sets may appear. The @var{x} and @var{y} values are -interpreted as follows: - -@itemize @bullet -@item -If a single data argument is supplied, it is taken as the set of @var{y} -coordinates and the @var{x} coordinates are taken to be the indices of -the elements, starting with 1. - -@item -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.) - -@item -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.) - -@item -If both arguments are vectors, the elements of @var{y} are plotted versus -the elements of @var{x}. +@DOCSTRING(plot) -@item -If both arguments are matrices, the columns of @var{y} are plotted -versus the columns of @var{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. -@end itemize - -The @var{fmt} argument, if present is interpreted as follows. If -@var{fmt} is missing, the default gnuplot line style is assumed. - -@table @samp -@item - -Set lines plot style (default). - -@item . -Set dots plot style. - -@item @@ -Set points plot style. - -@item -@@ -Set linespoints plot style. +@DOCSTRING(hold) -@item ^ -Set impulses plot style. - -@item L -Set steps plot style. - -@item # -Set boxes plot style. - -@item ~ -Set errorbars plot style. - -@item #~ -Set boxerrorbars plot style. - -@item @var{n} -Interpreted as the plot color if @var{n} is an integer in the range 1 to -6. - -@item @var{nm} -If @var{nm} is a two digit integer and @var{m} is an integer in the -range 1 to 6, @var{m} is interpreted as the point style. This is only -valid in combination with the @code{@@} or @code{-@@} specifiers. - -@item @var{c} -If @var{c} is one of @code{"r"}, @code{"g"}, @code{"b"}, @code{"m"}, -@code{"c"}, or @code{"w"}, it is interpreted as the plot color (red, -green, blue, magenta, cyan, or white). +@DOCSTRING(ishold) -@item + -@itemx * -@itemx o -@itemx x -Used in combination with the points or linespoints styles, set the point -style. -@end table - -The color line styles have the following meanings on terminals that -support color. - -@example -Number Gnuplot colors (lines)points style - 1 red * - 2 green + - 3 blue o - 4 magenta x - 5 cyan house - 6 brown there exists -@end example - -Here are some plot examples: +@DOCSTRING(clearplot) -@example -plot (x, y, "@@12", x, y2, x, y3, "4", x, y4, "+") -@end example - -This command will plot @code{y} with points of type 2 (displayed as -@samp{+}) and color 1 (red), @code{y2} with lines, @code{y3} with lines of -color 4 (magenta) and @code{y4} with points displayed as @samp{+}. - -@example -plot (b, "*") -@end example - -This command will plot the data in the variable @code{b} will be plotted -with points displayed as @samp{*}. -@end deftypefn - -@deftypefn {Function File} {} hold @var{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 - -@example -hold on -@end example +@DOCSTRING(closeplot) -@noindent -turns the hold state on. An argument of @code{off} turns the hold state -off, and @code{hold} with no arguments toggles the current hold state. -@end deftypefn - -@deftypefn {Function File} {} 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. -@end deftypefn - -@deftypefn {Function File} {} clearplot -@deftypefnx {Function File} {} clg -Clear the plot window and any titles or axis labels. The name -@code{clg} is aliased to @code{clearplot} for compatibility with @sc{Matlab}. - -The commands @kbd{gplot clear}, @kbd{gsplot clear}, and @kbd{replot -clear} are equivalent to @code{clearplot}. (Previously, commands like -@kbd{gplot clear} would evaluate @code{clear} as an ordinary expression -and clear all the visible variables.) -@end deftypefn - -@deftypefn {Function File} {} closeplot -Close stream to the @code{gnuplot} subprocess. If you are using X11, -this will close the plot window. -@end deftypefn +@DOCSTRING(purge_tmp_files) -@deftypefn {Function File} {} purge_tmp_files -Delete the temporary files created by the plotting commands. - -Octave creates temporary data files for @code{gnuplot} and then sends -commands to @code{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. -@end deftypefn - -@deftypefn {Function File} {} axis (@var{limits}) -Sets the axis limits for plots. - -The argument @var{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. - -With no arguments, @code{axis} turns autoscaling on. - -If your plot is already drawn, then you need to use @code{replot} before -the new axis limits will take effect. You can get this to happen -automatically by setting the built-in variable @code{automatic_replot} -to a nonzero value. -@end deftypefn +@DOCSTRING(axis) @node Specialized Two-Dimensional Plots, Three-Dimensional Plotting, Two-Dimensional Plotting, Plotting @section Specialized Two-Dimensional Plots -@deftypefn {Function File} {} bar (@var{x}, @var{y}) -Given two vectors of x-y data, @code{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, +@DOCSTRING(bar) -@example -bar (x, y); -@end example - -@noindent -and - -@example -[xb, yb] = bar (x, y); -plot (xb, yb); -@end example +@DOCSTRING(contour) -@noindent -are equivalent. -@end deftypefn - -@deftypefn {Function File} {} contour (@var{z}, @var{n}, @var{x}, @var{y}) -Make a contour plot of the three-dimensional surface described by -@var{z}. Someone needs to improve @code{gnuplot}'s contour routines -before this will be very useful. -@end deftypefn +@DOCSTRING(hist) -@deftypefn {Function File} {} hist (@var{y}, @var{x}) -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. - -Extreme values are lumped in the first and last bins. +@DOCSTRING(loglog) -With two output arguments, produce the values @var{nn} and @var{xx} such -that @code{bar (@var{xx}, @var{nn})} will plot the histogram. -@end deftypefn - -@deftypefn {Function File} {} loglog (@var{args}) -Make a two-dimensional plot using log scales for both axes. See the -description of @code{plot} above for a description of the arguments that -@code{loglog} will accept. -@end deftypefn +@DOCSTRING(polar) -@deftypefn {Function File} {} polar (@var{theta}, @var{rho}) -Make a two-dimensional plot given polar the coordinates @var{theta} and -@var{rho}. -@end deftypefn - -@deftypefn {Function File} {} semilogx (@var{args}) -Make a two-dimensional plot using a log scale for the @var{x} axis. See -the description of @code{plot} above for a description of the arguments -that @code{semilogx} will accept. -@end deftypefn +@DOCSTRING(semilogx) -@deftypefn {Function File} {} semilogy (@var{args}) -Make a two-dimensional plot using a log scale for the @var{y} axis. See -the description of @code{plot} above for a description of the arguments -that @code{semilogy} will accept. -@end deftypefn - -@deftypefn {Function File} {} stairs (@var{x}, @var{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, +@DOCSTRING(semilogy) -@example -stairs (x, y); -@end example - -@noindent -and - -@example -[xs, ys] = stairs (x, y); -plot (xs, ys); -@end example - -@noindent -are equivalent. -@end deftypefn +@DOCSTRING(stairs) @node Three-Dimensional Plotting, Plot Annotations, Specialized Two-Dimensional Plots, Plotting @section Three-Dimensional Plotting @@ -563,66 +288,26 @@ The @sc{Matlab}-style three-dimensional plotting commands are: -@deftypefn {Function File} {} mesh (@var{x}, @var{y}, @var{z}) -Plot a mesh given matrices @code{x}, and @var{y} from @code{meshdom} and -a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of -the mesh. -@end deftypefn +@DOCSTRING(mesh) -@deftypefn {Function File} {} meshdom (@var{x}, @var{y}) -Given vectors of @var{x} and @var{y} coordinates, return two matrices -corresponding to the @var{x} and @var{y} coordinates of the mesh. +@DOCSTRING(meshdom) -See the file @file{sombrero.m} for an example of using @code{mesh} and -@code{meshdom}. -@end deftypefn - -@defvr {Built-in Variable} gnuplot_binary -The name of the program invoked by the plot command. The default value -is @code{"gnuplot"}. @xref{Installation}. -@end defvr +@DOCSTRING(gnuplot_binary) -@defvr {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. It's 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. -@end defvr +@DOCSTRING(gnuplot_has_frames) -@deftypefn {Function File} {} figure (@var{n}) -Set the current plot window to plot window @var{n}. This function -currently requires X11 and a version of gnuplot that supports multiple -frames. -@end deftypefn +@DOCSTRING(figure) -@defvr {Built-in Variable} gnuplot_has_multiplot -If the value of this variable is nonzero, Octave assumes that your copy -of gnuplot has the multiplot support that is included in recent -3.6beta releases. It's 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. -@end defvr +@DOCSTRING(gnuplot_has_multiplot) @node Plot Annotations, Multiple Plots on One Page, Three-Dimensional Plotting, Plotting @section Plot Annotations -@deftypefn {Function File} {} grid -For two-dimensional plotting, force the display of a grid on the plot. -@end deftypefn +@DOCSTRING(grid) -@deftypefn {Function File} {} title (@var{string}) -Specify a title for the plot. If you already have a plot displayed, use -the command @code{replot} to redisplay it with the new title. -@end deftypefn +@DOCSTRING(title) -@deftypefn {Function File} {} xlabel (@var{string}) -@deftypefnx {Function File} {} ylabel (@var{string}) -@deftypefnx {Function File} {} zlabel (@var{string}) -Specify x, y, and z axis labels for the plot. If you already have a plot -displayed, use the command @code{replot} to redisplay it with the new -labels. -@end deftypefn +@DOCSTRING(xlabel) @node Multiple Plots on One Page, , Plot Annotations, Plotting @section Multiple Plots on One Page @@ -630,118 +315,16 @@ The following functions all require a version of @code{gnuplot} that supports the multiplot feature. -@deftypefn {Function File} {} mplot (@var{x}, @var{y}) -@deftypefnx {Function File} {} mplot (@var{x}, @var{y}, @var{fmt}) -@deftypefnx {Function File} {} mplot (@var{x1}, @var{y1}, @var{x2}, @var{y2}) -This is a modified version of the @code{plot} function that works with -the multiplot version of @code{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 @var{plot} function for the various options. -@end deftypefn - -@deftypefn {Function File} {} multiplot (@var{xn}, @var{yn}) -Sets and resets multiplot mode. - -If the arguments are non-zero, @code{multiplot} will set up multiplot -mode with @var{xn}, @var{yn} subplots along the @var{x} and @var{y} -axes. If both arguments are zero, @code{multiplot} closes multiplot -mode. -@end deftypefn - -@deftypefn {Function File} {} oneplot () -If in multiplot mode, switches to single plot mode. -@end deftypefn - -@deftypefn {Function File} {} plot_border (...) -Multiple arguments allowed to specify the sides on which the border -is shown. Allowed arguments include: +@DOCSTRING(mplot) -@table @code -@item "blank" -No borders displayed. - -@item "all" -All borders displayed - -@item "north" -North Border - -@item "south" -South Border +@DOCSTRING(multiplot) -@item "east" -East Border - -@item "west" -West Border -@end table - -@noindent -The arguments may be abbreviated to single characters. Without any -arguments, @code{plot_border} turns borders off. -@end deftypefn - -@deftypefn {Function File} {} subplot (@var{rows}, @var{cols}, @var{index}) -@deftypefnx {Function File} {} subplot (@var{rcn}) -Sets @code{gnuplot} in multiplot mode and plots in location -given by index (there are @var{cols} by @var{rows} subwindows). +@DOCSTRING(oneplot) -Input: - -@table @var -@item rows -Number of rows in subplot grid. - -@item columns -Number of columns in subplot grid. +@DOCSTRING(plot_border) -@item index -Index of subplot where to make the next plot. -@end table - -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. +@DOCSTRING(subplot) -For example, a plot with 4 by 2 grid will have plot indices running as -follows: -@iftex -@tex -\vskip 10pt -\hfil\vbox{\offinterlineskip\hrule -\halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr -height13pt&1&2&3&4\cr height12pt&&&&\cr\noalign{\hrule} -height13pt&5&6&7&8\cr height12pt&&&&\cr\noalign{\hrule}}} -\hfil -\vskip 10pt -@end tex -@end iftex -@ifinfo -@display -@group -+-----+-----+-----+-----+ -| 1 | 2 | 3 | 4 | -+-----+-----+-----+-----+ -| 5 | 6 | 7 | 8 | -+-----+-----+-----+-----+ -@end group -@end display -@end ifinfo -@end deftypefn +@DOCSTRING(subwindow) -@deftypefn {Function File} {} subwindow (@var{xn}, @var{yn}) -Sets the subwindow position in multiplot mode for the next plot. The -multiplot mode has to be previously initialized using the -@code{multiplot} function, otherwise this command just becomes an alias -to @code{multiplot} -@end deftypefn - -@deftypefn {Function File} {} top_title (@var{string}) -@deftypefnx {Function File} {} bottom_title (@var{string}) -Makes a title with text @var{string} at the top (bottom) of the plot. -@end deftypefn +@DOCSTRING(top_title)