Code covered by the BSD License

# Calculate number of bins for histogram

11 Aug 2008 (Updated )

Automatically calculates the 'best' number of bins for a histogram.

histx(varargin)
```function [n, xout] = histx(varargin)
% A wrapper for hist that picks the "ideal" number of bins to use if
% unspecified.
%
% N = HISTX(Y) bins the elements of Y into M equally spaced containers and
% returns the number of elements in each container.  If Y is a matrix, HIST
% works down the columns.  The value of M is the middle (median) value of
% the optimal number of bins calculated using the Freedman-Diaconis, Scott
% and Sturges methods.  See below for further information on these methods.
%
% N = HISTX(Y,M), where M is a scalar, uses M bins.  (This is identical to
% N = HIST(Y,M).)
%
% N = HISTX(Y, X), where X is a vector, returns the distribution of Y among
% bins with centers specified by X. The first bin includes data between
% -inf and the first center and the last bin includes data between the last
% bin and inf. Note: Use HISTC if it is more natural to specify bin edges
% instead.  (This is identical to N = HIST(Y,X).)
%
% N = HISTX(Y, METHOD), where METHOD is a string chooses the number of bins
% as follows:
%
% 'fd': The Freedman-Diaconis method, based upon the inter-quartile range
% and number of data, is used.
% 'scott': The Scott method, based upon the sample standard deviation and
% nnumber of data, is used.
% 'sturges': The Sturges method, based upon the number of data, is used.
% 'middle': All three methods are tried, and the middle value is used.
%
% N = HISTX(Y, [], MINIMUM), where MINIMUM is a numeric scalar, defines the
% smallest acceptable number of bins.
%
% N = HISTX(Y, [], [], MAXIMUM), where MAXIMUM is a numeric scalar, defines the
% largest acceptable number of bins.
%
% HISTX(...) without output arguments produces a histogram bar plot of the
% results. The bar edges on the first and last bins may extend to cover the
% min and max of the data unless a matrix of data is supplied.
%
% HISTX(Y, 'all') produces three histograms in a new figure window, drawn
% with the number of bins calculated using each of the three methods.
%
% HISTX(AX, ...) plots into AX instead of GCA.
%
% Notes:
% 1. When the method chosen is 'all', any axes inputted will be ignored
% with a warning.  Likewise for output arguments.
%
% 2. References for the methods can be found in the help page for
% CALCNBINS.
%
% Examples:
% y = randn(10000,1);
% histx(y)
% histx(y, 'all')
%
%
% \$ Author: Richard Cotton \$		\$ Date: 2008/08/28 \$    \$ Version 1.1 \$

% Check there is at least one input, and see if the first input is an axis.
error(nargchk(1,inf,nargin,'struct'));
[cax,args,nargs] = axescheck(varargin{:});

plotall = false;
y = args{1};

% If the number of bins wasn't specified, calculate it using calcnbins.
if nargs < 4 || isempty(args{4})
args{4} = []; % this also sets missing arguments before this positon to [].
end

if ~isempty(args{2}) && isnumeric(args{2})
nbins = args{2};
else
nbins = calcnbins(y, args{2}, args{3}, args{4});
if ischar(args{2}) && strcmpi(args{2}, 'all')
plotall = true;
end
end

% Plot the histogram(s)
if plotall
if nargout > 0
warning('histx:ignoreargout', 'No arguments will be returned when the method is "all".');
end
if ~isempty(cax)
warning('histx:ignoreaxes', 'The input axes are ignored when the method is "all".');
end
n = [];
xout = [];
figure();
subplot(3, 1, 1); hist(y, nbins.fd);
title('Freedman-Diaconis'' method');
subplot(3, 1, 2); hist(y, nbins.scott);
title('Scott''s method');
subplot(3, 1, 3); hist(y, nbins.sturges);
title('Sturges'' method');
else
if nargout==0
if isempty(cax)
hist(y, nbins);
else
hist(cax, y, nbins);
end
else
if isempty(cax)
[n, xout] = hist(y, nbins);
else
[n, xout] = hist(cax, y, nbins);
end
end
end```