polarhistogram

R2026b

Histogram chart in polar coordinates

• 

Syntax

polarhistogram(theta)

polarhistogram(theta,nbins)

polarhistogram(theta,edges)

polarhistogram(BinEdges=edges,BinCounts=counts)

polarhistogram(tbl,datavar)

polarhistogram(tbl,datavar,nbins)

polarhistogram(tbl,datavar,edges)

polarhistogram(___,Name=Value)

polarhistogram(pax,___)

h = polarhistogram(___)

Description

Vector and Matrix Data

polarhistogram(theta) creates a histogram plot in polar coordinates by sorting the values in theta into equally spaced bins. Specify the values in radians.

polarhistogram(theta,nbins) uses the number of bins specified by the positive integer, nbins.

polarhistogram(theta,edges) sorts theta into bins with bin edges specified by the vector, edges. All bins include the left edge, but only the last bin includes the right edge. In other words, the last bin includes both edges.

polarhistogram(BinEdges=edges,BinCounts=counts) uses the manually specified bin edges and associated bin counts without doing any data binning.

Table Data

Since R2026a

polarhistogram(tbl,datavar) creates a histogram using the variable datavar from the table tbl. The variable you specify can contain values of any numeric type.

polarhistogram(tbl,datavar,nbins) uses table data and the specified number of bins.

polarhistogram(tbl,datavar,edges) uses table data and the specified bin edges.

Additional Options

polarhistogram(___,Name=Value) specifies additional options using one or more name-value arguments. For example, you can use semitransparent bars by specifying FaceAlpha as a scalar value between 0 and 1.

polarhistogram(pax,___) plots into the polar axes specified by pax instead of into the current axes.

h = polarhistogram(___) returns the Histogram object. Use h to modify the histogram after it is created. For a list of properties, see Histogram Properties.

Examples

Create Histogram Chart in Polar Coordinates

Create a vector of values between 0 and $$2\pi$$. Create a histogram chart that shows the data sorted into six bins.

theta = [0.1 1.1 5.4 3.4 2.3 4.5 3.2 3.4 5.6 2.3 2.1 3.5 0.6 6.1];
polarhistogram(theta,6)

Before R2022a, polar axes do not include degree symbols by default. To add them, get the polar axes using pax = gca. Then modify the tick labels using pax.ThetaTickLabel = string(pax.ThetaTickLabel) + char(176).

Specify Number of Bins for Polar Histogram Chart

Create a histogram plot from 100,000 values between $$-\pi$$ and $$\pi$$, and sort the data into 25 bins.

theta = atan2(rand(100000,1)-0.5,2*(rand(100000,1)-0.5));
polarhistogram(theta,25);

Create Histogram in Polar Coordinates from Table

Since R2026a

Create a table with a variable named ThetaVals that has 14 angle values in radians. Create a histogram of the angle values.

ThetaVals = [0.1 1.1 5.4 3.4 2.3 4.5 3.2 3.4 5.6 2.3 2.1 3.5 0.6 6.1]';
tbl = table(ThetaVals);
polarhistogram(tbl,"ThetaVals")

Create a histogram of the same table variable with the data sorted into six bins.

polarhistogram(tbl,"ThetaVals",6)

Using the same table variable, create a histogram and specify the bin edges.

Edges = [0 0.5 1 1.5 2] * pi;
polarhistogram(tbl,"ThetaVals",Edges)

Plot Multiple Table Variables

Since R2026b

Create two vectors of angle values. Then assemble the vectors into a table.

theta1 = [0.1 1 0.5 1 1 1.4 0.2 0.5 1 1]';
theta2 = [3.5 5 3.2 4 4 6.1 6 4.5 2 3.3]';
tbl = table(theta1,theta2);

Plot both sets of angles by passing the table and the two table variable names to the polarhistogram function. Then add a legend.

polarhistogram(tbl,["theta1","theta2"])
legend

Modify Appearance of Histogram Chart

Create a histogram chart in polar coordinates, and then change its appearance. Specify the bar colors by setting the FaceColor property to a character vector of a color name, such as "red", or an RGB triplet. Specify the transparency by setting the FaceAlpha property to a value between 0 and 1.

