octave_packages/m/plot/errorbar.m

   1 ## Copyright (C) 2000-2012 Teemu Ikonen
   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} {} errorbar (@var{args})
  21 ## This function produces two-dimensional plots with errorbars.  Many
  22 ## different combinations of arguments are possible.  The simplest form is
  23 ##
  24 ## @example
  25 ## errorbar (@var{y}, @var{ey})
  26 ## @end example
  27 ##
  28 ## @noindent
  29 ## where the first argument is taken as the set of @var{y} coordinates
  30 ## and the second argument @var{ey} is taken as the errors of the
  31 ## @var{y} values.  @var{x} coordinates are taken to be the indices
  32 ## of the elements, starting with 1.
  33 ##
  34 ## If more than two arguments are given, they are interpreted as
  35 ##
  36 ## @example
  37 ## errorbar (@var{x}, @var{y}, @dots{}, @var{fmt}, @dots{})
  38 ## @end example
  39 ##
  40 ## @noindent
  41 ## where after @var{x} and @var{y} there can be up to four error
  42 ## parameters such as @var{ey}, @var{ex}, @var{ly}, @var{uy}, etc.,
  43 ## depending on the plot type.  Any number of argument sets may appear,
  44 ## as long as they are separated with a format string @var{fmt}.
  45 ##
  46 ## If @var{y} is a matrix, @var{x} and error parameters must also be matrices
  47 ## having same dimensions.  The columns of @var{y} are plotted versus the
  48 ## corresponding columns of @var{x} and errorbars are drawn from
  49 ## the corresponding columns of error parameters.
  50 ##
  51 ## If @var{fmt} is missing, yerrorbars ("~") plot style is assumed.
  52 ##
  53 ## If the @var{fmt} argument is supplied, it is interpreted as in
  54 ## normal plots.  In addition, @var{fmt} may include an errorbar style
  55 ## which must precede the line and marker format.  The following plot
  56 ## styles are supported by errorbar:
  57 ##
  58 ## @table @samp
  59 ## @item ~
  60 ## Set yerrorbars plot style (default).
  61 ##
  62 ## @item >
  63 ## Set xerrorbars plot style.
  64 ##
  65 ## @item ~>
  66 ## Set xyerrorbars plot style.
  67 ##
  68 ## @item #
  69 ## Set boxes plot style.
  70 ##
  71 ## @item #~
  72 ## Set boxerrorbars plot style.
  73 ##
  74 ## @item #~>
  75 ## Set boxxyerrorbars plot style.
  76 ## @end table
  77 ##
  78 ## Examples:
  79 ##
  80 ## @example
  81 ## errorbar (@var{x}, @var{y}, @var{ex}, ">")
  82 ## @end example
  83 ##
  84 ## @noindent
  85 ## produces an xerrorbar plot of @var{y} versus @var{x} with @var{x}
  86 ## errorbars drawn from @var{x}-@var{ex} to @var{x}+@var{ex}.
  87 ##
  88 ## @example
  89 ## @group
  90 ## errorbar (@var{x}, @var{y1}, @var{ey}, "~",
  91 ##           @var{x}, @var{y2}, @var{ly}, @var{uy})
  92 ## @end group
  93 ## @end example
  94 ##
  95 ## @noindent
  96 ## produces yerrorbar plots with @var{y1} and @var{y2} versus @var{x}.
  97 ## Errorbars for @var{y1} are drawn from @var{y1}-@var{ey} to
  98 ## @var{y1}+@var{ey}, errorbars for @var{y2} from @var{y2}-@var{ly} to
  99 ## @var{y2}+@var{uy}.
 100 ##
 101 ## @example
 102 ## @group
 103 ## errorbar (@var{x}, @var{y}, @var{lx}, @var{ux},
 104 ##           @var{ly}, @var{uy}, "~>")
 105 ## @end group
 106 ## @end example
 107 ##
 108 ## @noindent
 109 ## produces an xyerrorbar plot of @var{y} versus @var{x} in which
 110 ## @var{x} errorbars are drawn from @var{x}-@var{lx} to @var{x}+@var{ux}
 111 ## and @var{y} errorbars from @var{y}-@var{ly} to @var{y}+@var{uy}.
 112 ## @seealso{semilogxerr, semilogyerr, loglogerr}
 113 ## @end deftypefn
 114
 115 ## Created: 18.7.2000
 116 ## Author: Teemu Ikonen <tpikonen@pcu.helsinki.fi>
 117 ## Keywords: errorbar, plotting
 118
 119 function retval = errorbar (varargin)
 120
 121   [h, varargin] = __plt_get_axis_arg__ ("errorbar", varargin{:});
 122
 123   oldh = gca ();
 124   unwind_protect
 125     axes (h);
 126     newplot ();
 127
 128     tmp = __errcomm__ ("errorbar", h, varargin{:});
 129
 130     if (nargout > 0)
 131       retval = tmp;
 132     endif
 133   unwind_protect_cleanup
 134     axes (oldh);
 135   end_unwind_protect
 136
 137 endfunction
 138
 139
 140 %!demo
 141 %! clf
 142 %! rand_1x11_data1 = [0.82712, 0.50325, 0.35613, 0.77089, 0.20474, 0.69160, 0.30858, 0.88225, 0.35187, 0.14168, 0.54270];
 143 %! rand_1x11_data2 = [0.506375, 0.330106, 0.017982, 0.859270, 0.140641, 0.327839, 0.275886, 0.162453, 0.807592, 0.318509, 0.921112];
 144 %! errorbar (0:10, rand_1x11_data1, 0.25*rand_1x11_data2);
 145
 146 %!demo
 147 %! clf
 148 %! rand_1x11_data3 = [0.423650, 0.142331, 0.213195, 0.129301, 0.975891, 0.012872, 0.635327, 0.338829, 0.764997, 0.401798, 0.551850];
 149 %! rand_1x11_data4 = [0.682566, 0.456342, 0.132390, 0.341292, 0.108633, 0.601553, 0.040455, 0.146665, 0.309187, 0.586291, 0.540149];
 150 %! errorbar(0:10, rand_1x11_data3, rand_1x11_data4, ">");
 151
 152 %!demo
 153 %! clf
 154 %! x = 0:0.5:2*pi;
 155 %! err = x/100;
 156 %! y1 = sin (x);
 157 %! y2 = cos (x);
 158 %! hg = errorbar (x, y1, err, "~", x, y2, err, ">");
 159
 160 %!demo
 161 %! clf
 162 %! x = 0:0.5:2*pi;
 163 %! err = x/100;
 164 %! y1 = sin (x);
 165 %! y2 = cos (x);
 166 %! hg = errorbar (x, y1, err, err, "#r", x, y2, err, err, "#~");
 167
 168 %!demo
 169 %! clf
 170 %! x = 0:0.5:2*pi;
 171 %! err = x/100;
 172 %! y1 = sin (x);
 173 %! y2 = cos (x);
 174 %! hg = errorbar (x, y1, err, err, err, err, "~>", ...
 175 %!                x, y2, err, err, err, err, "#~>-*");
 176