octave_packages/m/plot/stairs.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} {} stairs (@var{y})
  21 ## @deftypefnx {Function File} {} stairs (@var{x}, @var{y})
  22 ## @deftypefnx {Function File} {} stairs (@dots{}, @var{style})
  23 ## @deftypefnx {Function File} {} stairs (@dots{}, @var{prop}, @var{val})
  24 ## @deftypefnx {Function File} {} stairs (@var{h}, @dots{})
  25 ## @deftypefnx {Function File} {@var{h} =} stairs (@dots{})
  26 ## @deftypefnx {Function File} {[@var{xstep}, @var{ystep}] =} stairs (@dots{})
  27 ## Produce a stairstep plot.  The arguments may be vectors or matrices.
  28 ##
  29 ## If only one argument is given, it is taken as a vector of y-values
  30 ## and the x coordinates are taken to be the indices of the elements.
  31 ##
  32 ## If one output argument is requested, return a graphics handle to the plot.
  33 ## If two output arguments are specified, the data are generated but
  34 ## not plotted.  For example,
  35 ##
  36 ## @example
  37 ## stairs (x, y);
  38 ## @end example
  39 ##
  40 ## @noindent
  41 ## and
  42 ##
  43 ## @example
  44 ## @group
  45 ## [xs, ys] = stairs (x, y);
  46 ## plot (xs, ys);
  47 ## @end group
  48 ## @end example
  49 ##
  50 ## @noindent
  51 ## are equivalent.
  52 ## @seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
  53 ## bar, xlabel, ylabel, title}
  54 ## @end deftypefn
  55
  56 ## Author: jwe
  57
  58 function [xs, ys] = stairs (varargin)
  59
  60   [ax, varargin, nargin] = __plt_get_axis_arg__ ("stairs", varargin{:});
  61
  62   if (nargin < 1)
  63     print_usage ();
  64   else
  65     if (nargout > 1)
  66       [h, xs, ys] = __stairs__ (false, varargin{:});
  67     else
  68       oldax = gca ();
  69       unwind_protect
  70         axes (ax);
  71         newplot ();
  72         [h, xxs, yys] = __stairs__ (true, varargin{:});
  73       unwind_protect_cleanup
  74         axes (oldax);
  75       end_unwind_protect
  76     endif
  77     if (nargout == 1)
  78       xs = h;
  79     endif
  80   endif
  81 endfunction
  82
  83 function [h, xs, ys] = __stairs__ (doplot, varargin)
  84
  85   if (nargin == 2 || ischar (varargin{2}))
  86     y = varargin {1};
  87     varargin(1) = [];
  88     if (ismatrix (y))
  89       if (isvector (y))
  90         y = y(:);
  91       endif
  92       x = 1:rows (y);
  93     endif
  94   else
  95     x = varargin{1};
  96     y = varargin{2};
  97     varargin(1:2) = [];
  98   endif
  99
 100   if (ndims (x) > 2 || ndims (y) > 2)
 101     error ("stairs: expecting 2-d arguments");
 102   endif
 103
 104   vec_x = isvector (x);
 105
 106   if (vec_x)
 107     x = x(:);
 108   endif
 109
 110   if (isvector (y))
 111     y = y(:);
 112   endif
 113
 114   if (ismatrix (y))
 115     [nr, nc] = size (y);
 116     if (vec_x)
 117       x = repmat (x, [1, nc]);
 118     else
 119       [x_nr, x_nc] = size (x);
 120       if (x_nr != nr || x_nc != nc)
 121         error ("stairs: argument size mismatch");
 122       endif
 123     endif
 124   endif
 125
 126   len = 2*nr - 1;
 127
 128   xs = ys = zeros (len, nc);
 129
 130   xs(1,:) = x(1,:);
 131   ys(1,:) = y(1,:);
 132
 133   xtmp = x(2:nr,:);
 134   ridx = 2:2:len-1;
 135   xs(ridx,:) = xtmp;
 136   ys(ridx,:) = y(1:nr-1,:);
 137
 138   ridx = 3:2:len;
 139   xs(ridx,:) = xtmp;
 140   ys(ridx,:) = y(2:nr,:);
 141
 142   have_line_spec = false;
 143   for i = 1 : length (varargin)
 144     arg = varargin {i};
 145     if ((ischar (arg) || iscell (arg)) && ! have_line_spec)
 146       [linespec, valid] = __pltopt__ ("stairs", arg, false);
 147       if (valid)
 148         have_line_spec = true;
 149         varargin(i) = [];
 150         break;
 151       endif
 152     endif
 153   endfor
 154
 155   if (doplot)
 156     h = [];
 157     unwind_protect
 158       hold_state = get (gca (), "nextplot");
 159       for i = 1 : size(y, 2)
 160         hg = hggroup ();
 161         h = [h; hg];
 162         args = __add_datasource__ ("stairs", hg, {"x", "y"}, varargin{:});
 163
 164         addproperty ("xdata", hg, "data", x(:,i).');
 165         addproperty ("ydata", hg, "data", y(:,i).');
 166
 167         addlistener (hg, "xdata", @update_data);
 168         addlistener (hg, "ydata", @update_data);
 169
 170         if (have_line_spec)
 171           tmp = line (xs(:,i).', ys(:,i).', "color", linespec.color,
 172                       "parent", hg);
 173         else
 174           tmp = line (xs(:,i).', ys(:,i).', "color", __next_line_color__ (),
 175                       "parent", hg);
 176         endif
 177
 178         addproperty ("color", hg, "linecolor", get (tmp, "color"));
 179         addproperty ("linewidth", hg, "linelinewidth", get (tmp, "linewidth"));
 180         addproperty ("linestyle", hg, "linelinestyle", get (tmp, "linestyle"));
 181
 182         addproperty ("marker", hg, "linemarker", get (tmp, "marker"));
 183         addproperty ("markerfacecolor", hg, "linemarkerfacecolor",
 184                      get (tmp, "markerfacecolor"));
 185         addproperty ("markeredgecolor", hg, "linemarkeredgecolor",
 186                      get (tmp, "markeredgecolor"));
 187         addproperty ("markersize", hg, "linemarkersize",
 188                      get (tmp, "markersize"));
 189
 190         addlistener (hg, "color", @update_props);
 191         addlistener (hg, "linewidth", @update_props);
 192         addlistener (hg, "linestyle", @update_props);
 193         addlistener (hg, "marker", @update_props);
 194         addlistener (hg, "markerfacecolor", @update_props);
 195         addlistener (hg, "markeredgecolor", @update_props);
 196         addlistener (hg, "markersize", @update_props);
 197
 198         if (! isempty (args))
 199           set (hg, args{:});
 200         endif
 201       endfor
 202     unwind_protect_cleanup
 203       set (gca (), "nextplot", hold_state);
 204     end_unwind_protect
 205   else
 206     h = 0;
 207   endif
 208
 209 endfunction
 210
 211
 212 %!demo
 213 %! clf
 214 %! x = 1:10;
 215 %! rand_1x10_data1 = [0.073, 0.455, 0.837, 0.124, 0.426, 0.781, 0.004, 0.024, 0.519, 0.698];
 216 %! y = rand_1x10_data1;
 217 %! stairs (x, y);
 218
 219 %!demo
 220 %! clf
 221 %! x = 1:10;
 222 %! rand_1x10_data2 = [0.014, 0.460, 0.622, 0.394, 0.531, 0.378, 0.466, 0.788, 0.342, 0.893];
 223 %! y = rand_1x10_data2;
 224 %! [xs, ys] = stairs (x, y);
 225 %! plot (xs, ys);
 226
 227 %!demo
 228 %! clf
 229 %! stairs (1:9);
 230
 231 %!demo
 232 %! clf
 233 %! [xs, ys] = stairs (9:-1:1);
 234 %! plot (xs, ys);
 235
 236
 237 function update_props (h, d)
 238   set (get (h, "children"), "color", get (h, "color"),
 239        "linewidth", get (h, "linewidth"),
 240        "linestyle", get (h, "linestyle"),
 241        "marker", get (h, "marker"),
 242        "markerfacecolor", get (h, "markerfacecolor"),
 243        "markeredgecolor", get (h, "markeredgecolor"),
 244        "markersize", get (h, "markersize"));
 245 endfunction
 246
 247 function update_data (h, d)
 248   x = get (h, "xdata");
 249   y = get (h, "ydata");
 250
 251   nr = length (x);
 252   len = 2 * nr - 1;
 253   xs = ys = zeros (1, len);
 254
 255   xs(1) = x(1);
 256   ys(1) = y(1);
 257
 258   xtmp = x(2:nr);
 259   ridx = 2:2:len-1;
 260   xs(ridx) = xtmp;
 261   ys(ridx) = y(1:nr-1);
 262
 263   ridx = 3:2:len;
 264   xs(ridx) = xtmp;
 265   ys(ridx) = y(2:nr);
 266
 267   set (get (h, "children"), "xdata", xs, "ydata", ys);
 268 endfunction