.TH PSROSE 1gmt "15 Jul 2011" "GMT 4.5.7" "Generic Mapping Tools"
.SH NAME
psrose \- Plot (length, azimuth) as windrose diagram or polar histogram (sector or rose diagram).
.SH SYNOPSIS
\fBpsrose\fP \fIfile\fP [ \fB\-A\fP\fIsector_width\fP[\fBr\fP] ] 
[ \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ] [ \fB\-C\fP[\fImode_file\fP] ] [ \fB\-D\fP ] [ \fB\-E\fP\fIazimuth\fP/\fIelevation\fP ] [ \fB\-I\fP ] [ \fB\-G\fP\fIfill\fP ] 
[ \fB\-H\fP[\fBi\fP][\fInrec\fP] ] [ \fB\-I\fP ] [ \fB\-K\fP ] [ \fB\-L\fP[\fIwlabel\fP/\fIelabel\fP/\fIslabel\fP/\fInlabel\fP] ] 
[ \fB\-M\fP[\fIparameters\fP ] [ \fB\-O\fP ] [ \fB\-P\fP ] 
[ \fB\-R\fP\fIr0\fP/\fIr1\fP/\fIaz_0\fP/\fIaz_1\fP ] [ \fB\-S\fP\fIradial_scale\fP[\fBn\fP] ] [ \fB\-T\fP ] [ \fB\-U\fP[\fIjust\fP/\fIdx\fP/\fIdy\fP/][\fBc\fP|\fIlabel\fP] ] 
[ \fB\-V\fP ] [ \fB\-W\fP\fIpen\fP ] [ \fB\-X\fP[\fBa\fP|\fBc\fP|\fBr\fP][\fIx-shift\fP[\fBu\fP]] ] 
[ \fB\-Y\fP[\fBa\fP|\fBc\fP|\fBr\fP][\fIy-shift\fP[\fBu\fP]] ] [ \fB\-Z\fP\fIscale\fP ] [ \fB\-c\fP\fIcopies\fP ] [ \fB\-:\fP[\fBi\fP|\fBo\fP] ] [ \fB\-bi\fP[\fBs\fP|\fBS\fP|\fBd\fP|\fBD\fP[\fIncol\fP]|\fBc\fP[\fIvar1\fP\fB/\fP\fI...\fP]] ]
.SH DESCRIPTION
\fBpsrose\fP reads (length,azimuth) pairs from \fIfile\fP [or standard input] and
generates \fIPostScript\fP code that will plot a windrose diagram.  Optionally (with \fB\-A\fP), polar histograms
may be drawn (sector diagram or rose diagram).  Options include full circle and half circle plots.
The \fIPostScript\fP code is written to standard output. 
.TP
\fIfile\fP
Name of ASCII [or binary, see \fB\-b\fP] data file.  If no file is given, psrose will read standard input.
.SH OPTIONS
No space between the option flag and the associated arguments.
.TP
\fB\-A\fP
Gives the sector width in degrees for sector and rose diagram.  [Default 0 means windrose diagram].  Append \fBr\fP to draw
rose diagram instead of sector diagram.
.TP
\fB\-B\fP
Sets map boundary annotation and tickmark intervals; see the
\fBpsbasemap\fP man page for all the details.
Remember that "x" here is radial distance and
"y" is azimuth.  The ylabel may be used to plot a figure caption.
.TP
\fB\-C\fP
Plot vectors showing the principal directions given in the \fImodes\fP file.  If no file is
given, compute and plot mean direction.
.TP
\fB\-D\fP
Shift sectors so that they are centered on the bin interval (e.g., first sector is centered on 0 degrees).
.TP
\fB\-E\fP
Sets the viewpoint's azimuth and elevation [180/90]\"'
.TP
\fB\-F\fP
Do not draw the scale length bar [Default plots scale in lower right corner]
.TP
\fB\-G\fP
Selects shade, color or pattern for filling the sectors [Default is no fill].
(See SPECIFYING FILL below).
.TP
\fB\-H\fP
Input file(s) has header record(s).  If used, the default number of header records is \fBN_HEADER_RECS\fP.
Use \fB\-Hi\fP if only input data should have header records [Default will write out header records if the
input data have them]. Blank lines and lines starting with # are always skipped.
.TP
\fB\-I\fP
Inquire.  Computes statistics needed to specify useful \fB\-R\fP.  No plot is generated.
.TP
\fB\-K\fP
More \fIPostScript\fP code will be appended later [Default terminates the plot system].
.TP
\fB\-L\fP
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 \fB\-L\fP with no argument to disable all four labels
.TP
\fB\-M\fP
Specify new arrow attributes tailwidth/headlength/headwidth/r/g/b to change
the appearance of arrows (Only if \fB\-C\fP is set). [Default is 0.075\fBc\fP/0.3\fBc\fP/0.25\fBc\fP/0/0/0 (or 0.03\fBi\fP/0.12\fBi\fP/0.1\fBi\fP/0/0/0)].
.TP
\fB\-O\fP
Selects Overlay plot mode [Default initializes a new plot system].
.TP
\fB\-P\fP
Selects Portrait plotting mode [Default is Landscape, see \fBgmtdefaults\fP to change this].
.TP
\fB\-R\fP
Specifies the 'region' of interest in (r,azimuth) space.  r0 is 0, r1 is max length in units.  For azimuth, specify
-90/90 for half circle plot or 0/360 for full circle.
.TP
\fB\-S\fP
Specifies radius of circle.  Append \fBn\fP to normalize input radii to go from 0 to 1.
.TP
\fB\-T\fP
Specifies that the input data is orientation data (has a 180 degree ambiguity) instead of true
0-360 degree directions [Default].
.TP
\fB\-U\fP
Draw Unix System time stamp on plot.
By adding \fIjust/dx/dy/\fP, the user may specify the justification of the stamp and
where the stamp should fall on the page relative to lower left corner of the plot.
For example, BL/0/0 will align the lower left corner of the time stamp with the lower left corner of the plot.
Optionally, append a \fIlabel\fP, or \fBc\fP (which will plot the command string.).
The \fBGMT\fP parameters \fBUNIX_TIME\fP, \fBUNIX_TIME_POS\fP, and \fBUNIX_TIME_FORMAT\fP can affect the appearance;
see the \fBgmtdefaults\fP man page for details.
The time string will be in the locale set by the environment variable \fBTZ\fP (generally local time).
.TP
\fB\-V\fP
Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
.TP
\fB\-W\fP
Set pen attributes for sector outline or rose plot.  [Default is no outline].
(See SPECIFYING PENS below).
.TP
\fB\-X\fP \fB\-Y\fP
Shift plot origin relative to the current origin by (\fIx-shift,y-shift\fP) and
optionally append the length unit (\fBc\fP, \fBi\fP, \fBm\fP, \fBp\fP).
You can prepend \fBa\fP to shift the origin back to the original position after plotting,
or prepend  \fBr\fP [Default] to reset the current origin to the new location.
If \fB\-O\fP is used then the default (\fIx-shift,y-shift\fP) is (0,0), otherwise it is
(r1i, r1i) or (r2.5c, r2.5c).
Alternatively, give \fBc\fP to align the center coordinate (x or y) of the plot with the center of the page
based on current page size.
.TP
\fB\-Z\fP
Multiply the data radii by \fIscale\fP.  E.g., use \fB\-Z\fP0.001 to convert your data from m to km [Default is no scaling].
.TP
\fB\-:\fP
Input file has (azimuth,radius) pairs rather than the expected (radius,azimuth).
.TP
\fB\-bi\fP
Selects binary input.
Append \fBs\fP for single precision [Default is \fBd\fP (double)].
Uppercase \fBS\fP or \fBD\fP will force byte-swapping.
Optionally, append \fIncol\fP, the number of columns in your binary input file
if it exceeds the columns needed by the program.
Or append \fBc\fP if the input file is netCDF. Optionally, append \fIvar1\fP\fB/\fP\fIvar2\fP\fB/\fP\fI...\fP to
specify the variables to be read.
[Default is 2 input columns].
.TP
\fB\-c\fP
Specifies the number of plot copies. [Default is 1].
.SS SPECIFYING PENS
.TP
\fIpen\fP
The attributes of lines and symbol outlines as defined by \fIpen\fP is a comma delimetered list of
\fIwidth\fP, \fIcolor\fP and \fItexture\fP, each of which is optional.
\fIwidth\fP can be indicated as a measure (points, centimeters, inches) or as \fBfaint\fP, \fBthin\fP[\fBner\fP|\fBnest\fP],
\fBthick\fP[\fBer\fP|\fBest\fP], \fBfat\fP[\fBter\fP|\fBtest\fP], or \fBobese\fP.
\fIcolor\fP specifies a gray shade or color (see SPECIFYING COLOR below).
\fItexture\fP is a combination of dashes `-' and dots `.'.
.SS SPECIFYING FILL
.TP
\fIfill\fP
The attribute \fIfill\fP specifies the solid shade or solid \fIcolor\fP
(see SPECIFYING COLOR below) or the pattern used for filling polygons.
Patterns are specified as \fBp\fP\fIdpi/pattern\fP, where \fIpattern\fP gives
the number of the built-in pattern (1-90) \fIor\fP the name of a Sun 1-, 8-,
or 24-bit raster file. The \fIdpi\fP sets the resolution of the image. For
1-bit rasters: use \fBP\fP\fIdpi/pattern\fP for inverse video, or append
\fB:F\fP\fIcolor\fP[\fBB\fP[\fIcolor\fP]] to specify fore- and background
colors (use \fIcolor\fP = - for transparency).
See \fBGMT\fP Cookbook & Technical Reference Appendix E for information
on individual patterns.
.SS SPECIFYING COLOR
.TP
\fIcolor\fP
The \fIcolor\fP of lines, areas and patterns can be specified by a valid color name;
by a gray shade (in the range 0\-255); by a decimal color code (r/g/b, each in range 0\-255; h-s-v, ranges
0\-360, 0\-1, 0\-1; or c/m/y/k, each in range 0\-1); or by a hexadecimal color code (#rrggbb, as used in HTML).
See the \fBgmtcolors\fP manpage for more information and a full list of color names.
.SH 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:
.br
.sp
\fBpsrose\fP fault_segments.az_r \fB\-R\fP0/150/-90/90 \fB\-B\fP50g25:"Fault length":/g30:."Rose diagram":
\fB\-S\fP3\fBi\fP \fB\-A\fP10\fBr\fP \fB\-G\fPlightblue \fB\-W\fP0.75\fBp\fP,red \fB\-Z\fP0.001 \fB\-C\fP \fB\-P\fP \fB\-T\fP \fB\-:\fP | lpr
.br
.sp
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:
.br
.sp
\fBpsrose\fP lines.az_r \fB\-R\fP0/500/0/360 \fB\-S\fP5\fBc\fP \fB\-Bg\fP100/\fBg\fP45:."Windrose diagram": \fB\-W\fP0.5\fBp\fP \fB\-Uc\fP | lpr
.SH BUGS
No default radial scale and grid settings for polar histograms.  User must run \fBpsrose \-I\fP to find max length in
binned data set.
.SH "SEE ALSO"
.IR GMT (1),
.IR gmtcolors (5),
.IR gmtdefaults (1),
.IR pshistogram (1)