time | Calls | line |
---|
| | 1 | function [n,edges,bin] = histcounts(x, varargin)
|
| | 2 | %HISTCOUNTS Histogram Bin Counts.
|
| | 3 | % [N,EDGES] = HISTCOUNTS(X) partitions the values in X into bins, and
|
| | 4 | % returns the count in each bin, as well as the bin edges. HISTCOUNTS
|
| | 5 | % determines the bin edges using an automatic binning algorithm that
|
| | 6 | % returns uniform bins of a width that is chosen to cover the range of
|
| | 7 | % values in X and reveal the shape of the underlying distribution.
|
| | 8 | %
|
| | 9 | % N(k) will count the value X(i) if EDGES(k) <= X(i) < EDGES(k+1). The
|
| | 10 | % last bin will also include the right edge such that N(end) will count
|
| | 11 | % X(i) if EDGES(end-1) <= X(i) <= EDGES(end).
|
| | 12 | %
|
| | 13 | % [N,EDGES] = HISTCOUNTS(X,M), where M is a scalar, uses M bins.
|
| | 14 | %
|
| | 15 | % [N,EDGES] = HISTCOUNTS(X,EDGES), where EDGES is a vector, specifies the
|
| | 16 | % edges of the bins.
|
| | 17 | %
|
| | 18 | % [N,EDGES] = HISTCOUNTS(...,'BinWidth',BW) uses bins of width BW. To
|
| | 19 | % prevent from accidentally creating too many bins, a limit of 65536 bins
|
| | 20 | % can be created when specifying 'BinWidth'. If BW is too small such that
|
| | 21 | % more than 65536 bins are needed, HISTCOUNTS uses wider bins instead.
|
| | 22 | %
|
| | 23 | % [N,EDGES] = HISTCOUNTS(...,'BinLimits',[BMIN,BMAX]) bins only elements
|
| | 24 | % in X between BMIN and BMAX inclusive, X(X>=BMIN & X<=BMAX).
|
| | 25 | %
|
| | 26 | % [N,EDGES] = HISTCOUNTS(...,'Normalization',NM) specifies the
|
| | 27 | % normalization scheme of the histogram values returned in N. NM can be:
|
| | 28 | % 'count' Each N value is the number of observations in
|
| | 29 | % each bin, and SUM(N) is equal to NUMEL(X).
|
| | 30 | % This is the default.
|
| | 31 | % 'probability' Each N value is the relative number of
|
| | 32 | % observations (number of observations in bin /
|
| | 33 | % total number of observations), and SUM(N) is
|
| | 34 | % equal to 1.
|
| | 35 | % 'countdensity' Each N value is the number of observations in
|
| | 36 | % each bin divided by the width of the bin.
|
| | 37 | % 'pdf' Probability density function estimate. Each N
|
| | 38 | % value is, (number of observations in bin) /
|
| | 39 | % (total number of observations * width of bin).
|
| | 40 | % 'cumcount' Each N value is the cumulative number of
|
| | 41 | % observations in each bin and all previous bins.
|
| | 42 | % N(end) is equal to NUMEL(X).
|
| | 43 | % 'cdf' Cumulative density function estimate. Each N
|
| | 44 | % value is the cumulative relative number of
|
| | 45 | % observations in each bin and all previous bins.
|
| | 46 | % N(end) is equal to 1.
|
| | 47 | %
|
| | 48 | % [N,EDGES] = HISTCOUNTS(...,'BinMethod',BM), uses the specified automatic
|
| | 49 | % binning algorithm to determine the number and width of the bins. BM can be:
|
| | 50 | % 'auto' The default 'auto' algorithm chooses a bin
|
| | 51 | % width to cover the data range and reveal the
|
| | 52 | % shape of the underlying distribution.
|
| | 53 | % 'scott' Scott's rule is optimal if X is close to being
|
| | 54 | % normally distributed, but is also appropriate
|
| | 55 | % for most other distributions. It uses a bin width
|
| | 56 | % of 3.5*STD(X(:))*NUMEL(X)^(-1/3).
|
| | 57 | % 'fd' The Freedman-Diaconis rule is less sensitive to
|
| | 58 | % outliers in the data, and may be more suitable
|
| | 59 | % for data with heavy-tailed distributions. It
|
| | 60 | % uses a bin width of 2*IQR(X(:))*NUMEL(X)^(-1/3),
|
| | 61 | % where IQR is the interquartile range.
|
| | 62 | % 'integers' The integer rule is useful with integer data,
|
| | 63 | % as it creates a bin for each integer. It uses
|
| | 64 | % a bin width of 1 and places bin edges halfway
|
| | 65 | % between integers. To prevent from accidentally
|
| | 66 | % creating too many bins, a limit of 65536 bins
|
| | 67 | % can be created with this rule. If the data
|
| | 68 | % range is greater than 65536, then wider bins
|
| | 69 | % are used instead.
|
| | 70 | % 'sturges' Sturges' rule is a simple rule that is popular
|
| | 71 | % due to its simplicity. It chooses the number of
|
| | 72 | % bins to be CEIL(1 + LOG2(NUMEL(X))).
|
| | 73 | % 'sqrt' The Square Root rule is another simple rule
|
| | 74 | % widely used in other software packages. It
|
| | 75 | % chooses the number of bins to be
|
| | 76 | % CEIL(SQRT(NUMEL(X))).
|
| | 77 | %
|
| | 78 | % [N,EDGES,BIN] = HISTCOUNTS(...) also returns an index array BIN, using
|
| | 79 | % any of the previous syntaxes. BIN is an array of the same size as X
|
| | 80 | % whose elements are the bin indices for the corresponding elements in X.
|
| | 81 | % The number of elements in the kth bin is NNZ(BIN==k), which is the same
|
| | 82 | % as N(k). A value of 0 in BIN indicates an element which does not belong
|
| | 83 | % to any of the bins (for example, a NaN value).
|
| | 84 | %
|
| | 85 | % Class support for inputs X, EDGES:
|
| | 86 | % float: double, single
|
| | 87 | % integers: uint8, int8, uint16, int16, uint32, int32, uint64, int64
|
| | 88 | % logical
|
| | 89 | %
|
| | 90 | % See also HISTOGRAM, HISTCOUNTS2, HISTOGRAM2, DISCRETIZE
|
| | 91 |
|
| | 92 | % Copyright 1984-2015 The MathWorks, Inc.
|
| | 93 |
|
< 0.01 | 135 | 94 | nin = nargin;
|
| | 95 |
|
< 0.01 | 135 | 96 | validateattributes(x,{'numeric','logical'},{'real'}, mfilename, 'x', 1)
|
| | 97 |
|
< 0.01 | 135 | 98 | if nin < 3
|
| | 99 | % optimized code path for no name-value pair inputs
|
< 0.01 | 135 | 100 | opts = [];
|
< 0.01 | 135 | 101 | if nin == 2 && ~isscalar(varargin{1})
|
| | 102 | % bin edges code path
|
< 0.01 | 135 | 103 | in = varargin{1};
|
< 0.01 | 135 | 104 | validateattributes(in,{'numeric','logical'},{'vector','nonempty', ...
|
| 135 | 105 | 'real', 'nondecreasing'}, mfilename, 'edges', 2)
|
< 0.01 | 135 | 106 | edges = in;
|
| | 107 | else
|
| | 108 | % default 'auto' BinMethod and numbins code path
|
| | 109 | if ~isfloat(x)
|
| | 110 | % for integers, the edges are doubles
|
| | 111 | xc = x(:);
|
| | 112 | minx = double(min(xc));
|
| | 113 | maxx = double(max(xc));
|
| | 114 | else
|
| | 115 | xc = x(:);
|
| | 116 | minx = min(xc,[],'includenan');
|
| | 117 | maxx = max(xc,[],'includenan');
|
| | 118 | if ~isempty(x) && ~(isfinite(minx) && isfinite(maxx))
|
| | 119 | % exclude Inf and NaN
|
| | 120 | xc = x(isfinite(x));
|
| | 121 | minx = min(xc);
|
| | 122 | maxx = max(xc);
|
| | 123 | end
|
| | 124 | end
|
| | 125 | if nin == 1 % auto bin method
|
| | 126 | edges = autorule(xc, minx, maxx, false);
|
| | 127 | else % numbins
|
| | 128 | in = varargin{1};
|
| | 129 | validateattributes(in,{'numeric','logical'},{'integer', 'positive'}, ...
|
| | 130 | mfilename, 'm', 2)
|
| | 131 | xrange = maxx - minx;
|
| | 132 | numbins = double(in);
|
| | 133 | edges = binpicker(minx,maxx,numbins,xrange/numbins);
|
| | 134 | end
|
| | 135 | end
|
| | 136 | else
|
| | 137 | % parse through inputs including name-value pairs
|
| | 138 | opts = parseinput(varargin);
|
| | 139 |
|
| | 140 | if isempty(opts.BinLimits) % Bin Limits is not specified
|
| | 141 | if ~isempty(opts.BinEdges)
|
| | 142 | edges = opts.BinEdges;
|
| | 143 | else
|
| | 144 | if ~isfloat(x)
|
| | 145 | % for integers, the edges are doubles
|
| | 146 | xc = x(:);
|
| | 147 | minx = double(min(xc));
|
| | 148 | maxx = double(max(xc));
|
| | 149 | else
|
| | 150 | xc = x(:);
|
| | 151 | minx = min(xc,[],'includenan');
|
| | 152 | maxx = max(xc,[],'includenan');
|
| | 153 | if ~isempty(x) && ~(isfinite(minx) && isfinite(maxx))
|
| | 154 | % exclude Inf and NaN
|
| | 155 | xc = x(isfinite(x));
|
| | 156 | minx = min(xc);
|
| | 157 | maxx = max(xc);
|
| | 158 | end
|
| | 159 | end
|
| | 160 | if ~isempty(opts.NumBins)
|
| | 161 | numbins = double(opts.NumBins);
|
| | 162 | xrange = maxx - minx;
|
| | 163 | edges = binpicker(minx,maxx,numbins,xrange/numbins);
|
| | 164 | elseif ~isempty(opts.BinWidth)
|
| | 165 | if ~isfloat(opts.BinWidth)
|
| | 166 | opts.BinWidth = double(opts.BinWidth);
|
| | 167 | end
|
| | 168 | xrange = maxx - minx;
|
| | 169 | if ~isempty(minx)
|
| | 170 | binWidth = opts.BinWidth;
|
| | 171 | leftEdge = binWidth*floor(minx/binWidth);
|
| | 172 | nbins = max(1,ceil((maxx-leftEdge) ./ binWidth));
|
| | 173 | % Do not create more than maximum bins.
|
| | 174 | MaximumBins = getmaxnumbins();
|
| | 175 | if nbins > MaximumBins % maximum exceeded, recompute
|
| | 176 | % Try setting bin width to xrange/(MaximumBins-1).
|
| | 177 | % In cases where minx is exactly a multiple of
|
| | 178 | % xrange/MaximumBins, then we can set bin width to
|
| | 179 | % xrange/MaximumBins-1 instead.
|
| | 180 | nbins = MaximumBins;
|
| | 181 | binWidth = xrange/(MaximumBins-1);
|
| | 182 | leftEdge = binWidth*floor(minx/binWidth);
|
| | 183 |
|
| | 184 | if maxx <= leftEdge + (nbins-1) * binWidth
|
| | 185 | binWidth = xrange/MaximumBins;
|
| | 186 | leftEdge = minx;
|
| | 187 | end
|
| | 188 | end
|
| | 189 | edges = leftEdge + (0:nbins) .* binWidth; % get exact multiples
|
| | 190 | else
|
| | 191 | edges = cast([0 opts.BinWidth], 'like', xrange);
|
| | 192 | end
|
| | 193 | else % BinMethod specified
|
| | 194 | if strcmp(opts.BinMethod, 'auto')
|
| | 195 | edges = autorule(xc, minx, maxx, false);
|
| | 196 | else
|
| | 197 | switch opts.BinMethod
|
| | 198 | case 'scott'
|
| | 199 | edges = scottsrule(xc,minx,maxx,false);
|
| | 200 | case 'fd'
|
| | 201 | edges = fdrule(xc,minx,maxx,false);
|
| | 202 | case 'integers'
|
| | 203 | edges = integerrule(xc,minx,maxx,false,getmaxnumbins());
|
| | 204 | case 'sqrt'
|
| | 205 | edges = sqrtrule(xc,minx,maxx,false);
|
| | 206 | case 'sturges'
|
| | 207 | edges = sturgesrule(xc,minx,maxx,false);
|
| | 208 | end
|
| | 209 | end
|
| | 210 | end
|
| | 211 | end
|
| | 212 |
|
| | 213 | else % BinLimits specified
|
| | 214 | if ~isfloat(opts.BinLimits)
|
| | 215 | % for integers, the edges are doubles
|
| | 216 | minx = double(opts.BinLimits(1));
|
| | 217 | maxx = double(opts.BinLimits(2));
|
| | 218 | else
|
| | 219 | minx = opts.BinLimits(1);
|
| | 220 | maxx = opts.BinLimits(2);
|
| | 221 | end
|
| | 222 | if ~isempty(opts.NumBins)
|
| | 223 | numbins = double(opts.NumBins);
|
| | 224 | edges = [minx + (0:numbins-1).*((maxx-minx)/numbins), maxx];
|
| | 225 | elseif ~isempty(opts.BinWidth)
|
| | 226 | if ~isfloat(opts.BinWidth)
|
| | 227 | opts.BinWidth = double(opts.BinWidth);
|
| | 228 | end
|
| | 229 | % Do not create more than maximum bins.
|
| | 230 | MaximumBins = getmaxnumbins();
|
| | 231 | binWidth = max(opts.BinWidth, (maxx-minx)/MaximumBins);
|
| | 232 | edges = minx:binWidth:maxx;
|
| | 233 | if edges(end) < maxx || isscalar(edges)
|
| | 234 | edges = [edges maxx];
|
| | 235 | end
|
| | 236 |
|
| | 237 | else % BinMethod specified
|
| | 238 | xc = x(x>=minx & x<=maxx);
|
| | 239 | if strcmp(opts.BinMethod, 'auto')
|
| | 240 | edges = autorule(xc, minx, maxx, true);
|
| | 241 | else
|
| | 242 | switch opts.BinMethod
|
| | 243 | case 'scott'
|
| | 244 | edges = scottsrule(xc,minx,maxx,true);
|
| | 245 | case 'fd'
|
| | 246 | edges = fdrule(xc,minx,maxx,true);
|
| | 247 | case 'integers'
|
| | 248 | edges = integerrule(xc,minx,maxx,true,getmaxnumbins());
|
| | 249 | case 'sqrt'
|
| | 250 | edges = sqrtrule(xc,minx,maxx,true);
|
| | 251 | case 'sturges'
|
| | 252 | edges = sturgesrule(xc,minx,maxx,true);
|
| | 253 | end
|
| | 254 | end
|
| | 255 | end
|
| | 256 | end
|
| | 257 | end
|
| | 258 |
|
< 0.01 | 135 | 259 | edges = full(edges); % make sure edges are non-sparse
|
< 0.01 | 135 | 260 | if nargout <= 2
|
| | 261 | n = histcountsmex(x,edges);
|
< 0.01 | 135 | 262 | else
|
0.01 | 135 | 263 | [n,bin] = histcountsmex(x,edges);
|
< 0.01 | 135 | 264 | end
|
| | 265 |
|
< 0.01 | 135 | 266 | if ~isempty(opts)
|
| | 267 | switch opts.Normalization
|
| | 268 | case 'countdensity'
|
| | 269 | n = n./double(diff(edges));
|
| | 270 | case 'cumcount'
|
| | 271 | n = cumsum(n);
|
| | 272 | case 'probability'
|
| | 273 | n = n / sum(n);
|
| | 274 | case 'pdf'
|
| | 275 | n = n/sum(n)./double(diff(edges));
|
| | 276 | case 'cdf'
|
| | 277 | n = cumsum(n / sum(n));
|
| | 278 | end
|
| | 279 | end
|
| | 280 |
|
< 0.01 | 135 | 281 | end
|
Other subfunctions in this file are not included in this listing.