octave_packages/m/plot/bar.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} {} bar (@var{x}, @var{y})
  21 ## @deftypefnx {Function File} {} bar (@var{y})
  22 ## @deftypefnx {Function File} {} bar (@var{x}, @var{y}, @var{w})
  23 ## @deftypefnx {Function File} {} bar (@var{x}, @var{y}, @var{w}, @var{style})
  24 ## @deftypefnx {Function File} {@var{h} =} bar (@dots{}, @var{prop}, @var{val})
  25 ## @deftypefnx {Function File} {} bar (@var{h}, @dots{})
  26 ## Produce a bar graph from two vectors of x-y data.
  27 ##
  28 ## If only one argument is given, @var{y}, it is taken as a vector of y-values
  29 ## and the x coordinates are taken to be the indices of the elements.
  30 ##
  31 ## The default width of 0.8 for the bars can be changed using @var{w}.
  32 ##
  33 ## If @var{y} is a matrix, then each column of @var{y} is taken to be a
  34 ## separate bar graph plotted on the same graph.  By default the columns
  35 ## are plotted side-by-side.  This behavior can be changed by the @var{style}
  36 ## argument, which can take the values @code{"grouped"} (the default),
  37 ## or @code{"stacked"}.
  38 ##
  39 ## The optional return value @var{h} is a handle to the created "bar series"
  40 ## object with one handle per column of the variable @var{y}.  This
  41 ## series allows common elements of the group of bar series objects to
  42 ## be changed in a single bar series and the same properties are changed
  43 ## in the other "bar series".  For example,
  44 ##
  45 ## @example
  46 ## @group
  47 ## h = bar (rand (5, 10));
  48 ## set (h(1), "basevalue", 0.5);
  49 ## @end group
  50 ## @end example
  51 ##
  52 ## @noindent
  53 ## changes the position on the base of all of the bar series.
  54 ##
  55 ## The optional input handle @var{h} allows an axis handle to be passed.
  56 ##
  57 ## The bar graph's appearance may be modified by specifying property/value
  58 ## pairs.  The following example modifies the face and edge colors.
  59 ##
  60 ## @example
  61 ## bar (randn (1, 100), "facecolor", "r", "edgecolor", "b")
  62 ## @end example
  63 ##
  64 ## @noindent
  65 ## The color of the bars is taken from the figure's colormap, such that
  66 ##
  67 ## @example
  68 ## @group
  69 ## bar (rand (10, 3));
  70 ## colormap (summer (64));
  71 ## @end group
  72 ## @end example
  73 ##
  74 ## @noindent
  75 ## will change the colors used for the bars.  The color of bars can also be set
  76 ## manually using the "facecolor" property as shown below.
  77 ##
  78 ## @example
  79 ## @group
  80 ## h = bar (rand (10, 3));
  81 ## set (h(1), "facecolor", "r")
  82 ## set (h(2), "facecolor", "g")
  83 ## set (h(3), "facecolor", "b")
  84 ## @end group
  85 ## @end example
  86 ##
  87 ## @seealso{barh, plot}
  88 ## @end deftypefn
  89
  90 ## Author: jwe
  91
  92 function varargout = bar (varargin)
  93   varargout = cell (nargout, 1);
  94   [varargout{:}] = __bar__ (true, "bar", varargin{:});
  95 endfunction
  96
  97
  98 %% FIXME: Need demo or test for function
  99