compassplot

Polar plot with arrows emanating from origin

Since R2024b

collapse all in page

Syntax

compassplot(theta,rho)

compassplot(Z)

compassplot(tbl,thetavar,rhovar)

compassplot(pax,___)

compassplot(___,Name=Value)

cp = compassplot(___)

Description

Vector and Matrix Data

compassplot(theta,rho) plots arrows (vectors) originating at the origin in polar coordinates. The theta values control the arrow directions in radians. The rho values control the arrow magnitudes as radius values.

To plot one set of arrows, specify theta and rho as vectors of equal length.
To plot multiple sets of arrows, specify theta or rho as a matrix, or both as matrices of the same size.

example

compassplot(Z) plots the complex numbers in Z. Specify Z as a vector or matrix containing values of the form a+bi.

example

Table Data

compassplot(tbl,thetavar,rhovar) plots the variables thetavar and rhovar from the table tbl. To plot one set of arrows, specify one variable each for thetavar and rhovar. To plot multiple sets of arrows, specify multiple variables for thetavar, rhovar, or both.

example

Additional Options

compassplot(pax,___) displays the compass plot in the target polar axes pax. Specify the polar axes as the first argument in any of the previous syntaxes.

example

compassplot(___,Name=Value) specifies PolarCompassPlot properties using one or more name-value arguments. Specify the name-value arguments after all other input arguments. For a list of properties, see PolarCompassPlot Properties.

example

cp = compassplot(___) returns the PolarCompassPlot object. Use cp to get and set properties of the plot after creating it. For a list of properties, see PolarCompassPlot Properties.

example

Examples

collapse all

Plot One Set of Arrows with Radian Tick Labels

Open Live Script

Create the vectors theta and rho, and plot their values in a compass plot.

rho = [1 3 2 2];
theta = [0 pi/4 3*pi/4 5*pi/4];
compassplot(theta,rho)

Figure contains an axes object with type polaraxes. The polaraxes object contains an object of type compassplot.

Change the display of the theta-axis tick labels to show radian values by getting the polar axes and setting the ThetaAxisUnits property to "radians".

pax = gca;
pax.ThetaAxisUnits = "radians";

Figure contains an axes object with type polaraxes. The polaraxes object contains an object of type compassplot.

Plot Multiple Sets of Arrows

Open Live Script

To plot multiple sets of arrows, specify at least one set of coordinates as a matrix. Alternatively, you can call the hold function between plotting commands.

Create a 4-by-2 matrix of wind direction values and a 4-by-2 matrix of wind speed values. The first column in each matrix corresponds to the morning data, and the second column corresponds to the evening data. Plot the data as a compass plot with a legend.

windDirection = deg2rad([0.5 185; 30 200; 45 230; 75 250]);
windSpeed = [20 15; 15 30; 12 25; 20 45];
compassplot(windDirection,windSpeed)
legend(["Morning Winds" "Evening Winds"])

Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type compassplot. These objects represent Morning Winds, Evening Winds.

Alternatively, you can plot one set of arrows at a time and call the hold function between plotting commands.

% Create figure and data
figure
morningDirection = deg2rad([0.5 30 45 75]);
eveningDirection = deg2rad([185 200 230 250]);
morningSpeed = [20 15 12 20];
eveningSpeed = [15 30 25 45];

% Plot morning and evening data separately
compassplot(morningDirection,morningSpeed)
hold on
compassplot(eveningDirection,eveningSpeed)
hold off
legend(["Morning Winds" "Evening Winds"])

Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type compassplot. These objects represent Morning Winds, Evening Winds.

Plot Complex Values

Open Live Script

To plot complex values, specify a vector or matrix of complex numbers. For example, create matrices a and b that contain numbers between –2 and 2. Create a matrix Z of complex numbers of the form a+bi and plot them. compassplot plots each column of Z separately with a different color.

[a,b] = meshgrid(-2:2);
Z = a + b*1i;
compassplot(Z)

Figure contains an axes object with type polaraxes. The polaraxes object contains 5 objects of type compassplot.

Modify Arrow Appearance

Open Live Script

You can modify aspects of the plot by setting properties. You can set properties by specifying name-value arguments when you call compassplot, or you can set properties later using dot notation.

For example, plot seven values, and specify the line thickness by setting the LineWidth name-value argument. Also, specify an output argument to store the PolarCompassPlot object.

theta = 0:pi/6:pi;
rho = [1 0.8 0.7 0.7 0.7 0.8 1];
cp = compassplot(theta,rho,LineWidth=1.5);

Figure contains an axes object with type polaraxes. The polaraxes object contains an object of type compassplot.

