Syntax

Description

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.

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.

Plot Histogram with Intensity Map

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.

Input Arguments

X — Data to distribute among binsm-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.

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 centerstwo-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 edgestwo-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 axescurrent 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 Pair Arguments

Specify optional
comma-separated pairs of Name,Value arguments. Name is
the argument name and Value is the corresponding value.
Name must appear inside quotes. You can specify several name and value
pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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.

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 or color name — Use the specified color for
all the edges. This option does not use the color values in
the CData property.

The default color of [0 0 0]
corresponds to black edges.

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].
Alternatively, you can specify some common colors by name. This table lists the long and short
color name options and the equivalent RGB triplet values.

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.

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 or color name — Use the specified color for
all the faces. This option does not use the color values in
the CData property.

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].
Alternatively, you can specify some common colors by name. This table lists the long and short
color name options and the equivalent RGB triplet values.

Option

Description

Equivalent RGB Triplet

'red' or 'r'

Red

[1 0 0]

'green' or 'g'

Green

[0 1 0]

'blue' or 'b'

Blue

[0 0 1]

'yellow' or 'y'

Yellow

[1 1 0]

'magenta' or 'm'

Magenta

[1 0 1]

'cyan' or 'c'

Cyan

[0 1 1]

'white' or 'w'

White

[1 1 1]

'black' or 'k'

Black

[0 0 0]

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 width0.5 (default) | positive value

Line width, specified as the comma-separated pair consisting of
'LineWidth' and a positive value in
points.

Output Arguments

N — Number of elements in each binnumeric matrix

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

c — Bin centerstwo-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').