PSROSE(1gmt) | GMT | PSROSE(1gmt) |

# NAME¶

psrose - Plot a polar histogram (rose, sector, windrose diagrams)

# SYNOPSIS¶

**psrose** [ *table* ] [
**-A**[**r**]*sector_width* ] [
**-B**[**p**|**s**]*parameters* ] [
**-C****m**|[**+w**]*mode_file* ] [ **-D** ] [ **-F** ]
[ **-G***fill* ] [ **-I** ] [ **-K** ] [
**-L**[*wlabel*,*elabel*,*slabel*,*nlabel*] ] [
**-M***parameters* ] [ **-O** ] [ **-P** ] [
**-Q***alpha* ] [
**-R***r0*/*r1*/*az_0*/*az_1* ] [
**-S**[**n**]*radial_scale* ] [ **-T** ] [
**-U**[*stamp*] ] [ **-V**[*level*] ] [
**-W**[**v**]*pen* ] [ **-X***x_offset* ] [
**-Y***y_offset* ] [ **-Z****u**|*scale* ] [
**-bi**binary ] [ **-di**nodata ] [ **-e**regexp ] [
**-h**headers ] [ **-i**flags ] [ **-p**flags ] [ **-t**transp ]
[ **-:**[**i**|**o**] ]

**Note:** No space is allowed between the option flag and the
associated arguments.

# DESCRIPTION¶

**psrose** reads (length,azimuth) pairs from *file* [or
standard input] and generates PostScript code that will plot a windrose
diagram. Add **-i**0 if your file only has azimuth values. Optionally
(with **-A**), polar histograms may be drawn (sector diagram or rose
diagram). Options include full circle and half circle plots. The PostScript
code is written to standard output. The outline of the windrose is drawn
with the same color as **MAP_DEFAULT_PEN**.

# REQUIRED ARGUMENTS¶

None.

# OPTIONAL ARGUMENTS¶

*table*- One or more ASCII (or binary, see
**-bi**[*ncols*][*type*]) data table file(s) holding a number of data columns. If no tables are given then we read from standard input. If a file with only azimuths are given, use**-i**to indicate the single column with azimuths; then all lengths are set to unity (see**-Zu**to set actual lengths to unity as well).

**-A**[**r**]*sector_width*- Gives the sector width in degrees for sector and rose diagram. [Default 0
means windrose diagram]. Use
**-Ar**to draw rose diagram instead of sector diagram.

**-B**[**p**|**s**]*parameters*(more ...)- Set map boundary frame and axes attributes.

Remember that "x" here is radial distance and "y" is azimuth. The ylabel may be used to plot a figure caption. The scale bar length is determined by the radial gridline spacing.

**-C****m**|[**+w**]*mode_file*- Plot vectors showing the principal directions given in the
*mode_file*file. Alternatively, specify**-Cm**to compute and plot mean direction. See**-M**to control the vector attributes. Finally, to instead save the computed mean direction and other statistics, use [**m**]**+w***mode_file*. The eight items saved to a single record are:*mean_az, mean_r, mean_resultant, max_r, scaled_mean_r, length_sum, n, sign@alpha*, where the last term is 0 or 1 depending on whether the mean resultant is significant at the level of confidence set via**-Q**.

**-D**- Shift sectors so that they are centered on the bin interval (e.g., first sector is centered on 0 degrees).

**-F**- Do not draw the scale length bar [Default plots scale in lower right corner]

**-G***fill*- Selects shade, color or pattern for filling the sectors [Default is no fill]K.

**-I**- Inquire. Computes statistics needed to specify a useful
**-R**. No plot is generated. The following statistics are written to stdout:*n*,*mean az*,*mean r*,*mean resultant length*,*max bin sum*,*scaled mean*, and*linear length sum*.

**-K**(more ...)- Do not finalize the PostScript plot.

**-L**[*wlabel*,*elabel*,*slabel*,*nlabel*]- Specify labels for the 0, 90, 180, and 270 degree marks. For full-circle
plot the default is WEST,EAST,SOUTH,NORTH and for half-circle the default
is 90W,90E,-,0. A - in any entry disables that label. Use
**-L**with no argument to disable all four labels. Note that the GMT_LANGUAGE setting will affect the words used.

**-M***parameters*- Used with
**-C**to modify vector parameters. For vector heads, append vector head*size*[Default is 0, i.e., a line]. See VECTOR ATTRIBUTES for specifying additional attributes. If**-C**is not given and the current plot mode is to draw a windrose diagram then using**-M**will add vector heads to all individual directions using the supplied attributes.

**-O**(more ...)- Append to existing PostScript plot.

**-P**(more ...)- Select "Portrait" plot orientation.

**-Q***alpha*]- Sets the confidence level used to determine if the mean resultant is significant (i.e., Lord Rayleigh test for uniformity) [0.05]. Note: The critical values are approximated [Berens, 2009] and requires at least 10 points; the critical resultants are accurate to at least 3 significant digits. For smaller data sets you should consult exact statistical tables.

**-R***r0*/*r1*/*az_0*/*az_1*- Specifies the 'region' of interest in (r,azimuth) space. r0 is 0, r1 is max length in units. For azimuth, specify either -90/90 or 0/180 for half circle plot or 0/360 for full circle.

**-S**[**n**]*plot_radius*- Specifies radius of plotted circle (append a unit from
**c**|**i**|**p**). Use**-Sn**to normalize input radii (or bin counts if**-A**is used) by the largest value so all radii (or bin counts) range from 0 to 1.

**-T**- Specifies that the input data are orientation data (i.e., have a 180
degree ambiguity) instead of true 0-360 degree directions [Default]. We
compensate by counting each record twice: First as
*azimuth*and second as*azimuth + 180*. Ignored if range is given as -90/90 or 0/180.

**-U**[[*just*]/*dx*/*dy*/][**c**|*label*] (more ...)- Draw GMT time stamp logo on plot.

**-V**[*level*] (more ...)- Select verbosity level [c].

**-W***pen*- Set pen attributes for sector outline or rose plot. [Default is no
outline]. Use
**-Wv***pen*to change pen used to draw vector (requires**-C**) [Default is same as sector outline].

**-X**[**a**|**c**|**f**|**r**][*x-shift*[**u**]]

**-Y**[**a**|**c**|**f**|**r**][*y-shift*[**u**]] (more ...)- Shift plot origin.

**-Z****u**|*scale*- Multiply the data radii by
*scale*. E.g., use**-Z**0.001 to convert your data from m to km. To exclude the radii from consideration, set them all to unity with**-Zu**[Default is no scaling]. **-:**- Input file has (azimuth,radius) pairs rather than the expected (radius,azimuth).

**-bi**[*ncols*][**t**] (more ...)- Select native binary input. [Default is 2 input columns].

**-di***nodata*(more ...)- Replace input columns that equal
*nodata*with NaN.

**-e**[**~**]*"pattern"***|****-e**[**~**]/*regexp*/[**i**] (more ...)- Only accept data records that match the given pattern.

**-h**[**i**|**o**][*n*][**+c**][**+d**][**+r***remark*][**+r***title*] (more ...)- Skip or produce header record(s).

**-i***cols*[**+l**][**+s***scale*][**+o***offset*][,*...*] (more ...)- Select input columns and transformations (0 is first column).

**-p**[**x**|**y**|**z**]*azim*[/*elev*[/*zlevel*]][**+w***lon0*/*lat0*[/*z0*]][**+v***x0*/*y0*] (more ...)- Select perspective view.

**-t**[*transp*] (more ...)- Set PDF transparency level in percent.

**-^**or just**-**- Print a short message about the syntax of the command, then exits (NOTE:
on Windows just use
**-**). **-+**or just**+**- Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exits.
**-?**or no arguments- Print a complete usage (help) message, including the explanation of all options, then exits.

# VECTOR ATTRIBUTES¶

Several modifiers may be appended to the vector-producing options to specify the placement of vector heads, their shapes, and the justification of the vector. Below, left and right refers to the side of the vector line when viewed from the start point to the end point of the segment:

**+a**

*angle*sets the angle of the vector head apex [30].

**+b** places a vector head at the beginning of the vector path
[none]. Optionally, append **t** for a terminal line, **c** for a
circle, **a** for arrow [Default], **i** for tail, **A** for plain
arrow, and **I** for plain tail. Further append **l**|**r** to only
draw the left or right side of this head [both sides].

**+e** places a vector head at the end of the vector path
[none]. Optionally, append **t** for a terminal line, **c** for a
circle, **a** for arrow [Default], **i** for tail, **A** for plain
arrow, and **I** for plain tail. Further append **l**|**r** to only
draw the left or right side of this head [both sides].

**+g**-|*fill* turns off vector head fill (if -) or sets
the vector head fill [Default fill is used, which may be no fill].

**+h***shape* sets the shape of the vector head (range
-2/2). Default is controlled by MAP_VECTOR_SHAPE [0].

**+l** draws half-arrows, using only the left side of specified
heads [both sides].

**+m** places a vector head at the mid-point the vector path
[none]. Append **f** or **r** for forward or reverse direction of the
vector [forward]. Optionally, append **t** for a terminal line, **c**
for a circle, or **a** for arrow head [Default]. Further append
**l**|**r** to only draw the left or right side of this head [both
sides]. Cannot be combined with **+b** or **+e**.

**+n***norm* scales down vector attributes (pen thickness,
head size) with decreasing length, where vectors shorter than *norm*
will have their attributes scaled by length/*norm* [arrow attributes
remains invariant to length].

**+o***plon*/*plat* specifies the oblique pole for
the great or small circles. Only needed for great circles if **+q** is
given.

**+p**[-][*pen*] sets the vector pen attributes. If
*pen* has a leading - then the head outline is not drawn. [Default pen
is used, and head outline is drawn]

**+q** means the input *angle*, *length* data instead
represent the *start* and *stop* opening angles of the arc segment
relative to the given point.

**+r** draws half-arrows, using only the right side of
specified heads [both sides].

**+t**[**b**|**e**]*trim* will shift the beginning
or end point (or both) along the vector segment by the given *trim*;
append suitable unit. If the modifiers **b**|**e** are not used then
*trim* may be two values separated by a slash, which is used to specify
different trims for the two ends. Positive trims will shorted the vector
while negative trims will lengthen it [no trim].

In addition, all but circular vectors may take these modifiers:

**+j**

*just*determines how the input

*x*,

*y*point relates to the vector. Choose from

**b**eginning [default],

**e**nd, or

**c**enter.

**+s** means the input *angle*, *length* are instead
the *x*, *y* coordinates of the vector end point.

Finally, Cartesian vectors may take these modifiers:

**+z**

*scale*[

*unit*] expects input

*dx*,

*dy*vector components and uses the

*scale*to convert to polar coordinates with length in given unit.

# EXAMPLES¶

To plot a half circle rose diagram of the data in the file fault_segments.az_r (containing pairs of (azimuth, length in meters), using a 10 degree bin sector width, on a circle of radius = 3 inch, grid going out to radius = 150 km in steps of 25 km with a 30 degree sector interval, radial direction annotated every 50 km, using a light blue shading outlined by a solid red pen (width = 0.75 points), draw the mean azimuth, and shown in Portrait orientation, use:

gmt psrose fault_segments.az_r -R0/150/-90/90 -Bx50g25+l"Fault length"

-Byg30 -B+t"Rose diagram"-S3i -Ar10 -Glightblue

-W0.75p,red -Z0.001 -Cm -P -T -: > half_rose.ps

To plot a full circle wind rose diagram of the data in the file lines.r_az, on a circle of radius = 5 cm, grid going out to radius = 500 units in steps of 100 with a 45 degree sector interval, using a solid pen (width = 0.5 point, and shown in landscape [Default] orientation with UNIX timestamp and command line plotted, use:

gmt psrose lines.az_r -R0/500/0/360 -S5c -Bxg100 -Byg45 -B+t"Windrose diagram" -W0.5p -Uc | lpr

Redo the same plot but this time add orange vector heads to each direction (with nominal head size 0.5 cm but this will be reduced linearly for lengths less than 1 cm) and save the plot, use:

gmt psrose lines.az_r -R0/500/0/360 -S5c -Bxg100 -Byg45 -B+t"Windrose diagram" -M0.5c+e+gorange+n1c -W0.5p -Uc > rose.ps

# BUGS¶

No default radial scale and grid settings for polar histograms.
User must run **psrose** **-I** to find max length in binned data
set.

# REFERENCES¶

Berens, P., 2009, CircStat: A MATLAB Toolbox for Circular
Statistics, *J. Stat. Software, 31(10)*, 1-21.

# SEE ALSO¶

gmt, gmt.conf, gmtcolors, pshistogram

# COPYRIGHT¶

2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe

May 10, 2017 | 5.4.1 |