# psrose

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

## Synopsis

**gmt psrose** [ *table* ] [ **-A***sector_width*[**+r**] ]
[ **-B**[**p**|**s**]*parameters* ]
[ **-C****m**|[**+w**]*mode_file* ]
[ **-D** ]
[ **-F** ]
[ **-G***fill* ] [ **-I** ]
[ **-J****X***diameter* ]
[ **-K** ]
[ **-L**[*wlabel*,*elabel*,*slabel*,*nlabel*] ]
[ **-M***parameters* ]
[ **-N***mode*[**+p***pen*] ]
[ **-O** ] [ **-P** ]
[ **-Q***alpha* ]
[ **-R***r0*/*r1*/*az0*/*az1* ]
[ **-S**[**+a**] ]
[ **-T** ]
[ **-U**[*stamp*] ]
[ **-V**[*level*] ]
[ **-W**[**v**]*pen* ]
[ **-X**[**a**|**c**|**f**|**r**][*xshift*] ]
[ **-Y**[**a**|**c**|**f**|**r**][*yshift*] ]
[ **-Z****u**|*scale* ]
[ **-bi**binary ]
[ **-di**nodata[**+c***col*] ]
[ **-e**regexp ]
[ **-h**headers ]
[ **-i**flags ]
[ **-o**flags ]
[ **-p**flags ]
[ **-qi**flags ]
[ **-t**transp ]
[ **-:**[**i**|**o**] ]
[ **--PAR**=*value* ]

## Description

**rose** reads (length, azimuth) pairs from *file* [or standard input]
and 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
outline of the windrose is drawn with the same color as MAP_DEFAULT_PEN.

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

## Optional Arguments

**-A***sector_width*[**+r**]Gives the sector width in degrees for sector and rose diagram. [Default 0 means windrose diagram]. Append

**+r**to draw rose diagram instead of sector diagram.

**-B**[**p**|**s**]*parameters*Set map boundary frame and axes attributes. (See full description) (See cookbook information). Remember that “x” here is radial distance and “y” is azimuth. The y label may be used to plot a figure caption. The scale bar length is determined by the radial gridline spacing.

**-C***cpt*Give a CPT. The

*r*-value for each sector is used to look-up the sector color. Cannot be used with a rose diagram. If modern mode and no argument is given then we select the current CPT.

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

**-E****m**|[**+w**]*mode_file*Plot vectors showing the principal directions given in the

*mode_file*file. Alternatively, specify**-Em**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**.

**-F**Do

*not*draw the scale length bar [Default plots scale bar in lower right corner provided**-B**is used. We use MAP_TICK_PEN_PRIMARY to draw the scale and label it with FONT_ANNOT_PRIMARY].

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

**-I**Inquire. Computes statistics needed to specify a useful

**-R**. No plot is generated. The following statistics are written to standard output:*n*,*mean az*,*mean r*,*mean resultant length*,*max bin sum*,*scaled mean*, and*linear length sum*.**Note**: You may use**-o**to select a subset from this record.

**-JX***diameter*Sets the diameter of the rose diagram. Only this form of the projection machinery is supported for this module. If not given, then we default to a diameter of 7.5 cm.

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

**-E**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**-E**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.

**-N***mode*[**+p***pen*]Draw the equivalent circular normal distribution, i.e., the

*von Mises*distribution; optionally append desired pen via the**+p**modifier [0.25p,black]. The*mode*selects which central location and scale to use:0 = mean and standard deviation;

1 = median and L1 scale (1.4826 * median absolute deviation; MAD);

2 = LMS (least median of squares) mode and scale.

**Note**: At the present time, only*mode*== 0 is supported.

**-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*/*az0*/*az1*Specifies the ‘region’ of interest in (

*r*,*azimuth*) space. Here,*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**[**+a**]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. Optionally, further normalize rose plots for area via modifier**+a**(i.e., take \(sqrt(r)\) before plotting [Default is no normalizations].

**-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**[*label*|**+c**][**+j***justify*][**+o***dx*[/*dy*]][**+t***text*]Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

**-V**[*level*]Select verbosity level [

**w**]. (See full description) (See cookbook information).

**-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**-E**) [Default is same as sector outline].

**-X**[**a**|**c**|**f**|**r**][*xshift*]Shift plot origin. (See full description) (See cookbook information).

**-Y**[**a**|**c**|**f**|**r**][*yshift*]Shift plot origin. (See full description) (See cookbook information).

**-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***record*[**+b**|**l**] (more …)Select native binary format for primary table input. [Default is 2 input columns].

**-di***nodata*[**+c***col*] (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**][**+m***segheader*][**+r***remark*][**+t***title*] (more …)Skip or produce header record(s).

**-i***cols*[**+l**][**+d***divisor*][**+s***scale*|**d**|**k**][**+o***offset*][,*…*][,**t**[*word*]] (more …)Select input columns and transformations (0 is first column,

**t**is trailing text, append*word*to read one word only).

**-o***cols*[**+l**][**+d***divisor*][**+s***scale*|**d**|**k**][**+o***offset*][,*…*][,**t**[*word*]] (more …)Select output columns and transformations (0 is first column,

**t**is trailing text, append*word*to write one word only).

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

**-qi**[~]*rows*|*limits*[**+c***col*][**+a**|**t**|**s**] (more …)Select input rows or data limit(s) [default is all rows].

**-s**[*cols*][**+a**][**+r**] (more …)Set handling of NaN records for output.

**-t***transp*[/*transp2*] (more …)Set transparency level(s) in percent.

**-wy**|**a**|**w**|**d**|**h**|**m**|**s**|**c***period*[/*phase*][**+c***col*] (more …)Convert an input coordinate to a cyclical coordinate.

**-^**or just**-**Print a short message about the syntax of the command, then exit (

**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 exit.

**-?**or no argumentsPrint a complete usage (help) message, including the explanation of all options, then exit.

**--PAR**=*value*Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

## Vector Attributes

Several modifiers may be appended to vector-producing options for
specifying 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 beginning point (**b**) to the
end point (**e**) of a line segment:

+a- Appendargumentto set the angle \(\theta\) of the vector head apex [30].

+b- Place a vector head at thebeginning of the vector path [none]. Optionally, appendtfor a terminal line,cfor a circle,sfor a square,afor arrow [Default],ifor tail,Afor plain open arrow, andIfor plain open tail.Note: For geovectors onlyaandAare available. Further appendl|rto only draw the left or right half-sides of this head [both sides].

+c- Select the vector data quantitymagnitudefor use with CPT color look-up [Default requires a separate data column following the 2 or 3 coordinates]. Requires that data quantity scaling (with unitqvia+vor+z) and a CPT have been selected.

+e- Place a vector head at theend of the vector path [none]. Optionally, appendtfor a terminal line,cfor a circle,sfor a square,afor arrow [Default],ifor tail,Afor plain open arrow, andIfor plain open tail.Note: For geovectors onlyaandAare available. Further appendl|rto only draw the left or right half-sides of this head [both sides].

+g- Append [fill] sets the vector head fill [Default fill is used, which may be no fill]. Turn off vector head fill by not appending afill. Some modules have a separate-Gfilloption and if used will select the fill as well.

+hAppendshapeof the vector head (range -2/2). Default is controlled by MAP_VECTOR_SHAPE [default is theme dependent]. A zero value produces no notch. Positive values moves the notch toward the head apex while a negative value moves it away. The example above uses+h0.5.

+m- Places a vector head at the mid-point the vector path [none]. Appendforrfor forward or reverse direction of the vector [forward]. Optionally, appendtfor a terminal line,cfor a circle,afor arrow [Default],ifor tail,Afor plain open arrow, andIfor plain open tail. Further appendl|rto only draw the left or right half-sides of this head [both sides]. Cannot be combined with+bor+e.

+n- Give [norm[/min]] to scale down vector attributes (pen thickness, head size) with decreasing length, where vector plot lengths shorter thannormwill have their attributes scaled by length/norm[other arrow attributes remain invariant to length]. Optionally, append /minfor the minimum shrink factor (in the 0-1 range) that we will shrink to [0.25]. For Cartesian vectors, please specify anormin plot units, while for geovectors specify anormin map units (see Distance units) [k]. Alternatively, append unitqto indicate we should use user quantity units in making the decision; this means the user also must select user quantity input via+vor+z. If no argument is given then+nensures vector heads are not shrunk and always plotted regardless of vector length [Vector heads are not plotted if exceeding vector length].

+o- Specify the oblique pole [plon/plat] for the great or small circles. Only needed for great circles if+qis given. If no pole is appended then we default to the north pole. Input arguments are thenlon lat arclengthwith the latter in map distance units; see+qof angular limits instead.

+p- Sets the vector pen attributes [pen]. If nopenis appended then the head outline is not drawn. [Default pen is half the width of stem pen, and head outline is drawn]. Above, we used+p2p,orange. The vector stem attributes are controlled by-W.

+q- Means the inputdirection,lengthdata instead represent thestartandstopopening angles of the arc segment relative to the given point. See+oto specify a specific pole for the arc [north pole].

+t[b|e]trim- Shift the beginning or end point (or both) along the vector segment by the giventrim; append suitable unit (c,i, orp). If the modifiersb|eare not used thentrimmay be two values separated by a slash, which is used to specify different trims for the beginning and end. 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- Thejustdetermines how the inputx,ypoint relates to the vector. Choose frombeginning [default],end, orcenter.

+s- The inputangle,lengthare instead the \(x_e, y_e\) coordinates of the vector end point.

Finally, Cartesian vectors and geovectors may take these modifiers (except in grdvector) which can be used to convert vector components to polar form or magnify user quantity magnitudes into plot lengths:

+v[i|l]scale- Expects ascaleto magnify the polar length in the given unit. Ifiis prepended we use the inverse scale while iflis prepended then it is taken as a fixed length to override input lengths. Append unitqif input magnitudes are given in user quantity units and we will scale them to current plot unit for Cartesian vectors (see PROJ_LENGTH_UNIT for how to change the plot unit) or to km for geovectors. In addition, if+cis selected then the vector magnitudes may be used for CPT color-lookup (and no extra data column is required by-C).

+z[scale] - Expects input \(\Delta x, \Delta y\) vector components and uses thescale[1] to convert to polar coordinates with length in given unit. Append unitqif input components are given in user quantity units and we will scale to current plot unit for Cartesian vectors (see PROJ_LENGTH_UNIT for how to change the plot unit) or to km for geovectors. In addition, if+cis selected then the vector magnitudes may be used for CPT color-lookup (and no extra data column is required by-C).

**Note**: Vectors were completely redesigned for GMT5 which separated the vector head (a polygon)
from the vector stem (a line). In GMT4, the entire vector was a polygon and it could only
be a straight Cartesian vector. Yes, the old GMT4 vector shape remains accessible if
you specify a vector (**-Sv**|**V**) using the GMT4 syntax, explained here: *size*, if present, will
be interpreted as \(t_w/h_l/h_w\) or *tailwidth/headlength/halfheadwidth* [Default is 0.075c/0.3c/0.25c (or
0.03i/0.12i/0.1i)]. By default, arrow attributes remain invariant to the length of the
arrow. To have the size of the vector scale down with decreasing size, append **+n***norm*,
where vectors shorter than *norm* will have their attributes scaled by *length*/*norm*.
To center the vector on the balance point, use **-Svb**; to align point with the vector head,
use **-Svh**; to align point with the vector tail, use **-Svt** [Default]. To give the
head point’s coordinates instead of direction and length, use **-Svs**. Upper case
**B**, **H**, **T**, **S** will draw a double-headed vector [Default is single head].
**Note**: If \(h_l/h_w\) are given as 0/0 then only the head-less vector stick will be plotted.

## Classic Mode Arguments

These options are used to manipulate the building of layered GMT PostScript plots in classic mode. They are not available when using GMT modern mode.

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

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

**-P**(more …)Select “Portrait” plot orientation.

## Examples

**Note**: Below are some examples of valid syntax for this module.
The examples that use remote files (file names starting with `@`

)
can be cut and pasted into your terminal for testing.
Other commands requiring input files are just dummy examples of the types
of uses that are common but cannot be run verbatim as written.

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 diameter = 6 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" -JX6i -A10+r -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 diameter = 10 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 -JX10c -Bxg100 -Byg45 -B+t"Windrose diagram" -W0.5p -U+c | 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 -JX10c -Bxg100 -Byg45 -B+t"Windrose diagram" -M0.5c+e+gorange+n1c -W0.5p -U+c > rose.ps

## Bugs

No default radial scale and grid settings for polar histograms. Users
must run the module with **-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.