Input matrices

hist creates a histogram for each column of an input matrix and plots the histograms side-by-side in the same figure.

A = randn(100,2);
hist(A)

histogram treats the input matrix as a single tall vector and creates a single histogram. To plot multiple histograms, create a different histogram object for each column of data. Use the hold on command to plot the histograms in the same figure.

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 BinWidth of each histogram to be the same instead. Also, for display purposes, it might be helpful to set the FaceAlpha property of each histogram, as this affects the transparency of overlapping bars.

Bin specification

hist accepts the bin centers as a second input.

histogram accepts the bin edges as a second input.

To convert bin centers into bin edges for use with histogram, see Convert Bin Centers to Bin Edges.

Note:   In cases where the bin centers used with hist are integers, such as hist(A,-3:3), use the new built-in binning method of histogram for integers. histogram(A,'BinLimits',[-3,3],'BinMethod','integers')

Output arguments

hist returns the bin counts as an output argument, and optionally can return the bin centers as a second output argument.

A = randn(100,1);
[N, Centers] = hist(A)

histogram returns a histogram object as an output argument. The object contains many properties of interest (bin counts, bin edges, and so on). You can modify aspects of the histogram by changing its property values. For more information, see histogram.

A = randn(100,1);
h = histogram(A);
N = h.Values
Edges = h.BinEdges

Note:   To calculate bin counts (without plotting a histogram), replace [N, Centers] = hist(A) with [N,edges] = histcounts(A,nbins).

Default number of bins

hist uses 10 bins by default.

Both histogram and histcounts use an automatic binning algorithm by default. The number of bins is determined by the size and spread of the input data.

A = randn(100,1);
histogram(A)
histcounts(A)

Bin limits

hist uses the minimum and maximum finite data values to determine the left and right edges of the first and last bar in the plot. -Inf and Inf are included in the first and last bin, respectively.

If BinLimits is not set, then histogram uses rational bin limits based on, but not exactly equal to, the minimum and maximum finite data values. histogram ignores Inf values unless one of the bin edges explicitly specifies Inf or -Inf as a bin edge.

To reproduce the results of hist(A) for finite data (no Inf values), use 10 bins and explicitly set BinLimits to the minimum and maximum data values.

A = randi(5,100,1);
histogram(A,10,'BinLimits',[min(A) max(A)])

histc calculates the bin counts for each column of input data. For an input matrix of size m-by-n, histc returns a matrix of bin counts of size length(edges)-by-n.

A = randn(100,10);
edges = -4:4;
N = histc(A,edges)

histcounts treats the input matrix as a single tall vector and calculates the bin counts for the entire matrix.

A = randn(100,10);
edges = -4:4;
N = histcounts(A,edges)

Use a for-loop 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 histc for the column-wise bin counts.

histc includes an element A(i) in the last bin if A(i) == edges(end). The output, N, is a vector with length(edges) elements containing the bin counts. Values falling outside the bins are not counted.

histcounts includes an element A(i) in the last bin if edges(end-1) <= A(i) <= edges(end). In other words, histcounts combines the last two bins from histc into a single final bin. The output, N, is a vector with length(edges)-1 elements containing the bin counts. If you specify the bin edges, then values falling outside the bins are not counted. Otherwise, histcounts automatically determines the proper bin edges to use to include all of the data.

A = 1:4;
edges = [1 2 2.5 3]
N = histcounts(A)
N = histcounts(A,edges)

histc returns the bin counts as an output argument, and optionally can return the bin indices as a second output argument.

A = randn(15,1);
edges = -4:4;
[N,Bin] = histc(A,edges)

• For bin count calculations like N = histc(A,edges) or [N,bin] = histc(A,edges), use histcounts. The histcounts function returns the bin counts as an output argument, and optionally can return the bin edges as a second output, or the bin indices as a third output.

  A = randn(15,1);
  [N,Edges,Bin] = histcounts(A)

• For bin placement calculations like [~,Bin] = histc(A,edges), use discretize. The discretize function offers additional options for determining the bin placement of each element.

  A = randn(15,1);
  edges = -4:4;
  Bin = discretize(A,edges)