hist3
Bivariate histogram plot
Syntax
Description
hist3(
creates a bivariate
histogram plot of X
)X(:,1)
and X(:,2)
using
10by10 equally spaced bins. The hist3
function displays
the bins as 3D rectangular bars, and the height of each bar indicates the
number of elements in the bin.
hist3(___,
specifies graphical properties using one or more namevalue pair arguments in
addition to the input arguments in the previous syntaxes. For example,
Name,Value
)'FaceAlpha',0.5
creates a semitransparent histogram. For
a list of properties, see Surface Properties.
hist3(
plots into
the axes specified by ax
,___)ax
instead of the current axes
(gca
). The option ax
can precede any
of the input argument combinations in the previous syntaxes.
Examples
Histogram of Vectors
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
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 twoelement 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
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
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 twodimensional.
X = [MPG,Weight]; hist3(X,'CdataMode','auto') xlabel('MPG') ylabel('Weight') colorbar view(2)
Adjust Graphical Properties
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
Create a bivariate histogram and add the 2D 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 2D 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_pcolor yl = linspace(min(y),max(y),size(N_pcolor,1)); % Rows of N_pcolor
Draw the intensity map by using pcolor
. Set the zlevel 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 colorbar h.ZData = max(N_pcolor(:))*ones(size(N_pcolor)); ax = gca; ax.ZTick(ax.ZTick < 0) = []; title('Seamount Location Histogram and Intensity Map');
Input Arguments
X
— Data to distribute among bins
mby2 numeric matrix
Data to distribute among the bins, specified as an
mby2 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 2D 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)  twoelement vector of positive integers
Number of bins in each dimension, specified as a twoelement 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
twoelement cell array of numeric vectors
Bin centers in each dimension, specified as a twoelement 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
twoelement cell array of numeric vectors
Bin edges in each dimension, specified as a twoelement 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
nonNaN
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.
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue 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 commaseparated pair consisting of
'CDataMode'
and one of these values:
'manual'
— Use manually specified values in theCData
property. The default color inCData
is light steel blue corresponding to an RGB triple value of[0.75 0.85 0.95]
.'auto'
— Use theZData
values to set the colors.ZData
contains the zcoordinate 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 commaseparated 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 theCData
property.'interp'
— Use interpolated coloring for each edge based on the values in theCData
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 threeelement 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 from0
toF
. 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 commaseparated pair consisting of
'FaceAlpha'
and one of these values:
Scalar in the range
[0,1]
— Use uniform transparency across all the faces. A value of1
is fully opaque and0
is completely transparent. Values between0
and1
are semitransparent. This option does not use the transparency values in theAlphaData
property.'flat'
— Use a different transparency for each face based on the values in theAlphaData
property. The transparency value at the first vertex determines the transparency for the entire face. This value applies only when you specify theAlphaData
property and set theFaceColor
property to'flat'
.'interp'
— Use interpolated transparency for each face based on the values in theAlphaData
property. The transparency varies across each face by interpolating the values at the vertices. This value applies only when you specify theAlphaData
property and set theFaceColor
property to'interp'
.'texturemap'
— Transform the data inAlphaData
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 commaseparated pair consisting of
'FaceColor'
and one of these values:
'flat'
— Use a different color for each face based on the values in theCData
property.'interp'
— Use interpolated coloring for each face based on the values in theCData
property.'none'
— Do not draw the faces.'texturemap'
— Transform the color data inCData
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 threeelement 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 from0
toF
. 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 commaseparated pair consisting of
'LineStyle'
and one of the options in this
table.
Line Style  Description  Resulting Line 

""  Solid line 

""  Dashed line 

":"  Dotted line 

"."  Dashdotted line 

"none"  No line  No line 
Example: 'LineStyle',':'
LineWidth
— Line width
0.5
(default)  positive value
Line width, specified as the commaseparated pair consisting of
'LineWidth'
and a positive value in
points.
Example: 'LineWidth',0.75
Data Types: single
 double
Output Arguments
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
twoelement cell array of numeric vectors
Bin centers in each dimension, returned as a twoelement 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 namevalue 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
namevalue 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 3D bars (DisplayStyle
).
Version History
Introduced before R2006a
See Also
accumarray
 bar3
 histcounts2
 histogram2
 binScatterPlot
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
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)