stem3 function

[David Bateman]

Here is a patch that adds the stem3 function, by generalizing the stem
function to 3D and using the resulting function for both stem and stem3.

D.

*** ./scripts/plot/stem.m.orig34        2007-11-29 17:30:59.111640347 +0100
--- ./scripts/plot/stem.m       2007-11-29 17:25:09.685762124 +0100
***************
*** 94,282 ****
  
  function h = stem (varargin)
  
!   if (nargin < 1 || nargin > 4)
!     print_usage ();
!   endif
! 
!   [x, y, dofill, lc, ls, mc, ms] = check_stem_arg (varargin{:});
! 
!   if (dofill)
!     fc = mc;
!   else
!     fc = "none";
!   endif
! 
!   newplot ();
!   nx = numel (x);
!   xt = x(:)';
!   xt = [xt; xt; NaN(1, nx)](:);
!   yt = y(:)';
!   yt = [zeros(1, nx); yt; NaN(1, nx)](:);
!   h_stems = plot (xt, yt, "color", lc, "linestyle", ls,
!                 x, y, "color", mc, "marker", ms, "linestyle", "",
!                 "markerfacecolor", fc);
! 
!   ## Must draw the plot first to get proper x limits.
!   drawnow();
!   x_axis_range = get (gca, "xlim");
!   h_baseline = line (x_axis_range, [0, 0], "color", [0, 0, 0]);
  
    if (nargout > 0)
!     h = [h_stems; h_baseline];
!   endif
! 
! endfunction
! 
! function [x, y, dofill, lc, ls, mc, ms] = check_stem_arg (varargin)
! 
!   ## set specifiers to default values
!   [lc, ls, mc, ms] = set_default_values ();
!   dofill = 0;
!   fill_2 = 0;
!   linespec_2 = 0;
! 
!   ## check input arguments
!   if (nargin == 1)
!     y = varargin{1};
!     if (isvector (y))
!       x = 1:length(y);
!     elseif (ismatrix (y))
!       x = 1:rows(y);
!     else 
!       error ("stem: Y must be a matrix");
!     endif # in each case, x & y will be defined
! 
!   elseif (nargin == 2)
!     ## several possibilities
!     ## 1. the real y data
!     ## 2. 'fill'
!     ## 3. line spec
!     if (ischar (varargin{2}))
!       ## only 2. or 3. possible
!       if (strcmp ("fill", varargin{2}))
!       dofill = 1;
!       else
!       ## parse the linespec
!       [lc, ls, mc, ms] = stem_line_spec (varargin{2});
!       endif
!       y = varargin{1};
!       if (isvector (y))
!       x = 1:length(y);
!       elseif (ismatrix (y))
!       x = 1:rows(y);
!       else
!       error ("stem: Y must be a matrix");
!       endif # in each case, x & y will be defined
!     else
!       ## must be the real y data
!       x = varargin{1};
!       y = varargin{2};
!       if (! (ismatrix (x) && ismatrix (y)))
!       error ("stem: X and Y must be matrices");
!       endif
!     endif
!   elseif (nargin == 3)
!     ## again several possibilities
!     ## arg2 1. real y
!     ## arg2 2. 'fill' or linespec
!     ## arg3 1. 'fill' or linespec
!     if (ischar (varargin{2}))
!       ## only arg2 2. / arg3 1. & arg3 3. are possible
!       if (strcmp ("fill", varargin{2}))
!       dofill = 1;
!       fill_2 = 1; # be sure, no second "fill" is in the arguments
!       else
!       ## must be a linespec
!       [lc, ls, mc, ms] = stem_line_spec (varargin{2});
!       linespec_2 = 1;
!       endif
!       y = varargin{1};
!       if (isvector (y))
!       x = 1:length(y);
!       elseif (ismatrix (y))
!       x = 1:size(y,1);
!       else
!       error ("stem: Y must be a matrix");
!       endif # in each case, x & y will be defined
!     else
!       ## must be the real y data
!       x = varargin{1};
!       y = varargin{2};
!       if (! (ismatrix (x) && ismatrix (y)))
!       error ("stem: X and Y must be matrices");
!       endif
!     endif # if ischar(varargin{2})
!     ## varargin{3} must be char...
!     ## check for "fill" ..
!     if (strcmp ("fill", varargin{3}) & fill_2)
!       error ("stem:check_stem_arg: duplicate fill argument");
!     elseif (strcmp("fill", varargin{3}) & linespec_2)
!       # must be "fill"
!       dofill = 1;
!       fill_2 = 1;
!     elseif (strcmp ("fill", varargin{3}) & ! linespec_2)
!       ## must be "fill"
!       dofill = 1;
!       fill_2 = 1;
!     elseif (! linespec_2)
!       ## must be linespec
!       [lc, ls, mc, ms] = stem_line_spec (varargin{3});
!       linespec_2 = 1;
!     endif
!   elseif (nargin == 4)
!     x = varargin{1};
!     y = varargin{2};
!     if (! (ismatrix (x) && ismatrix (y)))
!       error ("X and Y must be matrices");
!     endif
! 
!     if (strcmp ("fill", varargin{3}))
!       dofill = 1;
!       fill_2 = 1; # be sure, no second "fill" is in the arguments
!     else
!       ## must be a linespec
!       [lc, ls, mc, ms] = stem_line_spec (varargin{3});
!       linespec_2 = 1;
!     endif
! 
!     ## check for "fill" ..
!     if (strcmp ("fill", varargin{4}) & fill_2)
!       error ("stem:check_stem_arg: duplicate fill argument");
!     elseif (strcmp ("fill", varargin{4}) & linespec_2)
!       ## must be "fill"
!       dofill = 1;
!       fill_2 = 1;
!     elseif (! strcmp ("fill", varargin{4}) & ! linespec_2)
!       ## must be linespec
!       [lc, ls, mc, ms] = stem_line_spec (varargin{4});
!       linespec_2 = 1;
!     endif
    endif
  
  endfunction
