hist3

(Not recommended) Bivariate histogram plot

hist3 is not recommended. Use histogram2 instead.

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.

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

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.

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.

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

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

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 two-dimensional.

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

Input Arguments

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"

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

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"

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

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

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