Bivariate histogram plot

collapse all in page

## Syntax

`hist3(X)`

`hist3(X,'Nbins',nbins)`

`hist3(X,'Ctrs',ctrs)`

`hist3(X,'Edges',edges)`

`hist3(___,Name,Value)`

`hist3(ax,___)`

`N = hist3(___)`

`[N,c] = hist3(___)`

## Description

example

`hist3(X)`

creates a bivariate histogram plot of `X(:,1)`

and `X(:,2)`

using 10-by-10 equally spaced bins. The `hist3`

function displays the bins as 3-D rectangular bars, and the height of each bar indicates the number of elements in the bin.

example

`hist3(X,'Nbins',nbins)`

specifies the number of bins in each dimension of the histogram. This syntax is equivalent to `hist3(X,nbins)`

.

example

`hist3(X,'Ctrs',ctrs)`

specifies the centers of the bins in each dimension of the histogram. This syntax is equivalent to `hist3(X,ctrs)`

.

`hist3(X,'Edges',edges)`

specifies the edges of the bins in each dimension.

example

`hist3(___,Name,Value)`

specifies graphical properties using one or more name-value pair arguments in addition to the input arguments in the previous syntaxes. For example, `'FaceAlpha',0.5`

creates a semitransparent histogram. For a list of properties, see Surface Properties.

`hist3(ax,___)`

plots into the axes specified by `ax`

instead of the current axes (`gca`

). The option `ax`

can precede any of the input argument combinations in the previous syntaxes.

example

`N = hist3(___)`

returns the number of elements in X that fall in each bin. This syntax does not create a histogram.

`[N,c] = hist3(___)`

also returns the bin centers. This syntax does not create a histogram.

## Examples

collapse all

### Histogram of Vectors

Open Live Script

Load the sample data.

`load carbig`

Create a bivariate histogram with the default settings.

X = [MPG,Weight];hist3(X)xlabel('MPG')ylabel('Weight')

### Specify Centers of Histogram Bins

Open Live Script

Create a bivariate histogram on the bins specified by the bin centers, and count the number of elements in each bin.

Load the sample data.

`load carbig`

Create a bivariate histogram. Specify the centers of the histogram bins using a two-element cell array.

X = [MPG,Weight];hist3(X,'Ctrs',{0:10:50 2000:500:5000})xlabel('MPG')ylabel('Weight')

Count the number of elements in each bin.

`N = hist3(X,'Ctrs',{0:10:50 2000:500:5000})`

`N = `*6×7* 0 0 0 0 0 0 0 0 0 2 3 16 26 6 6 34 50 49 27 10 0 70 49 11 3 0 0 0 29 4 2 0 0 0 0 1 0 0 0 0 0 0

### Color Histogram Bars by Height

Open Live Script

Load the sample data.

`load carbig`

Create a bivariate histogram. Specify graphical properties to color the histogram bars by height representing the frequency of the observations.

X = [MPG,Weight];hist3(X,'CDataMode','auto','FaceColor','interp')xlabel('MPG')ylabel('Weight')

### Tiled Histogram View

Open Live Script

Load the sample data.

`load carbig`

Create a bivariate tiled histogram. Specify graphical properties to color the top surface of the histogram bars by the frequency of the observations. Change the view to two-dimensional.

X = [MPG,Weight];hist3(X,'CdataMode','auto')xlabel('MPG')ylabel('Weight')colorbarview(2)

### Adjust Graphical Properties

Open Live Script

Create a bivariate histogram and adjust its graphical properties by using the handle of the histogram surface object.

Load the sample data.

`load carbig`

Create a bivariate histogram with 7 bins in each dimension.

X = [MPG,Weight];hist3(X,'Nbins',[7 7])xlabel('MPG')ylabel('Weight')

The `hist3`

function creates a bivariate histogram, which is a type of surface plot. Find the handle of the surface object and adjust the face transparency.

s = findobj(gca,'Type','Surface');s.FaceAlpha = 0.65;

### Plot Histogram with Intensity Map

Open Live Script

Create a bivariate histogram and add the 2-D projected view of intensities to the histogram.

Load the `seamount`

data set (a *seamount* is an underwater mountain). The data set consists of a set of longitude (`x`

) and latitude (`y`

) locations, and the corresponding `seamount`

elevations (`z`

) measured at those coordinates. This example uses `x`

