compassplot

Polar plot with arrows emanating from origin

Since R2024b

collapse all in page
  • Polar plot with arrows emanating from the center

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

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.

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.

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.

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.

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.

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

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

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

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

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

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 SchemeExamples

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)

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

collapse all

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.

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

"none"Not applicableNot applicableNot applicableNo color

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

PalettePalette Colors

"gem" — Light theme default

Before R2025a: Most plots use these colors by default.

Sample of the "gem" color palette

"glow" — Dark theme default

Sample of the "glow" color palette

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

Style of arrow stems, specified as one of the line styles listed 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

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

See Also

Properties