rose

(Not recommended) Angle histogram

rose is not recommended. Use polarhistogram instead. For information on updating your code, see Version History.

Syntax

rose(theta)

rose(theta,x)

rose(theta,nbins)

rose(ax,___)

ln = rose(___)

[t,r] = rose(___)

Description

rose(theta) creates an angle histogram, which is a polar plot that shows the distribution of angles in theta.

rose(theta,x) uses the number of bins and the bin locations specified by vector x. The values in x specify the center angle of each bin, and length(x) is the number of bins.

rose(theta,nbins) plots the specified number of equally spaced bins in the range [0,2*pi].

rose(ax,___) plots into the specified axes instead of the current axes (gca).

ln = rose(___) returns the Line object used to create the angle histogram. Use ln to modify the histogram after it is created. For a list of properties, see Line Properties.

[t,r] = rose(___) returns the angle and radius values of the bins that can be used in polarplot(t,r) to generate the histogram. This syntax does not generate a plot.

Examples

Create Angle Histogram

Create an angle histogram of values between 0 and $$2\pi$$. Distribute the data among 10 bins.

theta = [0.4 1.4 3.1 2.3 0.4 2.5 3.9 2.8 2.3 1.6 4.6 4.5 6.1 3.9 5.1];
rose(theta,10)

Input Arguments

theta — Data to distribute among bins

vector

Data to distribute among bins, specified as a vector of angles expressed in radians. If you do not specify nbins, then rose distributes the data among 20 bins or fewer. The length of each bin corresponds to the number of elements in theta that fall within the start and end angles of that bin, from 0 to the greatest number of elements deposited in any one bin.

x — Bin centers

vector

Bin centers, specified as a vector of angles expressed in radians. For example, if x is a five-element vector, rose distributes the elements of theta among five bins centered at the specified values in x.

nbins — Number of bins

positive integer

Number of bins, specified as a positive integer. rose plots nbins equally spaced bins in the range [0,2*pi]. If you do not specify nbins, then rose distributes the data among 20 bins or fewer.

ax — Target axes

Axes object

Target axes, specified as an Axes object. If you do not specify the axes, MATLAB^® plots into the current axes or it creates an Axes object if one does not exist. rose does not support plotting into PolarAxes objects.

Output Arguments

ln — Angle histogram

Line object

Angle histogram, returned as a Line object. Use this output to modify the appearance of the angle histogram. For more information about the properties you can set for these objects, see Line Properties.

t — Angle values of bins

vector

Angle values of bins, returned as a vector. Use t with r to generate an angle histogram in a PolarAxes object by passing them as inputs to the polarplot function. Each bin in the histogram is represented by four distinct points. The length of t is 4 times the number of bins.

r — Radius values of bins

vector

Radius values of bins, returned as a vector. Use r with t to generate an angle histogram in a PolarAxes object by passing them as inputs to the polarplot function. Each bin in the histogram is represented by four distinct points. The length of r is 4 times the number of bins.

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The rose function supports GPU array input with these usage notes and limitations:

• This function accepts GPU arrays, but does not run on a GPU.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• This function operates on distributed arrays, but executes in the client MATLAB.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2016b: Not recommended

rose is not recommended. Use polarhistogram instead. There are no plans to remove rose.

The polarhistogram function uses graphics objects that are designed for polar coordinate and histogram data. These objects have more relevant customization options than the objects used by rose. The benefits of using polarhistogram over rose include:

• polarhistogram plots into a PolarAxes object instead of an Axes object. For example, you can change the location of 0 by setting the ThetaZeroLocation property of the PolarAxes object.

• polarhistogram creates a Histogram object instead of a Line object. For example, you can color the bins by setting the FaceColor property of the Histogram object.

This table shows some typical uses of rose and how to update your code to use polarhistogram instead.

Objective	Not Recommended	Recommended	Differences
Specify the number of bins.	rose(theta,nbins)	polarhistogram(theta,nbins)	No difference.
Specify the locations of bins.	rose(theta,x)	polarhistogram(theta,edges)	For rose, x specifies the center angle of each bin. length(x) is the total number of bins. For polarhistogram, edges specifies the start and end values of each bin. length(edges)-1 is the total number of bins.
Specify the target axes.	rose(ax,__)	polarhistogram(pax,__)	rose accepts an Axes target axes. polarhistogram accepts a PolarAxes target axes.
Specify a PolarAxes target axes.	[t,r] = rose(theta) polarplot(pax,t,r)	polarhistogram(pax,theta)	rose accepts an Axes target axes only. Use the polarplot function and specify pax, a PolarAxes object along with two output arguments from rose. polarhistogram accepts a PolarAxes target axes.
Modify the appearance of the angle histogram.	ln = rose(theta) Then, use dot notation with ln to change the graph appearance.	polarhistogram(theta,Name,Value) or h = polarhistogram(theta) Then, use dot notation with h to change the graph appearance.	For rose, ln is a Line object. Use dot notation to set any properties of the line. For a list of properties, see Line Properties. For polarhistogram, h is a Histogram object. Use dot notation or name-value arguments to set any properties of the histogram. For a list of properties, see Histogram Properties.