octave_packages/m/plot/stem.m

   1 ## Copyright (C) 2006-2012 Michel D. Schmid
   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} {} stem (@var{x})
  21 ## @deftypefnx {Function File} {} stem (@var{x}, @var{y})
  22 ## @deftypefnx {Function File} {} stem (@var{x}, @var{y}, @var{linespec})
  23 ## @deftypefnx {Function File} {} stem (@dots{}, "filled")
  24 ## @deftypefnx {Function File} {@var{h} =} stem (@dots{})
  25 ## Plot a stem graph from two vectors of x-y data.  If only one argument
  26 ## is given, it is taken as the y-values and the x coordinates are taken
  27 ## from the indices of the elements.
  28 ##
  29 ## If @var{y} is a matrix, then each column of the matrix is plotted as
  30 ## a separate stem graph.  In this case @var{x} can either be a vector,
  31 ## the same length as the number of rows in @var{y}, or it can be a
  32 ## matrix of the same size as @var{y}.
  33 ##
  34 ## The default color is @code{"b"} (blue).  The default line style is
  35 ## @code{"-"} and the default marker is @code{"o"}.  The line style can
  36 ## be altered by the @code{linespec} argument in the same manner as the
  37 ## @code{plot} command.  For example,
  38 ##
  39 ## @example
  40 ## @group
  41 ## x = 1:10;
  42 ## y = 2*x;
  43 ## stem (x, y, "r");
  44 ## @end group
  45 ## @end example
  46 ##
  47 ## @noindent
  48 ## plots 10 stems with heights from 2 to 20 in red;
  49 ##
  50 ## The optional return value @var{h} is a vector of "stem series" graphics
  51 ## handles with one handle per column of the variable @var{y}.  The
  52 ## handle regroups the elements of the stem graph together as the
  53 ## children of the "stem series" handle, allowing them to be altered
  54 ## together.  For example,
  55 ##
  56 ## @example
  57 ## @group
  58 ## x = [0:10]';
  59 ## y = [sin(x), cos(x)]
  60 ## h = stem (x, y);
  61 ## set (h(2), "color", "g");
  62 ## set (h(1), "basevalue", -1)
  63 ## @end group
  64 ## @end example
  65 ##
  66 ## @noindent
  67 ## changes the color of the second "stem series" and moves the base line
  68 ## of the first.
  69 ## @seealso{bar, barh, plot}
  70 ## @end deftypefn
  71
  72 ## Author: Michel D. Schmid <michaelschmid@users.sourceforge.net>
  73 ## Adapted-by: jwe
  74
  75 function h = stem (varargin)
  76
  77   if (nargin < 1)
  78     print_usage ();
  79   endif
  80
  81   tmp = __stem__ (false, varargin{:});
  82
  83   if (nargout > 0)
  84     h = tmp;
  85   endif
  86
  87 endfunction
  88
  89
  90 %!demo
  91 %! clf
  92 %! x = 1:10;
  93 %! stem (x);
  94
  95 %!demo
  96 %! clf
  97 %! x = 1:10;
  98 %! y = 2*x;
  99 %! stem (x, y);
 100
 101 %!demo
 102 %! clf
 103 %! x = 1:10;
 104 %! y = 2*x;
 105 %! h = stem (x, y, "r");
 106
 107 %!demo
 108 %! clf
 109 %! x = 1:10;
 110 %! y = 2*x;
 111 %! h = stem (x, y, "-.k");
 112
 113 %!demo
 114 %! clf
 115 %! x = 1:10;
 116 %! y = 2*x;
 117 %! h = stem (x, y, "-.k.");
 118
 119 %!demo
 120 %! clf
 121 %! x = 1:10;
 122 %! y = 2*x;
 123 %! h = stem (x, y, "filled");
 124
 125 %!demo
 126 %! clf
 127 %! x = [0 : 10]';
 128 %! y = [sin(x), cos(x)];
 129 %! h = stem (x, y);
 130 %! set (h(2), "color", "g");
 131 %! set (h(1), "basevalue", -1)
 132