binscatter

Binned scatter plot

• 

Syntax

binscatter(x,y)

binscatter(x,y,N)

binscatter(tbl,xvar,yvar)

binscatter(tbl,xvar,yvar,N)

binscatter(___,Name,Value)

binscatter(ax,___)

h = binscatter(___)

Description

Vector Data

binscatter(x,y) displays a binned scatter plot for vectors x and y. A binned scatter plot partitions the data space into rectangular bins and displays the count of data points in each bin using different colors. When zooming into the plot, the bin sizes automatically adjust to show finer resolution.

binscatter(x,y,N) specifies the number of bins to use. N can be a scalar or a two-element vector [Nx Ny]. If N is a scalar, then Nx and Ny are both set to the scalar value. The maximum number of bins in each dimension is 250.

Table Data

binscatter(tbl,xvar,yvar) creates a binned scatter plot using the variables xvar and yvar from the table tbl. (since R2026a)

binscatter(tbl,xvar,yvar,N) plots the table data using the specified number of bins. (since R2026a)

Additional Options

binscatter(___,Name,Value) specifies property values with one or more name-value pair arguments. For example, you can specify 'ShowEmptyBins' as 'on' to color areas with no data points. For a full list of properties, see Binscatter Properties. Use this option with any of the input argument combinations in previous syntaxes.

binscatter(ax,___) plots into the axes specified by ax instead of into the current axes (gca). The ax input can precede any of the input argument combinations in previous syntaxes.

h = binscatter(___) returns a Binscatter object. Use this object to inspect and adjust the properties of the binned scatter plot.

Examples

Binned Scatter Plot of Vectors

Generate random numbers in both the x and y dimensions and create a binned scatter plot. The binscatter function automatically chooses an appropriate number of bins to cover the range of values in the data.

x = randn(1e6,1);
y = 2*x + randn(1e6,1);
binscatter(x,y)

Specify Number of Bins

Plot a binned scatter plot of 10,000 random numbers sorted into 30 bins in the x dimension and 10 bins in the y dimension.

rng default % for reproducibility
x = randn(1e4,1);
y = randn(1e4,1);
h = binscatter(x,y,[30 10]);

Find the bin counts. The result is a matrix with the top left element corresponding to the bin count of the bottom left bin in the plot. The x bins are in the rows of the matrix and the y bins are in the columns.

counts = h.Values;

Binned Scatter Plot from Table

Since R2026a

Create a table and plot the variables. When you pass a table to the binscatter function, the axis labels display the variable names.

Alpha = randn(1e6,1);
Lambda = 50*randn(1e6,1);
tbl = table(Alpha,Lambda);
binscatter(tbl,"Alpha","Lambda")

Change Color Map of Binned Scatter Plot

Create a binned scatter plot of some random data points.

x = randn(1e5,1);
y = randn(1e5,1);
binscatter(x,y)

The default color map ranges from light colors (for small values) to dark colors (for large values). Switching to a color map that uses dark colors for small values can make it easier to spot outliers.

Use the colormap function to change the colors in the plot. Pass in the current axes handle using gca.

colormap(gca,'parula')

Adjust Binned Scatter Plot Properties

Generate 1,000 random numbers and create a binned scatter plot. Return the Binscatter object to adjust properties of the plot without recreating the entire plot.

x = randn(1000,1);
y = randn(1000,1);
h = binscatter(x,y)

h = 
  Binscatter with properties:

      NumBins: [11 11]
    XBinEdges: [-3.2764 -2.6485 -2.0206 -1.3927 -0.7648 -0.1369 0.4910 1.1189 1.7468 2.3747 3.0026 3.6305]
    YBinEdges: [-3.1155 -2.5034 -1.8914 -1.2794 -0.6674 -0.0553 0.5567 1.1687 1.7808 2.3928 3.0048 3.6168]
       Values: [11×11 double]
      XLimits: [-3.2764 3.6305]
      YLimits: [-3.1155 3.6168]
    FaceAlpha: 1

  Show all properties

Specify exactly how many bins to use in each direction.

h.NumBins = [20 30];

Turn on the display of empty bins in the plot.

h.ShowEmptyBins = 'on';

Specify the extent of the axes with the XLimits and YLimits properties. Then limit the bin limits in the x direction with a vector.

xlim(gca,h.XLimits); 
ylim(gca,h.YLimits); 
h.XLimits = [-1 1];

Input Arguments

x, y — Input vectors

vectors

Input vectors, specified as real vectors of the same length.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | datetime | duration

tbl — Source table

table | timetable

Source table containing the data to plot, specified as a table or timetable.

