Mercurial > octave-nkf

comparison scripts/plot/draw/errorbar.m @ 18347:238aa26b30e3 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Re-write documentation for errorbar family of functions. * errorbar.m: Rewrite docstring. * loglogerr.m, semilogxerr.m, semilogyerr.m: Update list of forms showing how function can be called.
author Rik <rik@octave.org>
date Thu, 23 Jan 2014 12:49:07 -0800
parents d63878346099
children cafffc1b70b1 446c46af4b42
comparison
equal deleted inserted replaced
18342:ee7f66925267 18347:238aa26b30e3
15 ## You should have received a copy of the GNU General Public License 15 ## You should have received a copy of the GNU General Public License
16 ## along with Octave; see the file COPYING. If not, see 16 ## along with Octave; see the file COPYING. If not, see
17 ## <http://www.gnu.org/licenses/>. 17 ## <http://www.gnu.org/licenses/>.
18 18
19 ## -*- texinfo -*- 19 ## -*- texinfo -*-
20 ## @deftypefn {Function File} {} errorbar (@var{args}) 20 ## @deftypefn {Function File} {} errorbar (@var{y}, @var{ey})
21 ## @deftypefnx {Function File} {} errorbar (@var{y}, @dots{}, @var{fmt})
22 ## @deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{ey})
23 ## @deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{err}, @var{fmt})
24 ## @deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
25 ## @deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
26 ## @deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
27 ## @deftypefnx {Function File} {} errorbar (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
21 ## @deftypefnx {Function File} {} errorbar (@var{hax}, @dots{}) 28 ## @deftypefnx {Function File} {} errorbar (@var{hax}, @dots{})
22 ## @deftypefnx {Function File} {@var{h} =} errorbar (@dots{}) 29 ## @deftypefnx {Function File} {@var{h} =} errorbar (@dots{})
23 ## Create a 2-D with errorbars. 30 ## Create a 2-D plot with errorbars.
24 ## 31 ##
25 ## Many different combinations of arguments are possible. The simplest 32 ## Many different combinations of arguments are possible. The simplest form is
26 ## form is
27 ## 33 ##
28 ## @example 34 ## @example
29 ## errorbar (@var{y}, @var{ey}) 35 ## errorbar (@var{y}, @var{ey})
30 ## @end example 36 ## @end example
31 ## 37 ##
32 ## @noindent 38 ## @noindent
33 ## where the first argument is taken as the set of @var{y} coordinates 39 ## where the first argument is taken as the set of @var{y} coordinates, the
34 ## and the second argument @var{ey} is taken as the errors of the 40 ## second argument @var{ey} are the errors around the @var{y} values, and the
35 ## @var{y} values. @var{x} coordinates are taken to be the indices 41 ## @var{x} coordinates are taken to be the indices of the elements
36 ## of the elements, starting with 1. 42 ## (@code{1:numel (@var{y})}).
37 ## 43 ##
38 ## If more than two arguments are given, they are interpreted as 44 ## The general form of the function is
39 ## 45 ##
40 ## @example 46 ## @example
41 ## errorbar (@var{x}, @var{y}, @dots{}, @var{fmt}, @dots{}) 47 ## errorbar (@var{x}, @var{y}, @var{err1}, @dots{}, @var{fmt}, @dots{})
42 ## @end example 48 ## @end example
43 ## 49 ##
44 ## @noindent 50 ## @noindent
45 ## where after @var{x} and @var{y} there can be up to four error 51 ## After the @var{x} and @var{y} arguments there can be 1, 2, or 4
46 ## parameters such as @var{ey}, @var{ex}, @var{ly}, @var{uy}, etc., 52 ## parameters specifying the error values depending on the nature of the error
47 ## depending on the plot type. Any number of argument sets may appear, 53 ## values and the plot format @var{fmt}.
48 ## as long as they are separated with a format string @var{fmt}. 54 ##
49 ## 55 ## @table @asis
50 ## If @var{y} is a matrix, @var{x} and error parameters must also be matrices 56 ## @item @var{err} (scalar)
51 ## having same dimensions. The columns of @var{y} are plotted versus the 57 ## When the error is a scalar all points share the same error value.
52 ## corresponding columns of @var{x} and errorbars are drawn from 58 ## The errorbars are symmetric and are drawn from @var{data}-@var{err} to
53 ## the corresponding columns of error parameters. 59 ## @var{data}+@var{err}.
54 ## 60 ## The @var{fmt} argument determines whether @var{err} is in the x-direction,
55 ## If @var{fmt} is missing, yerrorbars ("~") plot style is assumed. 61 ## y-direction (default), or both.
56 ## 62 ##
57 ## If the @var{fmt} argument is supplied, it is interpreted as in 63 ## @item @var{err} (vector or matrix)
58 ## normal plots. In addition, @var{fmt} may include an errorbar style 64 ## Each data point has a particular error value.
59 ## which must precede the line and marker format. The following plot 65 ## The errorbars are symmetric and are drawn from @var{data}(n)-@var{err}(n) to
60 ## styles are supported by errorbar: 66 ## @var{data}(n)+@var{err}(n).
67 ##
68 ## @item @var{lerr}, @var{uerr} (scalar)
69 ## The errors have a single low-side value and a single upper-side value.
70 ## The errorbars are not symmetric and are drawn from @var{data}-@var{lerr} to
71 ## @var{data}+@var{uerr}.
72 ##
73 ## @item @var{lerr}, @var{uerr} (vector or matrix)
74 ## Each data point has a low-side error and an upper-side error.
75 ## The errorbars are not symmetric and are drawn from
76 ## @var{data}(n)-@var{lerr}(n) to @var{data}(n)+@var{uerr}(n).
77 ## @end table
78 ##
79 ## Any number of data sets (@var{x1},@var{y1}, @var{x2},@var{y2}, @dots{}) may
80 ## appear as long as they are separated by a format string @var{fmt}.
81 ##
82 ## If @var{y} is a matrix, @var{x} and the error parameters must also be
83 ## matrices having the same dimensions. The columns of @var{y} are plotted
84 ## versus the corresponding columns of @var{x} and errorbars are taken from
85 ## the corresponding columns of the error parameters.
86 ##
87 ## If @var{fmt} is missing, the yerrorbars ("~") plot style is assumed.
88 ##
89 ## If the @var{fmt} argument is supplied then it is interpreted, as in normal
90 ## plots, to specify the line style, marker, and color. In addition,
91 ## @var{fmt} may include an errorbar style which @strong{must precede} the
92 ## ordinary format codes. The following errorbar styles are supported:
61 ## 93 ##
62 ## @table @samp 94 ## @table @samp
63 ## @item ~ 95 ## @item ~
64 ## Set yerrorbars plot style (default). 96 ## Set yerrorbars plot style (default).
65 ## 97 ##
67 ## Set xerrorbars plot style. 99 ## Set xerrorbars plot style.
68 ## 100 ##
69 ## @item ~> 101 ## @item ~>
70 ## Set xyerrorbars plot style. 102 ## Set xyerrorbars plot style.
71 ## 103 ##
104 ## @item #~
105 ## Set yboxes plot style.
106 ##
72 ## @item # 107 ## @item #
73 ## Set boxes plot style. 108 ## Set xboxes plot style.
74 ##
75 ## @item #~
76 ## Set boxerrorbars plot style.
77 ## 109 ##
78 ## @item #~> 110 ## @item #~>
79 ## Set boxxyerrorbars plot style. 111 ## Set xyboxes plot style.
80 ## @end table 112 ## @end table
81 ## 113 ##
82 ## If the first argument @var{hax} is an axes handle, then plot into this axis, 114 ## If the first argument @var{hax} is an axes handle, then plot into this axis,
83 ## rather than the current axes returned by @code{gca}. 115 ## rather than the current axes returned by @code{gca}.
84 ## 116 ##
85 ## The optional return value @var{h} is a handle to the hggroup object 117 ## The optional return value @var{h} is a handle to the hggroup object
86 ## representing the data plot and errorbars. 118 ## representing the data plot and errorbars.
87 ## 119 ##
120 ## Note: For compatibility with @sc{matlab} a line is drawn through all data
121 ## points. However, most scientific errorbar plots are a scatter plot of
122 ## points with errorbars. To accomplish this, add a marker style to the
123 ## @var{fmt} argument such as @qcode{"."}. Alternatively, remove the line
124 ## by modifying the returned graphic handle with
125 ## @code{set (h, "linestyle", "none")}.
126 ##
88 ## Examples: 127 ## Examples:
89 ## 128 ##
90 ## @example 129 ## @example
91 ## errorbar (@var{x}, @var{y}, @var{ex}, ">") 130 ## errorbar (@var{x}, @var{y}, @var{ex}, ">.r")
92 ## @end example 131 ## @end example
93 ## 132 ##
94 ## @noindent 133 ## @noindent
95 ## produces an xerrorbar plot of @var{y} versus @var{x} with @var{x} 134 ## produces an xerrorbar plot of @var{y} versus @var{x} with @var{x}
96 ## errorbars drawn from @var{x}-@var{ex} to @var{x}+@var{ex}. 135 ## errorbars drawn from @var{x}-@var{ex} to @var{x}+@var{ex}. The marker
136 ## @qcode{"."} is used so no connecting line is drawn and the errorbars
137 ## appear in red.
97 ## 138 ##
98 ## @example 139 ## @example
99 ## @group 140 ## @group
100 ## errorbar (@var{x}, @var{y1}, @var{ey}, "~", 141 ## errorbar (@var{x}, @var{y1}, @var{ey}, "~",
101 ## @var{x}, @var{y2}, @var{ly}, @var{uy}) 142 ## @var{x}, @var{y2}, @var{ly}, @var{uy})