Replace Discouraged Instances of hist and histc
Old Histogram Functions (hist
, histc
)
Earlier versions of MATLAB^{®} use the hist
and histc
functions as the primary way to create histograms and calculate histogram bin
counts. These functions, while good for some general purposes, have limited overall
capabilities. The use of hist
and histc
in
new code is discouraged for these reasons (among others):
After using
hist
to create a histogram, modifying properties of the histogram is difficult and requires recomputing the entire histogram.The default behavior of
hist
is to use 10 bins, which is not suitable for many data sets.Plotting a normalized histogram requires manual computations.
hist
andhistc
do not have consistent behavior.
Recommended Histogram Functions
The histogram
, histcounts
, and discretize
functions dramatically advance the capabilities of
histogram creation and calculation in MATLAB, while still promoting consistency and ease of use.
histogram
, histcounts
, and
discretize
are the recommended histogram creation and
computation functions for new code.
Of particular note are the following changes, which stand as
improvements over hist
and
histc
:
histogram
can return a histogram object. You can use the object to modify properties of the histogram.Both
histogram
andhistcounts
have automatic binning and normalization capabilities, with several common options builtin.histcounts
is the primary calculation function forhistogram
. The result is that the functions have consistent behavior.discretize
provides additional options and flexibility for determining the bin placement of each element.
Differences Requiring Code Updates
Despite the aforementioned improvements, there are several important differences between the old and now recommended functions, which might require updating your code. The tables summarize the differences between the functions and provide suggestions for updating code.
Code Updates for hist
Difference  Old behavior with hist  New behavior with
histogram 

Input matrices 
A = randn(100,2); hist(A) 
A = randn(100,2); h1 = histogram(A(:,1),10) edges = h1.BinEdges; hold on h2 = histogram(A(:,2),edges) The
above code example uses the same bin edges for each histogram,
but in some cases it is better to set the

Bin specification 

To
convert bin centers into bin edges for use with
Note In cases where the bin centers used with
histogram(A,'BinLimits',[3,3],'BinMethod','integers') 
Output arguments 
A = randn(100,1); [N, Centers] = hist(A) 
A = randn(100,1); h = histogram(A); N = h.Values Edges = h.BinEdges Note To calculate bin counts (without plotting a histogram),
replace 
Default number of bins 
 Both A = randn(100,1); histogram(A) histcounts(A) 
Bin limits 
 If To
reproduce the results of A = randi(5,100,1); histogram(A,10,'BinLimits',[min(A) max(A)]) 
Code Updates for histc
Difference  Old behavior with histc  New behavior with
histcounts 

Input matrices 
A = randn(100,10); edges = 4:4; N = histc(A,edges) 
A = randn(100,10); edges = 4:4; N = histcounts(A,edges) Use a forloop to calculate bin counts over each column. A = randn(100,10); nbins = 10; N = zeros(nbins, size(A,2)); for k = 1:size(A,2) N(:,k) = histcounts(A(:,k),nbins); end If
performance is a problem due to a large number of columns in the
matrix, then consider continuing to use

Values included in last bin 

A = 1:4; edges = [1 2 2.5 3] N = histcounts(A) N = histcounts(A,edges) The
last bin from N = histcounts(A,'BinMethod','integers'); 
Output arguments 
A = randn(15,1); edges = 4:4; [N,Bin] = histc(A,edges) 

Convert Bin Centers to Bin Edges
The hist
function accepts bin centers, whereas the histogram
function accepts bin edges. To update code to use histogram
, you might need to convert bin centers to bin edges to reproduce results achieved with hist
.
For example, specify bin centers for use with hist
. These bins have a uniform width.
A = [9 6 5 2 0 1 3 3 4 7]; centers = [7.5 2.5 2.5 7.5]; hist(A,centers)
To convert the bin centers into bin edges, calculate the midpoint between consecutive values in centers
. This method reproduces the results of hist
for both uniform and nonuniform bin widths.
d = diff(centers)/2; edges = [centers(1)d(1), centers(1:end1)+d, centers(end)+d(end)];
The hist
function includes values falling on the right edge of each bin (the first bin includes both edges), whereas histogram
includes values that fall on the left edge of each bin (and the last bin includes both edges). Shift the bin edges slightly to obtain the same bin counts as hist
.
edges(2:end) = edges(2:end)+eps(edges(2:end))
edges = 1×5
10.0000 5.0000 0.0000 5.0000 10.0000
Now, use histogram
with the bin edges.
histogram(A,edges)