histcounts2
Bivariate histogram bin counts
Syntax
Description
[
partitions the values in N
,Xedges
,Yedges
]
= histcounts2(X,Y
)X
and
Y
into 2-D bins and returns the bin counts and the bin edges
in each dimension. The histcounts2
function uses an automatic
binning algorithm that returns uniform bins chosen to cover the range of values in
X
and Y
and reveal the underlying shape of
the distribution.
[
specifies additional
parameters using one or more name-value arguments for any of the previous syntaxes.
For example, specify N
,Xedges
,Yedges
]
= histcounts2(___,Name,Value
)BinWidth
as a two-element vector to adjust
the width of the bins in each dimension.
Examples
Bin Counts and Bin Edges
Distribute 100 pairs of random numbers into bins. histcounts2
automatically chooses an appropriate bin width to reveal the underlying distribution of the data.
x = randn(100,1); y = randn(100,1); [N,Xedges,Yedges] = histcounts2(x,y)
N = 7×6
0 0 0 2 0 0
1 2 10 4 0 0
1 4 9 9 5 0
1 4 10 11 5 1
1 4 6 3 1 1
0 0 1 2 0 0
0 0 1 0 1 0
Xedges = 1×8
-3 -2 -1 0 1 2 3 4
Yedges = 1×7
-3 -2 -1 0 1 2 3
Specify Number of Bins in Each Dimension
Distribute 10 pairs of numbers into 12 bins. Specify 3 bins in the x-dimension, and 4 bins in the y-dimension.
x = [1 1 2 3 2 2 1 1 2 3]; y = [5 6 3 8 9 1 2 7 5 1]; nbins = [3 4]; [N,Xedges,Yedges] = histcounts2(x,y,nbins)
N = 3×4
1 0 2 1
1 1 1 1
1 0 0 1
Xedges = 1×4
0.6000 1.4000 2.2000 3.0000
Yedges = 1×5
0 2.3000 4.6000 6.9000 9.2000
Specify Bin Edges
Distribute 1,000 pairs of random numbers into bins. Define the bin edges with two vectors: one each for the x and y dimensions. The first element in each vector specifies the first edge of the first bin, and the last element is the last edge of the last bin.
x = randn(1000,1); y = randn(1000,1); Xedges = -5:5; Yedges = [-5 -4 -2 -1 -0.5 0 0.5 1 2 4 5]; N = histcounts2(x,y,Xedges,Yedges)
N = 10×10
0 0 0 0 0 0 0 0 0 0
0 0 0 0 1 1 1 0 0 0
0 0 5 5 3 5 1 2 0 0
0 2 19 23 29 25 26 20 5 0
0 10 36 51 59 71 54 46 10 0
0 7 43 46 79 64 60 46 9 0
0 3 12 18 21 23 19 9 6 0
0 0 5 3 2 8 2 2 0 0
0 0 0 1 1 1 0 0 0 0
0 0 0 0 0 0 0 0 0 0
Normalized Bin Counts
Distribute 1,000 pairs of random numbers into bins. Specify Normalization
as 'probability'
to normalize the bin counts such that sum(N(:))
is 1
. That is, each bin count represents the probability that an observation falls within that bin.
x = randn(1000,1); y = randn(1000,1); [N,Xedges,Yedges] = histcounts2(x,y,6,'Normalization','probability')
N = 6×6
0 0 0.0020 0.0020 0 0
0 0.0110 0.0320 0.0260 0.0070 0.0010
0.0010 0.0260 0.1410 0.1750 0.0430 0.0060
0 0.0360 0.1620 0.1940 0.0370 0.0040
0 0.0040 0.0300 0.0370 0.0100 0.0010
0 0.0030 0.0040 0.0040 0.0010 0
Xedges = 1×7
-4.0000 -2.7000 -1.4000 -0.1000 1.2000 2.5000 3.8000
Yedges = 1×7
-4.0000 -2.7000 -1.4000 -0.1000 1.2000 2.5000 3.8000
Determine Bin Placement
Distribute 1,000 random integer pairs between -10 and 10 into bins, and specify BinMethod
as 'integers'
to use unit-width bins centered on integers. Specify five outputs for histcounts2
to return vectors representing the bin placement of the data.
x = randi([-10,10],1000,1); y = randi([-10,10],1000,1); [N,Xedges,Yedges,binX,binY] = histcounts2(x,y,'BinMethod','integers');
Determine which bin the value (x(3),y(3))
falls into.
[x(3),y(3)]
ans = 1×2
-8 10
bin = [binX(3) binY(3)]
bin = 1×2
3 21
Input Arguments
X,Y
— Data to distribute among bins (as separate arguments)
vectors | matrices | multidimensional arrays
Data to distribute among bins, specified as separate arguments
of vectors, matrices, or multidimensional arrays. X
and Y
must
have the same size.
Corresponding elements in X
and Y
specify
the x and y coordinates of 2-D
data points, [X(k),Y(k)]
. The data types of X
and Y
can
be different.
histcounts2
ignores all NaN
values.
Similarly, histcounts2
ignores Inf
and -Inf
values
unless the bin edges explicitly specify Inf
or -Inf
as
a bin edge.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
nbins
— Number of bins in each dimension
positive integer scalar | two-element vector of positive integers
Number of bins in each dimension, specified as a positive integer scalar or two-element vector of positive integers.
If
nbins
is a scalar, thenhistcounts2
uses that many bins in each dimension.If
nbins
is a vector, then the first element gives the number of bins in the x-dimension, and the second element gives the number of bins in the y-dimension.
If you do not specify nbins
, then histcounts2
automatically calculates how many bins to
use based on the values in X
and
Y
.
If you specify nbins
with BinMethod
or BinWidth
, histcounts2
only honors the last parameter.
Example: [N,Xedges,Yedges] =
uses 15 bins in the
histcounts2
(X,Y,15)x
-dimension and in the
y
-dimension.
Example: [N,Xedges,Yedges] =
uses 15 bins in the histcounts2
(X,Y,[15
20])x
-dimension and 20
bins in the y
-dimension.
Xedges
— Bin edges in x-dimension
vector
Bin edges in x-dimension, specified as a vector. The first element specifies the leading edge of the first bin in the x-dimension. The last element specifies the trailing edge of the last bin in the x-dimension. The trailing edge is only included for the last bin.
If you specify
Xedges
andYedges
withBinMethod
,BinWidth
, orNumBins
,histcounts2
only honors the bin edges and the bin edges must be specified last.If you specify
Xedges
withXBinLimits
,histcounts2
only honors theXedges
and theXedges
must be specified last.
Yedges
— Bin edges in y-dimension
vector
Bin edges in y-dimension, specified as a vector. The first element specifies the leading edge of the first bin in the y-dimension. The last element specifies the trailing edge of the last bin in the y-dimension. The trailing edge is only included for the last bin.
If you specify
Yedges
andXedges
withBinMethod
,BinWidth
, orNumBins
,histcounts2
only honors the bin edges and the bin edges must be specified last.If you specify
Yedges
withYBinLimits
,histcounts2
only honors theYedges
and theYedges
must be specified last.
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: [N,Xedges,Yedges] = histcounts2(X,Y,'Normalization','probability')
normalizes
the bin counts in N
, such that sum(N)
is
1.
BinWidth
— Width of bins in each dimension
two-element vector of positive values
Width of bins in each dimension, specified as a two-element vector of positive values. The first element gives the width of the bins in the x-dimension, and the second element gives the width of the bins in the y-dimension.
If you specify BinWidth
, then histcounts2
can use a maximum of 1024 bins (210) along each dimension. If instead the specified bin width requires
more bins, then histcounts2
uses a larger bin width
corresponding to the maximum number of bins.
If you specify BinWidth
with BinMethod
or
NumBins
, histcounts2
only
honors the last parameter.
Example:
uses bins with size histcounts2
(X,Y,'BinWidth',[5
10])5
in the
x
-dimension and size 10
in the
y-dimension.
XBinLimits
— Bin limits in x-dimension
two-element vector
Bin limits in x-dimension, specified as a two-element vector,
[xbmin,xbmax]
. The first element indicates the first bin edge in
the x-dimension. The second element indicates the last bin edge in
the x-dimension.
This option only bins data that falls within the bin limits inclusively,
X>=xbmin & X<=xbmax
.
YBinLimits
— Bin limits in y-dimension
two-element
vector
Bin limits in y-dimension, specified as a two-element vector,
[ybmin,ybmax]
. The first element indicates the first bin edge in
the y-dimension. The second element indicates the last bin edge in
the y-dimension.
This option only bins data that falls within the bin limits inclusively,
Y>=ybmin & Y<=ybmax
.
BinMethod
— Binning algorithm
'auto'
(default) | 'scott'
| 'fd'
| 'integers'
Binning algorithm, specified as one of the values in this table.
Value | Description |
---|---|
'auto' | The default |
'scott' | Scott’s rule is optimal if the data is close to being jointly
normally distributed. This rule is appropriate for most other
distributions, as well. It uses a bin size of
|
'fd' | The Freedman-Diaconis rule is less sensitive to outliers in the
data, and might be more suitable for data with heavy-tailed
distributions. It uses a bin size of
|
'integers' | The integer rule is useful with integer data, as it creates bins centered on pairs of integers. It uses a bin width of 1 for each dimension and places bin edges halfway between integers. To avoid accidentally creating too many bins, you can use this rule to create a limit of 1024 bins (210). If the data range for either dimension is greater than 1024, then the integer rule uses wider bins instead. |
histcounts2
adjusts the number of bins slightly so that the bin edges fall on "nice" numbers, rather than using these exact formulas.If you set the
NumBins
,XBinEdges
,YBinEdges
,BinWidth
,XBinLimits
, orYBinLimits
properties, thenBinMethod
is set to'manual'
.If you specify
BinMethod
withBinWidth
orNumBins
,histcounts2
only honors the last parameter.
Example:
centers the 2-D bins on each
pair of integers.histcounts2
(X,Y,'BinMethod','integers')
Normalization
— Type of normalization
'count'
(default) | 'probability'
| 'percentage'
| 'countdensity'
| 'cumcount'
| 'pdf'
| 'cdf'
Type of normalization, specified as one of the values in this table. For each
bin i
:
is the bin value.
is the number of elements in the bin.
is the area of the bin, computed using the x and y bin widths.
is the number of elements in the input data. This value can be greater than the binned data if the data contains missing values or if some of the data lies outside the bin limits.
Value | Bin Values | Notes |
---|---|---|
'count' (default) |
|
|
'probability' |
|
|
'percentage' |
|
|
'countdensity' |
|
|
'cumcount' |
|
|
'pdf' |
|
|
'cdf' |
|
|
Example:
bins the data
using an estimate of the probability density function.histcounts2
(X,Y,'Normalization','pdf')
Output Arguments
N
— Bin counts
array
Bin counts, returned as an array.
The binning scheme includes the leading x-dimension and y-dimension edge of each bin as well as the trailing edge for the last bins along the x-dimension and y-dimension.
For example, the (1,1)
bin includes values that fall on the first edge in
each dimension, and the last bin in the bottom right includes values that
fall on any of its edges.
Xedges
— Bin edges in x-dimension
vector
Bin edges in x-dimension, returned as a vector. The first element is the leading edge of the first bin in the x-dimension. The last element is the trailing edge of the last bin in the x-dimension.
Yedges
— Bin edges in y-dimension
vector
Bin edges in y-dimension, returned as a vector. The first element is the leading edge of the first bin in the y-dimension. The last element is the trailing edge of the last bin in the y-dimension.
binX
— Bin index in x-dimension
array
Bin index in x-dimension, returned as an array of the same size as
X
. Corresponding elements in binX
and binY
describe which numbered bin contains the
corresponding values in X
and Y
. A
value of 0
in binX
or
binY
indicates an element that does not belong to any
of the bins (such as a NaN
value).
For example, binX(1)
and binY(1)
describe
the bin placement for the value [X(1),Y(1)]
.
binY
— Bin index in y-dimension
array
Bin index in y-dimension, returned as an array of the same size as
Y
. Corresponding elements in binX
and binY
describe which numbered bin contains the
corresponding values in X
and Y
. A
value of 0
in binX
or
binY
indicates an element that does not belong to any
of the bins (such as a NaN
value).
For example, binX(1)
and binY(1)
describe
the bin placement for the value [X(1),Y(1)]
.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
Code generation does not support sparse matrix inputs for this function.
If you do not supply bin edges, then code generation might require variable-size arrays and dynamic memory allocation.
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.
Version History
Introduced in R2015bR2023b: Normalize using percentages
You can normalize histogram values as percentages by specifying the
Normalization
name-value argument as
'percentage'
.
See Also
histogram
| histcounts
| discretize
| histogram2
| morebins
| fewerbins
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)