xvar — Table variables containing x-coordinates

string scalar | character vector | pattern | numeric scalar | logical vector | vartype subscript

Table variable containing the x-coordinates, specified using one of the indexing schemes from the table. The table variable you specify can contain numeric, logical, datetime, or duration values.

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A pattern object. The pattern object must refer to only one variable.	"A" or 'A' — A variable named A "Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.	3 — The third variable from the table [false false true] — The third variable
Variable type: A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	vartype("double") — The variable containing double values

Example: binscatter(tbl,"Input","Output") specifies the table variable named "Input" for the x-coordinates and the variable named "Output" for the y-coordinates.

Example: binscatter(tbl,2,"Output") specifies the second table variable for the x-coordinates and the variable named "Output" for the y-coordinates.

yvar — Table variable containing y-coordinates

string scalar | character vector | pattern | numeric scalar | logical vector | vartype subscript

Table variable containing the y-coordinates, specified using one of the indexing schemes from the table. The table variable you specify can contain numeric, logical, datetime, or duration values.

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A pattern object. The pattern object must refer to only one variable.	"A" or 'A' — A variable named A "Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.	3 — The third variable from the table [false false true] — The third variable
Variable type: A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	vartype("double") — The variable containing double values

Example: binscatter(tbl,"Input","Output") specifies the table variable named "Input" for the x-coordinates and the variable named "Output" for the y-coordinates.

Example: binscatter(tbl,"Input",2) specifies the table variable named "Input" for the x-coordinates and the second table variable for the y-coordinates.

N — Number of bins

scalar | two-element vector

Number of bins, specified as a scalar or two-element vector [Nx Ny].

• If N is a two-element vector [Nx Ny], then binscatter uses Nx bins in the x dimension and Ny bins in the y dimension.

• If N is a scalar, then Nx and Ny are both set to the scalar value.

binscatter uses Nx and Ny bins along the x and y dimensions in the initial plot, when the axes are not zoomed in. (The axes are not zoomed in when the XLimMode and YLimMode properties are both 'auto'.) When zooming, binscatter adjusts the number of bins to maintain a bin size such that the visible portion of the plot is approximately divided into Nx-by-Ny bins.

The maximum number of bins in each dimension is 250. The default number of bins is computed based on the data size and standard deviation and does not exceed 100.

Example: [10 20]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

ax — Target axes

gca (default) | Axes object

Target axes, specified as an Axes object. If you do not specify the axes, then binscatter uses the current axes (gca).

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: binscatter(x,y,'ShowEmptyBins','on') turns on the display of empty bins in the plot.

The properties listed here are only a subset. For a complete list, see Binscatter Properties.

XLimits — Data limits in x-dimension

vector

Data limits in x-dimension, specified as a two-element vector [Xmin Xmax].

binscatter only displays data points that fall within the specified data limits inclusively, $$X_{\min }\le X\le X_{\max }$$.

Example: [0 10]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

YLimits — Data limits in y-dimension

vector

Data limits in y-dimension, specified as a two-element vector [Ymin Ymax].

binscatter only displays data points that fall within the specified data limits inclusively, $$Y_{\min }\le Y\le Y_{\max }$$.

Example: [0 10]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

ShowEmptyBins — Toggle to show empty bins

'off' (default) | on/off logical value

Toggle to show empty bins, specified as either 'off' or 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Specify 'on' or true to color tiles in the plot that fall within the bin limits, but have no data points.

Output Arguments

h — Binscatter object

Binscatter object

Binscatter object. Use this object to inspect and adjust properties of the plot. For a full listing of properties, see Binscatter Properties.

Tips

• Change the ColorScale property of the axes to 'log' to produce better bin coloring when a few bins dominate the plot.

  ax = gca;
  ax.ColorScale = 'log';

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The binscatter function supports tall arrays with the following usage notes and limitations:

• Tall tables and tall timetables are not supported.

• If you specify your data as a tall array, the binscatter function plots in iterations, progressively adding to the plot as more data is read. During the updates, a progress indicator shows the proportion of data that has been plotted. Zooming and panning is supported during the updating process, before the plot is complete. To stop the update process, press the pause button in the progress indicator.

For more information, see Tall Arrays.

Version History

Introduced in R2017b

R2026a: Pass tables directly to binscatter

Create plots by passing a table to the binscatter function followed by the variables you want to plot. When you specify the data as a table, the axis labels display the table variable names automatically.

R2025a: Plots in UI axes use sky colormap

When you create a binned scatter plot using a UIAxes object, the plot colors come from the sky colormap. Previously, the plot colors came from the parula colormap.