and `y`

to draw a bivariate histogram.

`load seamount`

Draw a bivariate histogram.

hist3([x,y])xlabel('Longitude')ylabel('Latitude')hold on

Count the number of elements in each bin.

N = hist3([x,y]);

Generate a grid to draw the 2-D projected view of intensities by using pcolor.

N_pcolor = N';N_pcolor(size(N_pcolor,1)+1,size(N_pcolor,2)+1) = 0;xl = linspace(min(x),max(x),size(N_pcolor,2)); % Columns of N_pcoloryl = linspace(min(y),max(y),size(N_pcolor,1)); % Rows of N_pcolor

Draw the intensity map by using `pcolor`

. Set the *z*-level of the intensity map to view the histogram and the intensity map together.

h = pcolor(xl,yl,N_pcolor);colormap('hot') % Change color scheme colorbar % Display colorbarh.ZData = -max(N_pcolor(:))*ones(size(N_pcolor));ax = gca;ax.ZTick(ax.ZTick < 0) = [];title('Seamount Location Histogram and Intensity Map');

## Input Arguments

collapse all

`X`

— Data to distribute among bins

*m*-by-2 numeric matrix

Data to distribute among the bins, specified as an *m*-by-2 numeric matrix, where *m* is the number of data points. Corresponding elements in `X(:,1)`

and `X(:,2)`

specify the *x* and *y* coordinates of 2-D data points.

`hist3`

ignores all `NaN`

values. Similarly, `hist3`

ignores `Inf`

and `–Inf`

values unless you explicitly specify `Inf`

or `–Inf`

as a bin edge by using the edges input argument.

**Data Types: **`single`

| `double`

`nbins`

— Number of bins

`[10 10]`

(default) | two-element vector of positive integers

Number of bins in each dimension, specified as a two-element vector of positive integers. `nbins(1)`

specifies the number of bins in the first dimension, and `nbins(2)`

specifies the number of bins in the second dimension.

**Example: **`[10 20]`

**Data Types: **`single`

| `double`

`ctrs`

— Bin centers

two-element cell array of numeric vectors

Bin centers in each dimension, specified as a two-element cell array of numeric vectors with monotonically nondecreasing values. `ctrs{1}`

and `ctrs{2}`

are the positions of the bin centers in the first and second dimensions, respectively.

`hist3`

assigns rows of `X`

falling outside the range of the grid to the bins along the outer edges of the grid.

**Example: **`{0:10:100 0:50:500}`

**Data Types: **`cell`

`edges`

— Bin edges

two-element cell array of numeric vectors

Bin edges in each dimension, specified as a two-element cell array of numeric vectors with monotonically nondecreasing values. `edges{1}`

and `edges{2}`

are the positions of the bin edges in the first and second dimensions, respectively.

The value `X(k,:)`

is in the `(i,j)`

th bin if `edges{1}(i) ≤ X(k,1) < edges{1}(i+1)`

and `edges{2}(j) ≤ X(k,2) < edges{2}(j+1)`

.

The last bins in each dimension also include the last (outer) edge. For example, `X(k,:)`

falls into the `(I,j)`

th bin if `edges{1}(I–1) ≤ X(k,1) ≤ edges{1}(I)`

and `edges{2}(j) ≤ X(k,2) < edges{2}(j+1)`

, where `I`

is the length of `edges{1}`

. Also, `X(k,:)`

falls into the `(i,J)`

th bin if `edges{1}(i) ≤ X(k,1) < edges{1}(i+1)`

and `edges{2}(J–1) ≤ X(k,2) ≤ edges{2}(J)`

, where `J`

is the length of `edges{2}`

.

`hist3`

does not count rows of `X`

falling outside the range of the grid. Use `–Inf`

and `Inf`

in `edges`

to include all non-`NaN`

values.

**Example: **`{0:10:100 0:50:500}`

**Data Types: **`cell`

`ax`

— Target axes

current axes (`gca`

) (default) | `Axes`

object

Target axes, specified as an axes object. If you do not specify an `Axes`

object, then the `hist3`

function uses the current axes (gca). For details, see Axes Properties.

### 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: **`hist3(X,'FaceColor','interp','CDataMode','auto')`

colors the histogram bars according to the height of the bars.

The graphical properties listed here are only a subset. For a full list, see Surface Properties.