- 
- function [lc, ls, mc, ms] = stem_line_spec (str)
-   if (! ischar (str))
-     error ("stem:stem_line_spec: wrong argument type, must be \"fill\" or a 
string of specifiers");
-   endif
-   [lc, ls, mc, ms] = set_default_values ();
-   ## Parse the line specifier string.
-   cur_props = __pltopt__ ("stem", str, false);
-   for i = 1:length(cur_props)
-     if (isfield (cur_props(i), "color") && ! isempty (cur_props(i).color)); # 
means line color
-       mc = lc = cur_props(i).color;
-     elseif (isfield (cur_props(i), "linestyle"))
-       ls = cur_props(i).linestyle;
-     elseif (isfield (cur_props(i), "marker") && ! strcmp 
(cur_props(i).marker, "none"))
-       ms = cur_props(i).marker;
-     endif
-   endfor
- endfunction
- 
- function [lc, ls, mc, ms] = set_default_values ()
-   ## set default values
-   mc = [1, 0, 0];
-   lc = [1, 0, 0];
-   ls = "-";
-   ms = "o";
- endfunction
--- 94,103 ----
  
  function h = stem (varargin)
  
!   tmp = __stem__ (false, varargin{:});
  
    if (nargout > 0)
!     h = tmp;
    endif
  
  endfunction
*** ./scripts/plot/Makefile.in.orig34   2007-11-29 17:31:04.302371148 +0100
--- ./scripts/plot/Makefile.in  2007-11-29 17:31:40.388499664 +0100
***************
*** 65,70 ****
--- 65,71 ----
    __pltopt__.m \
    __quiver__.m \
    __scatter__.m \
+   __stem__.m \
    ancestor.m \
    area.m \
    axes.m \
***************
*** 135,140 ****
--- 136,142 ----
    spinmap.m \
    stairs.m \
    stem.m \
+   stem3.m \
    subplot.m \
    surf.m \
    surface.m \
*** ./scripts/plot/__stem__.m.orig34    2007-11-29 17:30:51.861016376 +0100
--- ./scripts/plot/__stem__.m   2007-11-29 17:25:49.638690102 +0100
***************
*** 0 ****
--- 1,312 ----
+ ## Copyright (C) 2006, 2007 Michel D. Schmid
+ ##
+ ## This file is part of Octave.
+ ##
+ ## Octave is free software; you can redistribute it and/or modify it
+ ## under the terms of the GNU General Public License as published by
+ ## the Free Software Foundation; either version 3 of the License, or (at
+ ## your option) any later version.
+ ##
+ ## Octave is distributed in the hope that it will be useful, but
+ ## WITHOUT ANY WARRANTY; without even the implied warranty of
+ ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ ## General Public License for more details.
+ ##
+ ## You should have received a copy of the GNU General Public License
+ ## along with Octave; see the file COPYING.  If not, see
+ ## <http://www.gnu.org/licenses/>.
+ 
+ ## Undocumented internal function
+ 
+ ## Author: Michel D. Schmid <address@hidden>
+ ## Adapted-by: jwe
+ 
+ function h = __stem__ (have_z, varargin)
+ 
+   [ax, varargin, nargin] = __plt_get_axis_arg__ ("stem", varargin{:});
+ 
+   if (nargin < 1 || nargin > 4)
+     print_usage ();
+   endif
+ 
+   [x, y, z, dofill, lc, ls, mc, ms] = check_stem_arg (have_z, varargin{:});
+ 
+   if (dofill)
+     fc = mc;
+   else
+     fc = "none";
+   endif
+ 
+   newplot ();
+   nx = numel (x);
+   xt = x(:)';
+   xt = [xt; xt; NaN(1, nx)](:);
+   if (have_z)
+     yt = y(:)';
+     yt = [yt; yt; NaN(1, nx)](:);
+     zt = z(:)';
+     zt = [zeros(1, nx); zt; NaN(1, nx)](:);
+   else
+     yt = y(:)';
+     yt = [zeros(1, nx); yt; NaN(1, nx)](:);
+   endif
+ 
+   oldax = gca ();
+   unwind_protect
+     axes (ax);
+ 
+     if (have_z)
+       h_stems = plot3 (xt, yt, zt, "color", lc, "linestyle", ls,
+                     x, y, z, "color", mc, "marker", ms, "linestyle", "",
+                     "markerfacecolor", fc);
+ 
+       h_baseline = [];
+     else
+       h_stems = plot (xt, yt, "color", lc, "linestyle", ls,
+                     x, y, "color", mc, "marker", ms, "linestyle", "",
+                     "markerfacecolor", fc);
+ 
+       ## Must draw the plot first to get proper x limits.
+       drawnow();
+       x_axis_range = get (gca, "xlim");
+       h_baseline = line (x_axis_range, [0, 0], "color", [0, 0, 0]);
+     endif
+   unwind_protect_cleanup
+     axes (oldax);
+   end_unwind_protect
+ 
+   h = [h_stems; h_baseline];
+ 
+ endfunction
+ 
+ function [x, y, z, dofill, lc, ls, mc, ms] = check_stem_arg (have_z, varargin)
+ 
+   ## set specifiers to default values
+   [lc, ls, mc, ms] = set_default_values ();
+   dofill = 0;
+   fill_2 = 0;
+   linespec_2 = 0;
+   z = [];
+ 
+   ## check input arguments
+   if (nargin == 2)
+     if (have_z)
+       z = varargin{1};
+       x = 1 : rows (z);
+       y = 1 : columns (z);
+     else
+       y = varargin{1};
+       if (isvector (y))
+       x = 1:length(y);
+       elseif (ismatrix (y))
+       x = 1:rows(y);
+       else 
+       error ("stem: Y must be a matrix");
+       endif # in each case, x & y will be defined
+     endif
+   elseif (nargin == 3)
+     ## several possibilities
+     ## 1. the real y data
+     ## 2. 'fill'
+     ## 3. line spec
+     if (ischar (varargin{2}))
+       ## only 2. or 3. possible
+       if (strcmp ("fill", varargin{2}))
+       dofill = 1;
+       else
+       ## parse the linespec
+       [lc, ls, mc, ms] = stem_line_spec (varargin{2});
+       endif
+       if (have_z)
+       z = varargin{1};
+       x = 1 : rows (z);
+       y = 1 : columns (z);
+       else
+       y = varargin{1};
+       if (isvector (y))
+         x = 1:length(y);
+       elseif (ismatrix (y))
+         x = 1:rows(y);
+       else
+         error ("stem: Y must be a matrix");
+       endif # in each case, x & y will be defined
+       endif
+     else
+       if (have_z)
+       error ("stem3: must define X, Y and Z");
+       else
+       ## must be the real y data
+       x = varargin{1};
+       y = varargin{2};
+       if (! (ismatrix (x) && ismatrix (y)))
+         error ("stem: X and Y must be matrices");
+       endif
+       endif
+     endif
+   elseif (nargin == 4)
+     ## again several possibilities
+     ## arg2 1. real y
+     ## arg2 2. 'fill' or linespec
+     ## arg3 1. real z
+     ## arg3 2. 'fill' or linespec
+     if (ischar (varargin{2}))
+       ## only arg2 2. / arg3 1. & arg3 3. are possible
+       if (strcmp ("fill", varargin{2}))
+       dofill = 1;
+       fill_2 = 1; # be sure, no second "fill" is in the arguments
+       else
+       ## must be a linespec
+       [lc, ls, mc, ms] = stem_line_spec (varargin{2});
+       linespec_2 = 1;
+       endif
+       if (have_z)
+       z = varargin{1};
+       x = 1 : rows (z);
+       y = 1 : columns (z);
+       else
+       y = varargin{1};
+       if (isvector (y))
+         x = 1:length(y);
+       elseif (ismatrix (y))
+         x = 1:size(y,1);
+       else
+         error ("stem: Y must be a matrix");
+       endif # in each case, x & y will be defined
+       endif
+     else
+       if (have_z)
+       x = varargin{1};
+       y = varargin{2};
+       z = varargin{3};
+       if (! (ismatrix (x) && ismatrix (y) && ismatrix (z)))
+         error ("stem3: X, Y and Z must be matrices");
+       endif
+       else
+       ## must be the real y data
+       x = varargin{1};
+       y = varargin{2};
+       if (! (ismatrix (x) && ismatrix (y)))
+         error ("stem: X and Y must be matrices");
+       endif
+       endif
+     endif # if ischar(varargin{2})
+     if (! have_z)
+       ## varargin{3} must be char...
+       ## check for "fill" ..
+       if (strcmp ("fill", varargin{3}) & fill_2)
+       error ("stem:check_stem_arg: duplicate fill argument");
+       elseif (strcmp("fill", varargin{3}) & linespec_2)
+       ## must be "fill"
+       dofill = 1;
+       fill_2 = 1;
+       elseif (strcmp ("fill", varargin{3}) & ! linespec_2)
+       ## must be "fill"
+       dofill = 1;
+       fill_2 = 1;
+       elseif (! linespec_2)
+       ## must be linespec
+       [lc, ls, mc, ms] = stem_line_spec (varargin{3});
+       linespec_2 = 1;
+       endif
+     endif
+   elseif (nargin == 5)
+     if (have_z)
+       x = varargin{1};
+       y = varargin{2};
+       z = varargin{3};
+       if (! (ismatrix (x) && ismatrix (y) && ismatrix (z)))
+       error ("stem3: X, Y and Z must be matrices");
+       endif
+     else
+       x = varargin{1};
+       y = varargin{2};
+       if (! (ismatrix (x) && ismatrix (y)))
+       error ("X and Y must be matrices");
+       endif
+     endif
+ 
+     if (! have_z)
+       if (strcmp ("fill", varargin{3}))
+       dofill = 1;
+       fill_2 = 1; # be sure, no second "fill" is in the arguments
+       else
+       ## must be a linespec
+       [lc, ls, mc, ms] = stem_line_spec (varargin{3});
+       linespec_2 = 1;
+       endif
+     endif
+ 
+     ## check for "fill" ..
+     if (strcmp ("fill", varargin{4}) & fill_2)
+       error ("stem:check_stem_arg: duplicate fill argument");
+     elseif (strcmp ("fill", varargin{4}) & linespec_2)
+       ## must be "fill"
+       dofill = 1;
+       fill_2 = 1;
+     elseif (! strcmp ("fill", varargin{4}) & ! linespec_2)
+       ## must be linespec
+       [lc, ls, mc, ms] = stem_line_spec (varargin{4});
+       linespec_2 = 1;
+     endif
+   elseif (nargin == 6 && have_z)
+     x = varargin{1};
+     y = varargin{2};
+     z = varargin{3};
+     if (! (ismatrix (x) && ismatrix (y) && ismatrix (z)))
+       error ("stem3: X, Y and Z must be matrices");
+     endif
+ 
+     if (strcmp ("fill", varargin{4}))
+       dofill = 1;
+       fill_2 = 1; # be sure, no second "fill" is in the arguments
+     else
+       ## must be a linespec
+       [lc, ls, mc, ms] = stem_line_spec (varargin{4});
+       linespec_2 = 1;
+     endif
+ 
+     ## check for "fill" ..
+     if (strcmp ("fill", varargin{5}) & fill_2)
+       error ("stem3:check_stem_arg: duplicate fill argument");
+     elseif (strcmp ("fill", varargin{5}) & linespec_2)
+       ## must be "fill"
+       dofill = 1;
+       fill_2 = 1;
+     elseif (! strcmp ("fill", varargin{5}) & ! linespec_2)
+       ## must be linespec
+       [lc, ls, mc, ms] = stem_line_spec (varargin{5});
+       linespec_2 = 1;
+     endif
+   elseif (have_z)
+     error ("stem3: incorrect number of arguments");
+   else
+     error ("stem: incorrect number of arguments");
+   endif
+ 
+ endfunction
+ 
+ function [lc, ls, mc, ms] = stem_line_spec (str)
+   if (! ischar (str))
+     error ("stem:stem_line_spec: wrong argument type, must be \"fill\" or a 
string of specifiers");
+   endif
+   [lc, ls, mc, ms] = set_default_values ();
+   ## Parse the line specifier string.
+   cur_props = __pltopt__ ("stem", str, false);
+   for i = 1:length(cur_props)
+     if (isfield (cur_props(i), "color") && ! isempty (cur_props(i).color)); # 
means line color
+       mc = lc = cur_props(i).color;
+     elseif (isfield (cur_props(i), "linestyle"))
+       ls = cur_props(i).linestyle;
+     elseif (isfield (cur_props(i), "marker") && ! strcmp 
(cur_props(i).marker, "none"))
+       ms = cur_props(i).marker;
+     endif
+   endfor
+ endfunction
+ 
+ function [lc, ls, mc, ms] = set_default_values ()
+   ## set default values
+   mc = [1, 0, 0];
+   lc = [1, 0, 0];
+   ls = "-";
+   ms = "o";
+ endfunction
*** ./scripts/plot/stem3.m.orig34       2007-11-29 17:31:11.136016744 +0100
--- ./scripts/plot/stem3.m      2007-11-29 17:58:56.182664801 +0100
***************
*** 0 ****
--- 1,46 ----
+ ## Copyright (C) 2007 David Bateman
+ ##
+ ## This file is part of Octave.
+ ##
+ ## Octave is free software; you can redistribute it and/or modify it
+ ## under the terms of the GNU General Public License as published by
+ ## the Free Software Foundation; either version 3 of the License, or (at
+ ## your option) any later version.
+ ##
+ ## Octave is distributed in the hope that it will be useful, but
+ ## WITHOUT ANY WARRANTY; without even the implied warranty of
+ ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ ## General Public License for more details.
+ ##
+ ## You should have received a copy of the GNU General Public License
+ ## along with Octave; see the file COPYING.  If not, see
+ ## <http://www.gnu.org/licenses/>.
+ 
+ ## -*- texinfo -*-
+ ## @deftypefn {Function File} address@hidden =} stem3 (@var{x}, @var{y}, 
@var{z}, @var{linespec})
+ ## Plot a three-dimensional stem graph and return the handles of the line
+ ## and marker objects used to draw the stems.  The default color is @code{"r"}
+ ## (red).  The default line style is @code{"-"} and the default marker is
+ ## @code{"o"}.
+ ##
+ ## For example,
+ ## @example
+ ## theta = 0:0.2:6; 
+ ## stem3 (cos (theta), sin (theta), theta) 
+ ## @end example
+ ##
+ ## @noindent
+ ## plots 31 stems with heights from 0 to 6 lying on a circle. Color 
+ ## definitions with rgb-triples are not valid!
+ ## @seealso{bar, barh, stem, plot}
+ ## @end deftypefn
+ 
+ function h = stem3 (varargin)
+ 
+   tmp = __stem__ (true, varargin{:});
+ 
+   if (nargout > 0)
+     h = tmp;
+   endif
+ 
+ endfunction

2007-11-29  David Bateman  <address@hidden>

        * plot/__stem__.m: New file based on old stem.m expanded to treat
        2- and 3-D.
        * plot/stem3.m: New function.
        * plot/Makefile.in (SOURCES): Add them to the sources.
        * plot/stem.m: Adapt to use __stem__.