Main Content

hist3

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

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

Figure contains an axes object. The axes object with xlabel MPG, ylabel Weight contains an object of type surface.

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

Figure contains an axes object. The axes object with xlabel MPG, ylabel Weight contains an object of type surface.

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

Figure contains an axes object. The axes object with xlabel MPG, ylabel Weight contains an object of type surface.

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')
colorbar
view(2)

Figure contains an axes object. The axes object with xlabel MPG, ylabel Weight contains an object of type surface.

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

Figure contains an axes object. The axes object with xlabel MPG, ylabel Weight contains an object of type surface.

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;

Figure contains an axes object. The axes object with xlabel MPG, ylabel Weight contains an object of type surface.

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

Figure contains an axes object. The axes object with xlabel Longitude, ylabel Latitude contains an object of type surface.

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_pcolor
yl = 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 colorbar
h.ZData = -max(N_pcolor(:))*ones(size(N_pcolor));
ax = gca;
ax.ZTick(ax.ZTick < 0) = [];
title('Seamount Location Histogram and Intensity Map');

Figure contains an axes object. The axes object with title Seamount Location Histogram and Intensity Map, xlabel Longitude, ylabel Latitude contains 2 objects of type surface.

Input Arguments

collapse all

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

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

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

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

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.

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'

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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

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

Sample of the color green

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

Sample of the color blue

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

Sample of the color cyan

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

Sample of the color magenta

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

Sample of the color yellow

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

Sample of the color black

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

Sample of the color white

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

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Example: 'EdgeColor','blue'

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

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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

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

Sample of the color green

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

Sample of the color blue

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

Sample of the color cyan

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

Sample of the color magenta

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

Sample of the color yellow

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

Sample of the color black

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

Sample of the color white

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

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Example: 'FaceColor','interp'

Line style, specified as the comma-separated pair consisting of 'LineStyle' and one of the options in this table.

Line StyleDescriptionResulting Line
"-"Solid line

Sample of solid line

"--"Dashed line

Sample of dashed line

":"Dotted line

Sample of dotted line

"-."Dash-dotted line

Sample of dash-dotted line, with alternating dashes and dots

"none"No lineNo line

Example: 'LineStyle',':'

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

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

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

| | | |