bin

% bin Bin y according to x in xbin

 Bin the contents of y in the xbins according to the values in x.
 E.g. y(i) is binned according to the value of x(i). Binning rules
 as for <a href="matlab:help histc">histc</a>.

 Any value for which x is not finite will not be binned at all.

 Also known as bucketing, see
 http://en.wikipedia.org/wiki/Bucket_%28computing%29


 FORMAT

   values = bin(x, y, xbin)

 IN

   x       numeric array
               values determine how y is binned
   y       numeric array
               values to bin. Must be the same size as x.
   xbin    numeric array, monotonously increasing
               bin edges (as for histc)

 OUT

   values  cell array
               Binned values.

 See also: binning_fast, bin_nd

 $Id: bin.m 8266 2013-03-05 18:03:58Z gerrit $

0001 function values = bin(x, y, xbin)
0002 %% bin Bin y according to x in xbin
0003 %
0004 % Bin the contents of y in the xbins according to the values in x.
0005 % E.g. y(i) is binned according to the value of x(i). Binning rules
0006 % as for <a href="matlab:help histc">histc</a>.
0007 %
0008 % Any value for which x is not finite will not be binned at all.
0009 %
0010 % Also known as bucketing, see
0011 % http://en.wikipedia.org/wiki/Bucket_%28computing%29
0012 %
0013 %
0014 % FORMAT
0015 %
0016 %   values = bin(x, y, xbin)
0017 %
0018 % IN
0019 %
0020 %   x       numeric array
0021 %               values determine how y is binned
0022 %   y       numeric array
0023 %               values to bin. Must be the same size as x.
0024 %   xbin    numeric array, monotonously increasing
0025 %               bin edges (as for histc)
0026 %
0027 % OUT
0028 %
0029 %   values  cell array
0030 %               Binned values.
0031 %
0032 % See also: binning_fast, bin_nd
0033 %
0034 % $Id: bin.m 8266 2013-03-05 18:03:58Z gerrit $
0035 
0036 
0037 % convert to column vectors, if needed
0038 x = vec2col(x);
0039 y = vec2col(y);
0040 %Z = [x y];
0041 
0042 % initialise with (0x1) arrays of type y, so that all entries have the same
0043 % type and size
0044 values = repmat({zeros(0, 1, class(y))}, [length(xbin), 1]);
0045 
0046 ignore = ~isfinite(x);
0047 x(ignore) = [];
0048 y(ignore) = [];
0049 % if any(~isfinite(x))
0050 %     error(['atmlab:' mfilename ':invalid'], ...
0051 %         ['Found nonfinite values in data to be binned against. ' ...
0052 %          'What can I do?']);
0053 % end
0054 
0055 if isempty(x)
0056     return % values already set, nothing to do
0057 end
0058 
0059 % check that all x are in range of bins.
0060 % This guarantees the last bin to be empty.
0061 if min(x) < min(xbin) || max(x) > max(xbin)
0062     error(['atmlab:' mfilename ':outofrange'], ...
0063         'x data (%g -- %g) out of range of x bins (%g -- %g)', ...
0064         min(x), max(x), min(xbin), max(xbin));
0065 end
0066 
0067 [x_sorted, x_sorted_i] = sort(x);
0068 [~, binsorted] = histc(x_sorted, xbin);
0069 boundaries = [0; find(diff(binsorted)); length(x)];
0070 
0071 for i = 1:length(boundaries)-1
0072     lo = boundaries(i)+1;
0073     hi = boundaries(i+1);
0074     bin_i = binsorted(lo);
0075     values{bin_i} = y(x_sorted_i(lo:hi));
0076 end
0077 
0078 end