Modify the appearance further by setting properties of the PolarCompassPlot object cp. Change the line color to magenta, and change the line style to a dashed line.

cp.Color = "magenta";
cp.LineStyle = "--";

Figure contains an axes object with type polaraxes. The polaraxes object contains an object of type compassplot.

Plot Data from Table

Open Live Script

Create a table containing two variables, theta and rho.

theta = [0 pi/4 pi/2]';
rho = [1 3 2]';
t = table(theta,rho);

Create a compass plot from the table.

compassplot(t,"theta","rho")

Figure contains an axes object with type polaraxes. The polaraxes object contains an object of type compassplot.

Specify Axes for Compass Plot

Open Live Script

To plot into a specific polar axes object, specify the polar axes as the first argument when you call compassplot. For example, create a polar axes object and plot into it. This strategy is useful in these situations:

You do not want compassplot to create a new polar axes object.
You want to preserve the contents of an existing axes object.
You are creating the plot in an app.

pax = polaraxes;
theta = [0 pi/4 pi/2];
rho = [1 2 3];
compassplot(pax,theta,rho)

Figure contains an axes object with type polaraxes. The polaraxes object contains an object of type compassplot.

Input Arguments

collapse all

`theta,rho` — theta and rho values
pair of scalars | pair of vectors | vector and matrix | pair of matrices

theta and rho values, specified as a pair of scalars, a pair of vectors, a vector and a matrix, or a pair of matrices. Specify the theta values in radians. The size and shape of theta and rho depend on the shape of your data. This table describes the most common situations.

Type of Plot How to Specify Coordinates

Single arrow

Type of Plot	How to Specify Coordinates
Single arrow	Specify `theta` and `rho` as scalars. For example: compassplot(pi/2,1)
One set of arrows	Specify `theta` and `rho` as any combination of row or column vectors of the same length. For example: theta = [0 pi/4 pi/2]; rho = [1; 2; 3]; compassplot(theta,rho)
Multiple sets of arrows that are different colors	If all the data sets share the same `theta` or `rho` values, specify the shared coordinates as a vector and the other coordinates as a matrix. The length of the vector must match one of the dimensions of the matrix. (If you specify a square matrix, `compassplot` plots at set of arrows for each column of the matrix.) For example, plot two sets of three arrows that have the same `theta` values. theta = [0 pi/4 pi/2]; rho = [4 5 6; 7 8 9]; compassplot(theta,rho) Alternatively, specify `theta` and `rho` as matrices of equal size. `compassplot` plots sets of arrows using the columns in the matrices. For example, plot three sets of two arrows. theta = [0 pi/6 pi/2; pi/8 pi/4 pi]; rho = [1 2 3; 4 5 6]; compassplot(theta,rho)

Specify theta and rho as scalars. For example:

compassplot(pi/2,1)

One set of arrows

Specify theta and rho as any combination of row or column vectors of the same length. For example:

theta = [0 pi/4 pi/2];
rho = [1; 2; 3];
compassplot(theta,rho)

Multiple sets of arrows that are different colors

If all the data sets share the same theta or rho values, specify the shared coordinates as a vector and the other coordinates as a matrix. The length of the vector must match one of the dimensions of the matrix. (If you specify a square matrix, compassplot plots at set of arrows for each column of the matrix.)

For example, plot two sets of three arrows that have the same theta values.

theta = [0 pi/4 pi/2];
rho = [4 5 6; 7 8 9];
compassplot(theta,rho)

Alternatively, specify theta and rho as matrices of equal size. compassplot plots sets of arrows using the columns in the matrices. For example, plot three sets of two arrows.

theta = [0 pi/6 pi/2; pi/8 pi/4 pi];
rho = [1 2 3; 4 5 6];
compassplot(theta,rho)

`Z` — Complex values
scalar | vector | matrix

Complex values, specified as a scalar, vector, or matrix of values of the form a+bi. MATLAB^® converts Z to polar form using theta = angle(Z) and rho = abs(Z).

The size and shape of Z depend on the shape of your data. This table describes the most common situations.

Type of Plot How to Specify Coordinates

Single arrow

Type of Plot	How to Specify Coordinates
Single arrow	Specify `Z` as scalar complex value. For example: Z = 0+1i; compassplot(Z)
One set of arrows	Specify `Z` as a vector of complex values. For example: Z = [0+1i 1+2i 1+3i]; compassplot(Z)
Multiple sets of arrows that are different colors	Specify `Z` as a matrix of complex values. `compassplot` plots a separate set of arrows for each column in the matrix. For example, plot three sets of two arrows: Z = [0+1i 1+2i 1+3i; 0-1i 1-2i 1-3i]; compassplot(Z)

Specify Z as scalar complex value. For example:

