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
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).
example
hist3(X,'Edges',edges) specifies the edges of the bins in each dimension.
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.
example
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.
N = hist3(___) returns the number of elements in X that fall in each bin. This syntax does not create a histogram.
example
[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 carbigCreate 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 carbigCreate 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 0Color Histogram Bars by Height
Open Live Script
Load the sample data.
load carbigCreate 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 carbigCreate 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 carbigCreate 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 seamountDraw 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 theCDataproperty. The default color inCDatais 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.ZDatacontains 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 theCDataproperty.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
CDataproperty.
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 from0toF. 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 of1is fully opaque and0is completely transparent. Values between0and1are 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 theAlphaDataproperty. The transparency value at the first vertex determines the transparency for the entire face. This value applies only when you specify theAlphaDataproperty and set the FaceColor property to'flat'.'interp'— Use interpolated transparency for each face based on the values in theAlphaDataproperty. The transparency varies across each face by interpolating the values at the vertices. This value applies only when you specify theAlphaDataproperty and set theFaceColorproperty to'interp'.'texturemap'— Transform the data inAlphaDataso 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 theCDataproperty.'none'— Do not draw the faces.'texturemap'— Transform the color data inCDataso 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
CDataproperty.
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 from0toF. 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
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:
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