theta = atan2(rand(100000,1)-0.5,2*(rand(100000,1)-0.5));
polarhistogram(theta,25,FaceColor="red",FaceAlpha=0.3);

Modify Appearance of Histogram Chart After Creation

Create a histogram chart in polar coordinates. Assign the histogram object to the variable h.

theta = atan2(rand(100000,1)-0.5,2*(rand(100000,1)-0.5));
h = polarhistogram(theta,25)

h = 
  Histogram with properties:

             Data: [100000×1 double]
           Values: [6232 7236 4699 2717 1908 1641 1622 1755 2207 3463 6471 6806 6429 6741 6380 3422 2233 1777 1570 1633 1899 2768 4755 7273 6363]
          NumBins: 25
         BinEdges: [-3.1416 -2.8903 -2.6389 -2.3876 -2.1363 -1.8850 -1.6336 -1.3823 -1.1310 -0.8796 -0.6283 -0.3770 -0.1257 0.1257 0.3770 0.6283 0.8796 1.1310 1.3823 1.6336 1.8850 2.1363 2.3876 2.6389 2.8903 3.1416]
         BinWidth: 0.2513
        BinLimits: [-3.1416 3.1416]
    Normalization: 'count'
        FaceColor: 'auto'
        EdgeColor: [0.1294 0.1294 0.1294]

  Show all properties

Use h to access and modify properties of the histogram object after it is created. For example, show just the histogram outline by setting the DisplayStyle property of the histogram object.

h.DisplayStyle = 'stairs';

Input Arguments

theta — Data to distribute among bins

vector | matrix

Data to distribute among bins, specified as a vector or a matrix. polarhistogram creates one histogram, regardless of whether you specify a vector or a matrix. Specify the values in radians. To convert degrees to radians, use deg2rad.

Values that correspond to the same angle direction differ by exactly 2π, and are sorted into the same bin. polarhistogram does not include NaN, Inf, and -Inf values in any bin.

Example: theta = [0 0.4 0.5 0.7 2.3 3.0 1.7 0.3];

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

nbins — Number of bins

positive integer

Number of bins, specified as a positive integer. If you do not specify nbins, then polarhistogram automatically calculates how many bins to use based on the values in theta.

Example: polarhistogram([0 pi/2 pi/2 pi 3*pi/2 2*pi],3)

edges — Bin edges

vector

Bin edges, specified as a vector. The difference between the minimum and maximum edge values must be less than or equal to 2π.

Example: polarhistogram([0 pi/2 pi 3*pi/2 2*pi],[0 pi 2*pi])

Example: polarhistogram(BinEdges=[0 pi/3 pi 3*pi/2 2*pi],BinCounts=[5 3 4 6])

counts — Bin counts

vector

Bin counts, specified as a vector. Use this option if you perform the bin counts calculation separately and you do not want polarhistogram to do any data binning.

Example: polarhistogram(BinEdges=[0 pi/3 pi 3*pi/2 2*pi],BinCounts=[5 3 4 6])

tbl — Source table

table | timetable

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

datavar — Table variable containing data

table variable index | multiple table variable indices (since R2026b)

Table variable containing the data to distribute among the bins, specified as one or more table variable indices. The variable you specify can contain values of any numeric type. If you specify multiple indices, the corresponding variables must all have the same type.

To specify one or more table variable indices, use any of the following indexing schemes.

Indexing Scheme	Examples
Variable names: A string array, character vector, or cell array. A pattern object.	"A" or 'A' — A variable named A ["A","B"] or {'A','B'} — Two variables named A and B "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit
Variable indices: An index number that refers to the location of a variable in the table. A vector of numbers. 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 [2 3] — The second and third variables from the table [false false true] — The third variable
Variable type: A vartype subscript that selects variables of a specified type.	vartype("double") — All the variables containing double values

Example: polarhistogram(tbl,"Theta") plots a histogram from the table variable named Theta.

Example: polarhistogram(tbl,["Theta1" "Theta2"]) plots two histograms from the table variables named Theta1 and Theta2. (since R2026b)

pax — PolarAxes object

PolarAxes object

PolarAxes object. If you do not specify the polar axes, then polarhistogram uses the current axes. polarhistogram does not support plotting into Cartesian axes.

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.

