octave_packages/m/plot/plot.m

   1 ## Copyright (C) 1993-2012 John W. Eaton
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {} plot (@var{y})
  21 ## @deftypefnx {Function File} {} plot (@var{x}, @var{y})
  22 ## @deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
  23 ## @deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{fmt})
  24 ## @deftypefnx {Function File} {} plot (@var{h}, @dots{})
  25 ## @deftypefnx {Function File} {@var{h} =} plot (@dots{})
  26 ## Produce two-dimensional plots.
  27 ##
  28 ## Many different combinations of arguments are possible.  The simplest
  29 ## form is
  30 ##
  31 ## @example
  32 ## plot (@var{y})
  33 ## @end example
  34 ##
  35 ## @noindent
  36 ## where the argument is taken as the set of @var{y} coordinates and the
  37 ## @var{x} coordinates are taken to be the indices of the elements
  38 ## starting with 1.
  39 ##
  40 ## To save a plot, in one of several image formats such as PostScript
  41 ## or PNG, use the @code{print} command.
  42 ##
  43 ## If more than one argument is given, they are interpreted as
  44 ##
  45 ## @example
  46 ## plot (@var{y}, @var{property}, @var{value}, @dots{})
  47 ## @end example
  48 ##
  49 ## @noindent
  50 ## or
  51 ##
  52 ## @example
  53 ## plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
  54 ## @end example
  55 ##
  56 ## @noindent
  57 ## or
  58 ##
  59 ## @example
  60 ## plot (@var{x}, @var{y}, @var{fmt}, @dots{})
  61 ## @end example
  62 ##
  63 ## @noindent
  64 ## and so on.  Any number of argument sets may appear.  The @var{x} and
  65 ## @var{y} values are interpreted as follows:
  66 ##
  67 ## @itemize @bullet
  68 ## @item
  69 ## If a single data argument is supplied, it is taken as the set of @var{y}
  70 ## coordinates and the @var{x} coordinates are taken to be the indices of
  71 ## the elements, starting with 1.
  72 ##
  73 ## @item
  74 ## If the @var{x} is a vector and @var{y} is a matrix, then
  75 ## the columns (or rows) of @var{y} are plotted versus @var{x}.
  76 ## (using whichever combination matches, with columns tried first.)
  77 ##
  78 ## @item
  79 ## If the @var{x} is a matrix and @var{y} is a vector,
  80 ## @var{y} is plotted versus the columns (or rows) of @var{x}.
  81 ## (using whichever combination matches, with columns tried first.)
  82 ##
  83 ## @item
  84 ## If both arguments are vectors, the elements of @var{y} are plotted versus
  85 ## the elements of @var{x}.
  86 ##
  87 ## @item
  88 ## If both arguments are matrices, the columns of @var{y} are plotted
  89 ## versus the columns of @var{x}.  In this case, both matrices must have
  90 ## the same number of rows and columns and no attempt is made to transpose
  91 ## the arguments to make the number of rows match.
  92 ##
  93 ## If both arguments are scalars, a single point is plotted.
  94 ## @end itemize
  95 ##
  96 ## Multiple property-value pairs may be specified, but they must appear
  97 ## in pairs.  These arguments are applied to the lines drawn by
  98 ## @code{plot}.
  99 ##
 100 ## If the @var{fmt} argument is supplied, it is interpreted as
 101 ## follows.  If @var{fmt} is missing, the default gnuplot line style
 102 ## is assumed.
 103 ##
 104 ## @table @samp
 105 ## @item -
 106 ## Set lines plot style (default).
 107 ##
 108 ## @item .
 109 ## Set dots plot style.
 110 ##
 111 ## @item @var{n}
 112 ## Interpreted as the plot color if @var{n} is an integer in the range 1 to
 113 ## 6.
 114 ##
 115 ## @item @var{nm}
 116 ## If @var{nm} is a two digit integer and @var{m} is an integer in the
 117 ## range 1 to 6, @var{m} is interpreted as the point style.  This is only
 118 ## valid in combination with the @code{@@} or @code{-@@} specifiers.
 119 ##
 120 ## @item @var{c}
 121 ## If @var{c} is one of @code{"k"} (black), @code{"r"} (red), @code{"g"}
 122 ## (green), @code{"b"} (blue), @code{"m"} (magenta), @code{"c"} (cyan),
 123 ## or @code{"w"} (white), it is interpreted as the line plot color.
 124 ##
 125 ## @item ";title;"
 126 ## Here @code{"title"} is the label for the key.
 127 ##
 128 ## @item +
 129 ## @itemx *
 130 ## @itemx o
 131 ## @itemx x
 132 ## @itemx ^
 133 ## Used in combination with the points or linespoints styles, set the point
 134 ## style.
 135 ##
 136 ## @item @@
 137 ## Select the next unused point style.
 138 ## @end table
 139 ##
 140 ## The @var{fmt} argument may also be used to assign key titles.
 141 ## To do so, include the desired title between semi-colons after the
 142 ## formatting sequence described above, e.g., "+3;Key Title;"
 143 ## Note that the last semi-colon is required and will generate an error if
 144 ## it is left out.
 145 ##
 146 ## Here are some plot examples:
 147 ##
 148 ## @example
 149 ## plot (x, y, "@@12", x, y2, x, y3, "4", x, y4, "+")
 150 ## @end example
 151 ##
 152 ## This command will plot @code{y} with points of type 2 (displayed as
 153 ## @samp{+}) and color 1 (red), @code{y2} with lines, @code{y3} with lines of
 154 ## color 4 (magenta) and @code{y4} with points displayed as @samp{+}.
 155 ##
 156 ## @example
 157 ## plot (b, "*", "markersize", 3)
 158 ## @end example
 159 ##
 160 ## This command will plot the data in the variable @code{b},
 161 ## with points displayed as @samp{*} with a marker size of 3.
 162 ##
 163 ## @example
 164 ## @group
 165 ## t = 0:0.1:6.3;
 166 ## plot (t, cos(t), "-;cos(t);", t, sin(t), "+3;sin(t);");
 167 ## @end group
 168 ## @end example
 169 ##
 170 ## This will plot the cosine and sine functions and label them accordingly
 171 ## in the key.
 172 ##
 173 ## If the first argument is an axis handle, then plot into these axes,
 174 ## rather than the current axis handle returned by @code{gca}.
 175 ##
 176 ## The optional return value @var{h} is a graphics handle to the created plot.
 177 ##
 178 ## @seealso{semilogx, semilogy, loglog, polar, mesh, contour, bar,
 179 ## stairs, errorbar, xlabel, ylabel, title, print}
 180 ## @end deftypefn
 181
 182 ## Author: jwe
 183
 184 function retval = plot (varargin)
 185
 186   [h, varargin, nargs] = __plt_get_axis_arg__ ("plot", varargin{:});
 187
 188   if (nargs < 1)
 189     print_usage();
 190   endif
 191
 192   oldh = gca ();
 193   unwind_protect
 194     axes (h);
 195     newplot ();
 196     tmp = __plt__ ("plot", h, varargin{:});
 197   unwind_protect_cleanup
 198     axes (oldh);
 199   end_unwind_protect
 200
 201   if (nargout > 0)
 202     retval = tmp;
 203   endif
 204
 205 endfunction
 206
 207
 208 %% FIXME: Need demo or test for function
 209