octave_packages/m/plot/hist.m

   1 ## Copyright (C) 1994-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} {} 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})
  26 ##
  27 ## Produce histogram counts or plots.
  28 ##
  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.
  33 ##
  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.
  37 ##
  38 ## If scalar, the second argument, @var{nbins}, defines the number of bins.
  39 ##
  40 ## If a third argument is provided, the histogram is normalized such that
  41 ## the sum of the bars is equal to @var{norm}.
  42 ##
  43 ## Extreme values are lumped in the first and last bins.
  44 ##
  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.
  47 ##
  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.
  51 ##
  52 ## @example
  53 ## @group
  54 ## hist (randn (1, 100), 25, "facecolor", "r", "edgecolor", "b");
  55 ## @end group
  56 ## @end example
  57 ##
  58 ## @noindent
  59 ## The histograms colors also depend upon the colormap.
  60 ##
  61 ## @example
  62 ## @group
  63 ## hist (rand (10, 3));
  64 ## colormap (summer ());
  65 ## @end group
  66 ## @end example
  67 ##
  68 ## @seealso{bar}
  69 ## @end deftypefn
  70
  71 ## Author: jwe
  72
  73 function [nn, xx] = hist (y, varargin)
  74
  75   if (nargin < 1)
  76     print_usage ();
  77   endif
  78
  79   arg_is_vector = isvector (y);
  80
  81   if (rows (y) == 1)
  82     y = y(:);
  83   endif
  84
  85   if (isreal (y))
  86     max_val = max (y(:));
  87     min_val = min (y(:));
  88   else
  89     error ("hist: first argument must be real valued");
  90   endif
  91
  92   iarg = 1;
  93   if (nargin == 1 || ischar (varargin{iarg}))
  94     n = 10;
  95     x = [0.5:n]'/n;
  96     x = x * (max_val - min_val) + ones(size(x)) * min_val;
  97   else
  98     ## nargin is either 2 or 3
  99     x = varargin{iarg++};
 100     if (isscalar (x))
 101       n = x;
 102       if (n <= 0)
 103         error ("hist: number of bins must be positive");
 104       endif
 105       x = [0.5:n]'/n;
 106       x = x * (max_val - min_val) + ones (size (x)) * min_val;
 107     elseif (isreal (x))
 108       if (isvector (x))
 109         x = x(:);
 110       endif
 111       tmp = sort (x);
 112       if (any (tmp != x))
 113         warning ("hist: bin values not sorted on input");
 114         x = tmp;
 115       endif
 116     else
 117       error ("hist: second argument must be a scalar or a vector");
 118     endif
 119   endif
 120
 121   ## Avoid issues with integer types for x and y
 122   x = double (x);
 123   y = double (y);
 124
 125   cutoff = (x(1:end-1,:) + x(2:end,:)) / 2;
 126   n = rows (x);
 127   y_nc = columns (y);
 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);
 131     for i = 1:n-1
 132       chist(i+1,:) = sum (y <= cutoff(i));
 133     endfor
 134     chist(n+1,:) = sum (! isnan (y));
 135   else
 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)]);
 140     len = rows (y);
 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)))];
 145   endif
 146
 147   freq = diff (chist);
 148
 149   if (nargin > 2 && ! ischar (varargin{iarg}))
 150     ## Normalise the histogram.
 151     norm = varargin{iarg++};
 152     freq = freq / rows (y) * norm;
 153   endif
 154
 155   if (nargout > 0)
 156     if (arg_is_vector)
 157       nn = freq';
 158       xx = x';
 159     else
 160       nn = freq;
 161       xx = x;
 162     endif
 163   elseif (size (freq, 2) != 1)
 164     bar (x, freq, 0.8, varargin{iarg:end});
 165   else
 166     bar (x, freq, 1.0, varargin{iarg:end});
 167   endif
 168
 169 endfunction
 170
 171 %!test
 172 %!  [nn,xx]=hist([1:4],3);
 173 %!  assert(xx, [1.5,2.5,3.5]);
 174 %!  assert(nn, [2,1,1]);
 175 %!test
 176 %!  [nn,xx]=hist([1:4]',3);
 177 %!  assert(xx, [1.5,2.5,3.5]);
 178 %!  assert(nn, [2,1,1]);
 179 %!test
 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]);
 183 %!test
 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);
 188 %!test
 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);
 195 %!  endfor
 196 %!test
 197 %!  assert (size (hist(randn(750,240), 200)), [200,240]);