Bivariate histogram bin counts

collapse all in page

## Syntax

`[N,Xedges,Yedges]= histcounts2(X,Y)`

`[N,Xedges,Yedges]= histcounts2(X,Y,nbins)`

`[N,Xedges,Yedges]= histcounts2(X,Y,Xedges,Yedges)`

`[N,Xedges,Yedges]= histcounts2(___,Name,Value)`

`[N,Xedges,Yedges,binX,binY]= histcounts2(___)`

## Description

example

`[N,Xedges,Yedges]= histcounts2(X,Y)`

partitions the values in `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.

example

`[N,Xedges,Yedges]= histcounts2(X,Y,nbins)`

specifiesthe number of bins to use in each dimension.

example

`[N,Xedges,Yedges]= histcounts2(X,Y,Xedges,Yedges)`

partitions `X`

and `Y`

intobins with the bin edges specified by `Xedges`

and `Yedges`

.

example

`[N,Xedges,Yedges]= histcounts2(___,Name,Value)`

specifies additional parameters using one or more name-value arguments for any of the previous syntaxes. For example, specify `BinWidth`

as a two-element vector to adjust the width of the bins in each dimension.

example

`[N,Xedges,Yedges,binX,binY]= histcounts2(___)`

also returns bin indices for the corresponding elements in `X`

and `Y`

.

## Examples

collapse all

### Bin Counts and Bin Edges

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

collapse all

`X,Y`

— Data to distribute among bins (as separate arguments)

vectors | matrices | multidimensional arrays

Data to distribute among bins, specified as separate argumentsof vectors, matrices, or multidimensional arrays. `X`

and `Y`

musthave the same size.

Corresponding elements in `X`

and `Y`

specifythe *x* and *y* coordinates of 2-Ddata points, `[X(k),Y(k)]`

. The data types of `X`

and `Y`

canbe different.

`histcounts2`

ignores all `NaN`

values.Similarly, `histcounts2`

ignores `Inf`

and `-Inf`

valuesunless the bin edges explicitly specify `Inf`

or `-Inf`

asa 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, then`histcounts2`

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`

and`Yedges`

with`BinMethod`

,`BinWidth`

, or`NumBins`

,`histcounts2`

only honors the bin edges and the bin edges must be specified last.If you specify

`Xedges`

with`XBinLimits`

,`histcounts2`

only honors the`Xedges`

and the`Xedges`

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`

and`Xedges`

with`BinMethod`

,`BinWidth`

, or`NumBins`

,`histcounts2`

only honors the bin edges and the bin edges must be specified last.If you specify

`Yedges`

with`YBinLimits`

,`histcounts2`

only honors the`Yedges`

and the`Yedges`

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')`

normalizesthe bin counts in `N`

, such that `sum(N)`

is1.

`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`

.

## Output Arguments

collapse all

`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)`

describethe 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)`

describethe 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.

The

`Normalization`

name-value argument does not support the`'percentage'`

option.

### 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 R2015b**

expand all

### R2023b: 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

## Commande MATLAB

Vous avez cliqué sur un lien qui correspond à cette commande MATLAB:

Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.

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:

### 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
- Deutsch
- English
- Français

- United Kingdom (English)

Contact your local office