`CDataMode`

— Selection mode for vertex colors

`'manual'`

(default) | `'auto'`

Selection mode for CData (vertex colors), specified as the comma-separated pair consisting of `'CDataMode'`

and one of these values:

`'manual'`

— Use manually specified values in the`CData`

property. The default color in`CData`

is light steel blue corresponding to an RGB triple value of`[0.75 0.85 0.95]`

.`'auto'`

— Use the ZData values to set the colors.`ZData`

contains the*z*-coordinate data for the eight corners of each bar.

**Example: **`'CDataMode','auto'`

`EdgeColor`

— Edge line color

`[0 0 0]`

(default) | `'none'`

| `'flat'`

| `'interp'`

| RGB triplet | hexadecimal color code | color name | short name

Edge line color, specified as the comma-separated pair consisting of `'EdgeColor'`

and one of these values:

`'none'`

— Do not draw the edges.`'flat'`

— Use a different color for each edge based on the values in the CData property.`'interp'`

— Use interpolated coloring for each edge based on the values in the`CData`

property.RGB triplet, hexadecimal color code, color name, or short name — Use the specified color for all the edges. These values do not use the color values in the

`CData`

property.

The default color of `[0 0 0]`

corresponds to black edges.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range

`[0,1]`

; for example,`[0.4 0.6 0.7]`

.A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (

`#`

) followed by three or six hexadecimal digits, which can range from`0`

to`F`

. The values are not case sensitive. Thus, the color codes`"#FF8800"`

,`"#ff8800"`

,`"#F80"`

, and`"#f80"`

are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|---|---|

`"red"` | `"r"` | `[1 0 0]` | `"#FF0000"` | |

`"green"` | `"g"` | `[0 1 0]` | `"#00FF00"` | |

`"blue"` | `"b"` | `[0 0 1]` | `"#0000FF"` | |

`"cyan"` | `"c"` | `[0 1 1]` | `"#00FFFF"` | |

`"magenta"` | `"m"` | `[1 0 1]` | `"#FF00FF"` | |

`"yellow"` | `"y"` | `[1 1 0]` | `"#FFFF00"` | |

`"black"` | `"k"` | `[0 0 0]` | `"#000000"` | |

`"white"` | `"w"` | `[1 1 1]` | `"#FFFFFF"` |

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB^{®} uses in many types of plots.

RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|

`[0 0.4470 0.7410]` | `"#0072BD"` | |

`[0.8500 0.3250 0.0980]` | `"#D95319"` | |

`[0.9290 0.6940 0.1250]` | `"#EDB120"` | |

`[0.4940 0.1840 0.5560]` | `"#7E2F8E"` | |

`[0.4660 0.6740 0.1880]` | `"#77AC30"` | |

`[0.3010 0.7450 0.9330]` | `"#4DBEEE"` | |

`[0.6350 0.0780 0.1840]` | `"#A2142F"` |

**Example: **`'EdgeColor','blue'`

`FaceAlpha`

— Face transparency

1 (default) | scalar in the range `[0,1]`

| `'flat'`

| `'interp'`

| `'texturemap'`

Face transparency, specified as the comma-separated pair consisting of `'FaceAlpha'`

and one of these values:

Scalar in the range

`[0,1]`

— Use uniform transparency across all the faces. A value of`1`

is fully opaque and`0`

is completely transparent. Values between`0`

and`1`

are semitransparent. This option does not use the transparency values in the AlphaData property.`'flat'`

— Use a different transparency for each face based on the values in the`AlphaData`

property. The transparency value at the first vertex determines the transparency for the entire face. This value applies only when you specify the`AlphaData`

property and set the FaceColor property to`'flat'`

.`'interp'`

— Use interpolated transparency for each face based on the values in the`AlphaData`

property. The transparency varies across each face by interpolating the values at the vertices. This value applies only when you specify the`AlphaData`

property and set the`FaceColor`

property to`'interp'`

.`'texturemap'`

— Transform the data in`AlphaData`

so that it conforms to the surface.

**Example: **`'FaceAlpha',0.5`

`FaceColor`

— Face color

`'flat'`

(default) | `'interp'`

| `'none'`

| `'texturemap'`

| RGB triplet | hexadecimal color code | color name | short name

Face color, specified as the comma-separated pair consisting of `'FaceColor'`