Example: polarhistogram(theta,FaceAlpha=0.3) creates a histogram chart with semitransparent bars.

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

BinLimits — Bin limits

two-element vector

Bin limits, specified as a two-element vector of the form [bmin,bmax], where bmin is less than bmax.

This option plots a histogram using the input array values that fall between bmin and bmax inclusive. That is, theta(theta>=bmin & theta<=bmax).

Example: polarhistogram(theta,BinLimits=[-pi/2 pi/2]) plots a histogram using only the values in theta that are between -pi/2 and pi/2 inclusive.

BinWidth — Width across top of bins

scalar less than 2π

Width across the top of the bins, specified as a scalar less than 2π.

polarhistogram uses a maximum of 65,536 bins (or 2¹⁶). If the specified bin width requires more bins, then polarhistogram uses the maximum number of bins and adjust the bin width accordingly.

Example: polarhistogram(theta,BinWidth=pi) uses bins with a width of π.

Normalization — Type of normalization

"count" (default) | "probability" | "countdensity" | "pdf" | "cumcount" | "cdf"

Type of normalization, specified as one of the values in this table.

Value	Description
"count"	Default normalization scheme. The height of each bar is the number of observations in each bin. The sum of the bar heights is numel(theta).
"probability"	The height of each bar is the relative number of observations. Each height is calculated as (number of observations in bin/total number of observations). The sum of the bar heights is 1.
"countdensity"	The height of each bar is the number of observations in bin/width of bin.
"pdf"	Probability density function estimate. The height of each bar is (number of observations in the bin)/(total number of observations * width of bin). The area of each bar is the relative number of observations. The sum of the bar areas is 1.
"cumcount"	The height of each bar is the cumulative number of observations in each bin and all previous bins. The height of the last bar is numel(theta).
"cdf"	Cumulative distribution function estimate. The height of each bar is equal to the cumulative relative number of observations in the bin and all previous bins. The height of the last bar is 1.

Example: polarhistogram(theta,Normalization="pdf") plots an estimate of the probability density function for theta.

DisplayStyle — Histogram display style

"bar" (default) | "stairs"

Histogram display style, specified as one of these values:

• "stairs" — Display the histogram outline only.

• "bar" — Show each individual bar with a filled interior.

Example: polarhistogram(theta,DisplayStyle="stairs") plots the outline of the histogram.

FaceAlpha — Transparency of histogram bars

0.6 (default) | scalar value between 0 and 1 inclusive

Transparency of histogram bars, specified as a scalar value between 0 and 1 inclusive. polarhistogram uses the same transparency for all the bars of the histogram. A value of 1 means fully opaque and 0 means completely transparent (invisible).

Example: polarhistogram(theta,FaceAlpha=0.5) creates a histogram plot with semi-transparent bars.

FaceColor — Histogram bar color

"auto" (default) | color name or short name | RGB triplet | hexadecimal color code

Histogram bar color, specified as one of these values:

• "auto" — MATLAB^® selects a color based on the ColorOrder property of the axes.

• Color name (or short name) — Specify any of these values: "red" (or "r"), "green" (or "g"), "blue" (or "b"), "cyan" (or "c"), "magenta" (or "m"), "yellow" (or "y"), "black" (or "k"), or "white" (or "w").

• RGB triplet — Specify the red, green, and blue components of a color as decimal values. 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].

• Hexadecimal color code — Specify the red, green, and blue components of a color as hexadecimal values. 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. The color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

This table shows the default color palettes for plots in the light and dark themes. 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 R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

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

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

Note

If you specify DisplayStyle as "stairs", then polarhistogram does not use the FaceColor property.

Example: polarhistogram(theta,FaceColor="g") creates a histogram plot with green bars.

Limitations

• polarhistogram does not support creating histograms of categorical data in polar axes.

Version History

Introduced in R2016b

R2026b: Plot multiple table variables simultaneously

Create polar histograms from multiple table variables simultaneously by passing a table to the polarhistogram function followed by the variables you want to plot. For an example, see Plot Multiple Table Variables.

R2026a: Pass tables directly to polarhistogram

Create histograms by passing a table to the polarhistogram function followed by the variable you want to plot.