1 ## Copyright (C) 1994-2012 John W. Eaton
3 ## This file is part of Octave.
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.
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.
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/>.
20 ## @deftypefn {Function File} {} hist (@var{y})
21 ## @deftypefnx {Function File} {} hist (@var{y}, @var{x})
22 ## @deftypefnx {Function File} {} hist (@var{y}, @var{nbins})
23 ## @deftypefnx {Function File} {} hist (@var{y}, @var{x}, @var{norm})
24 ## @deftypefnx {Function File} {[@var{nn}, @var{xx}] =} hist (@dots{})
25 ## @deftypefnx {Function File} {[@dots{}] =} hist (@dots{}, @var{prop}, @var{val})
27 ## Produce histogram counts or plots.
29 ## With one vector input argument, @var{y}, plot a histogram of the values
30 ## with 10 bins. The range of the histogram bins is determined by the
31 ## range of the data. With one matrix input argument, @var{y}, plot a
32 ## histogram where each bin contains a bar per input column.
34 ## Given a second vector argument, @var{x}, use that as the centers of
35 ## the bins, with the width of the bins determined from the adjacent
36 ## values in the vector.
38 ## If scalar, the second argument, @var{nbins}, defines the number of bins.
40 ## If a third argument is provided, the histogram is normalized such that
41 ## the sum of the bars is equal to @var{norm}.
43 ## Extreme values are lumped in the first and last bins.
45 ## With two output arguments, produce the values @var{nn} and @var{xx} such
46 ## that @code{bar (@var{xx}, @var{nn})} will plot the histogram.
48 ## The histogram's appearance may be modified by specifying property/value
49 ## pairs, @var{prop} and @var{val} pairs. For example the face and edge
50 ## color may be modified.
54 ## hist (randn (1, 100), 25, "facecolor", "r", "edgecolor", "b");
59 ## The histograms colors also depend upon the colormap.
63 ## hist (rand (10, 3));
64 ## colormap (summer ());
73 function [nn, xx] = hist (y, varargin)
79 arg_is_vector = isvector (y);
89 error ("hist: first argument must be real valued");
93 if (nargin == 1 || ischar (varargin{iarg}))
96 x = x * (max_val - min_val) + ones(size(x)) * min_val;
98 ## nargin is either 2 or 3
103 error ("hist: number of bins must be positive");
106 x = x * (max_val - min_val) + ones (size (x)) * min_val;
113 warning ("hist: bin values not sorted on input");
117 error ("hist: second argument must be a scalar or a vector");
121 ## Avoid issues with integer types for x and y
125 cutoff = (x(1:end-1,:) + x(2:end,:)) / 2;
128 if (n < 30 && columns (x) == 1)
129 ## The following algorithm works fastest for n less than about 30.
130 chist = zeros (n+1, y_nc);
132 chist(i+1,:) = sum (y <= cutoff(i));
134 chist(n+1,:) = sum (! isnan (y));
136 ## The following algorithm works fastest for n greater than about 30.
137 ## Put cutoff elements between boundaries, integrate over all
138 ## elements, keep totals at boundaries.
139 [s, idx] = sort ([y; repmat(cutoff, 1, y_nc)]);
141 chist = cumsum (idx <= len);
142 chist = [(zeros (1, y_nc));
143 (reshape (chist(idx > len), rows (cutoff), y_nc));
144 (chist(end,:) - sum (isnan (y)))];
149 if (nargin > 2 && ! ischar (varargin{iarg}))
150 ## Normalise the histogram.
151 norm = varargin{iarg++};
152 freq = freq / rows (y) * norm;
163 elseif (size (freq, 2) != 1)
164 bar (x, freq, 0.8, varargin{iarg:end});
166 bar (x, freq, 1.0, varargin{iarg:end});
172 %! [nn,xx]=hist([1:4],3);
173 %! assert(xx, [1.5,2.5,3.5]);
174 %! assert(nn, [2,1,1]);
176 %! [nn,xx]=hist([1:4]',3);
177 %! assert(xx, [1.5,2.5,3.5]);
178 %! assert(nn, [2,1,1]);
180 %! [nn,xx]=hist([1 1 1 NaN NaN NaN 2 2 3],[1 2 3]);
181 %! assert(xx, [1,2,3]);
182 %! assert(nn, [3,2,1]);
184 %! [nn,xx]=hist([[1:4]',[1:4]'],3);
185 %! assert(xx, [1.5;2.5;3.5]);
186 %! assert(nn, [[2,1,1]',[2,1,1]']);
187 %!assert(hist(1,1),1);
189 %! for n = [10, 30, 100, 1000]
190 %! assert(sum(hist([1:n], n)), n);
191 %! assert(sum(hist([1:n], [2:n-1])), n);
192 %! assert(sum(hist([1:n], [1:n])), n);
193 %! assert(sum(hist([1:n], 29)), n);
194 %! assert(sum(hist([1:n], 30)), n);
197 %! assert (size (hist(randn(750,240), 200)), [200,240]);