Z = 0+1i; 
compassplot(Z)

One set of arrows

Specify Z as a vector of complex values. For example:

Z = [0+1i 1+2i 1+3i];
compassplot(Z)

Multiple sets of arrows that are different colors

Specify Z as a matrix of complex values. compassplot plots a separate set of arrows for each column in the matrix. For example, plot three sets of two arrows:

Z = [0+1i 1+2i 1+3i; 0-1i 1-2i 1-3i];
compassplot(Z)

`tbl` — Source table
table | timetable

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

`thetavar,rhovar` — Table variables containing theta and rho values
pair of table variable indices

Table variables containing the theta and rho values, specified as a pair of table variable indices.

Specifying Table Indices

For each variable you specify, you can use any of these indexing schemes.

Indexing Scheme Examples

Indexing Scheme	Examples
Variable names: A string, 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 index: 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("categorical")` — All the variables containing categorical values

Variable names:

A string, 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 index:

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("categorical") — All the variables containing categorical values

Plotting Your Data

The table variables you specify can contain any numeric data type.

To plot one data set, specify one variable each for thetavar and rhovar. For example, create a table with four variables. Plot the theta1 and rho1 variables.

% Create a table of theta and rho values
theta1 = [0 pi/4 pi/2 3*pi/4]';
theta2 = theta1 + pi;
rho1 =  [1 2 3 4]';
rho2 = [5 6 7 8]';
tbl = table(theta1,theta2,rho1,rho2);

% Create compass plot
compassplot(tbl,"theta1","rho1")

To plot multiple data sets together, specify multiple variables for thetavar, rhovar, or both. If you specify multiple variables for both thetavar and rhovar, the number of variables must be the same. For example, create a compass plot by specifying two variables each for thetavar and rhovar.

compassplot(tbl,["theta1" "theta2"],["rho1" "rho2"])

You can also use different indexing schemes for the table variables. For example, specify thetavar as a variable name and rhovar as an index number.

compassplot(tbl,"theta1",3)

`pax` — Target axes
`PolarAxes` object

Target axes, specified as a PolarAxes object. If you do not specify the axes, compassplot plots into the current axes, or it creates a PolarAxes object if one does not exist.

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: compassplot([0 pi/4 pi/2],[1 2 3],LineWidth=1.5) creates a compass plot using a line width of 1.5 points.

Note

The properties listed here are only a subset. For a full list, see PolarCompassPlot Properties.

`Color` — Arrow color
RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

Arrow color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

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 string scalar or character vector 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. Therefore, 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"`
`"none"`	Not applicable	Not applicable	Not applicable	No color

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

`LineStyle` — Style of arrow stems
`"-"` (default) | `"--"` | `":"` | `"-."` | `"none"`

Style of arrow stems, specified as one of the line styles listed in this table.

Line Style	Description	Resulting Line
`"-"`	Solid line
`"--"`	Dashed line
`":"`	Dotted line
`"-."`	Dash-dotted line
`"none"`	No line	No line

`LineWidth` — Width of arrow lines
`0.5` (default) | positive value

Width of arrow lines, specified as a positive value in point units. One point equals 1/72 inch. The default value is 0.5 point.

Version History

Introduced in R2024b

compassplot

Syntax

Description

Vector and Matrix Data

Table Data

Additional Options

Examples

Plot One Set of Arrows with Radian Tick Labels

Plot Multiple Sets of Arrows

Plot Complex Values

Modify Arrow Appearance

Plot Data from Table

Specify Axes for Compass Plot

Input Arguments

theta,rho — theta and rho values pair of scalars | pair of vectors | vector and matrix | pair of matrices

Z — Complex values scalar | vector | matrix

tbl — Source table table | timetable

thetavar,rhovar — Table variables containing theta and rho values pair of table variable indices

Specifying Table Indices

Plotting Your Data

pax — Target axes PolarAxes object

Name-Value Arguments

Color — Arrow color RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

LineStyle — Style of arrow stems "-" (default) | "--" | ":" | "-." | "none"

LineWidth — Width of arrow lines 0.5 (default) | positive value

Version History

See Also

Properties

`theta,rho` — theta and rho values
pair of scalars | pair of vectors | vector and matrix | pair of matrices

`Z` — Complex values
scalar | vector | matrix

`tbl` — Source table
table | timetable

`thetavar,rhovar` — Table variables containing theta and rho values
pair of table variable indices

`pax` — Target axes
`PolarAxes` object

`Color` — Arrow color
RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

`LineStyle` — Style of arrow stems
`"-"` (default) | `"--"` | `":"` | `"-."` | `"none"`

`LineWidth` — Width of arrow lines
`0.5` (default) | positive value