and one of these values:

`'flat'`

— Use a different color for each face based on the values in the CData property.`'interp'`

— Use interpolated coloring for each face based on the values in the`CData`

property.`'none'`

— Do not draw the faces.`'texturemap'`

— Transform the color data in`CData`

so that it conforms to the surface.RGB triplet, hexadecimal color code, color name, or short name — Use the specified color for all the faces. These values do not use the color values in the

`CData`

property.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range

`[0,1]`

; for example,`[0.4 0.6 0.7]`

.A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (

`#`

) followed by three or six hexadecimal digits, which can range from`0`

to`F`

. The values are not case sensitive. Thus, the color codes`"#FF8800"`

,`"#ff8800"`

,`"#F80"`

, and`"#f80"`

are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|---|---|

`"red"` | `"r"` | `[1 0 0]` | `"#FF0000"` | |

`"green"` | `"g"` | `[0 1 0]` | `"#00FF00"` | |

`"blue"` | `"b"` | `[0 0 1]` | `"#0000FF"` | |

`"cyan"` | `"c"` | `[0 1 1]` | `"#00FFFF"` | |

`"magenta"` | `"m"` | `[1 0 1]` | `"#FF00FF"` | |

`"yellow"` | `"y"` | `[1 1 0]` | `"#FFFF00"` | |

`"black"` | `"k"` | `[0 0 0]` | `"#000000"` | |

`"white"` | `"w"` | `[1 1 1]` | `"#FFFFFF"` |

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|

`[0 0.4470 0.7410]` | `"#0072BD"` | |

`[0.8500 0.3250 0.0980]` | `"#D95319"` | |

`[0.9290 0.6940 0.1250]` | `"#EDB120"` | |

`[0.4940 0.1840 0.5560]` | `"#7E2F8E"` | |

`[0.4660 0.6740 0.1880]` | `"#77AC30"` | |

`[0.3010 0.7450 0.9330]` | `"#4DBEEE"` | |

`[0.6350 0.0780 0.1840]` | `"#A2142F"` |

**Example: **`'FaceColor','interp'`

`LineStyle`

— Line style

`'-'`

(default) | `'--'`

| `':'`

| `'-.'`

| `'none'`

Line style, specified as the comma-separated pair consisting of `'LineStyle'`

and one of the options in this table.

Line Style | Description | Resulting Line |
---|---|---|

`"-"` | Solid line | |

`"--"` | Dashed line | |

`":"` | Dotted line | |

`"-."` | Dash-dotted line | |

`"none"` | No line | No line |

**Example: **`'LineStyle',':'`

`LineWidth`

— Line width

`0.5`

(default) | positive value

Line width, specified as the comma-separated pair consisting of `'LineWidth'`

and a positive value in points.

**Example: **`'LineWidth',0.75`

**Data Types: **`single`

| `double`

## Output Arguments

collapse all

`N`

— Number of elements in each bin

numeric matrix

Number of elements in X that fall in each bin, returned as a numeric matrix.

`c`

— Bin centers

two-element cell array of numeric vectors

Bin centers in each dimension, returned as a two-element cell array of numeric vectors. `c{1}`

and `c{2}`

are the positions of the bin centers in the first and second dimensions, respectively.

## Tips

The `hist3`

function creates a bivariate histogram, which is a type of surface plot. You can specify surface properties using one or more name-value pair arguments. Also, you can change the appearance of the histogram by changing the surface property values after you create a histogram. Get the handle of the surface object by using `s = findobj(gca,'Type','Surface')`

, and then use `s`

to modify the surface properties. For an example, see Adjust Graphical Properties. For a list of properties, see Surface Properties.

## Alternative Functionality

The histogram2 function enables you to create a bivariate histogram using a `Histogram2`

object. You can use the name-value pair arguments of `histogram2`

to use normalization (Normalization), adjust the width of the bins in each dimension (BinWidth), and display the histogram as a rectangular array of tiles instead of 3-D bars (DisplayStyle).

## Version History

**Introduced before R2006a**

## See Also

accumarray | bar3 | histcounts2 | histogram2 | binScatterPlot

## Comando MATLAB

Hai fatto clic su un collegamento che corrisponde a questo comando MATLAB:

Esegui il comando inserendolo nella finestra di comando MATLAB. I browser web non supportano i comandi 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