"""
rose - Plot windrose diagrams or polar histograms.
"""
from pygmt.clib import Session
from pygmt.helpers import (
build_arg_string,
check_data_input_order,
deprecate_parameter,
fmt_docstring,
kwargs_to_strings,
use_alias,
)
@fmt_docstring
@deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
@check_data_input_order("v0.5.0", remove_version="v0.7.0")
@use_alias(
A="sector",
B="frame",
C="cmap",
D="shift",
Em="vectors",
F="no_scale",
G="color",
I="inquire",
JX="diameter",
L="labels",
M="vector_params",
Q="alpha",
R="region",
S="norm",
T="orientation",
U="timestamp",
V="verbose",
W="pen",
X="xshift",
Y="yshift",
Z="scale",
b="binary",
d="nodata",
e="find",
h="header",
i="incols",
c="panel",
p="perspective",
t="transparency",
w="wrap",
)
@kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
def rose(self, data=None, length=None, azimuth=None, **kwargs):
"""
Plot windrose diagrams or polar histograms.
Takes a matrix, (length,azimuth) pairs, or a file name as input
and plots windrose diagrams or polar histograms (sector diagram
or rose diagram).
Must provide either ``data`` or ``length`` and ``azimuth``.
Options include full circle and half circle plots. The outline
of the windrose is drawn with the same color as
:gmt-term:`MAP_DEFAULT_PEN`.
Full option list at :gmt-docs:`rose.html`
{aliases}
Parameters
----------
data : str or {table-like}
Pass in either a file name to an ASCII data table, a 2D
{table-classes}.
Use option ``columns`` to choose which columns are length and azimuth,
respectively. If a file with only azimuths is given, use ``columns`` to
indicate the single column with azimuths; then all lengths are set to
unity (see ``scale = 'u'`` to set actual lengths to unity as well).
length/azimuth : float or 1d arrays
Length and azimuth values, or arrays of length and azimuth
values
orientation : bool
Specifies that the input data are orientation data (i.e., have a
180 degree ambiguity) instead of true 0-360 degree directions
[Default is 0-360 degrees]. 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.
region : str or list
*Required if this is the first plot command*.
*r0/r1/az0/az1*.
Specifies the 'region' of interest in (*r*, *azimuth*) space. Here,
*r0* is 0, *r1* is max length in units. For *az0* and *az1*,
specify either -90/90 or 0/180 for half circle plot or 0/360 for
full circle.
diameter : str
Sets the diameter of the rose diagram. If not given,
then we default to a diameter of 7.5 cm.
sector : str
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 (e.g. ``'10+r'``).
norm : bool
Normalize input radii (or bin counts if ``sector_width`` is used)
by the largest value so all radii (or bin counts) range from 0
to 1.
frame : str
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.
scale : float or str
Multiply the data radii by scale. E.g., use ``scale = 0.001`` to
convert your data from m to km. To exclude the radii from
consideration, set them all to unity with ``scale = 'u'``
[Default is no scaling].
color : str
Selects shade, color or pattern for filling the sectors [Default
is no fill].
cmap : str
Give a CPT. The *r*-value for each sector is used to look-up the
sector color. Cannot be used with a rose diagram.
pen : str
Set pen attributes for sector outline or rose plot, e.g.
``pen = '0.5p'``. [Default is no outline]. To change pen used to
draw vector (requires ``vectors``) [Default is same as sector
outline] use e.g. ``pen = 'v0.5p'``.
labels : str
``'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
(e.g. ``labels = 'W,E,-,N'``). Use ``labels = ''`` to disable
all four labels. Note that the :gmt-term:`GMT_LANGUAGE` setting
will affect the words used.
no_scale : bool
Do NOT draw the scale length bar (``no_scale = True``).
Default plots scale in lower right corner provided ``frame``
is used.
shift : bool
Shift sectors so that they are centered on the bin interval
(e.g., first sector is centered on 0 degrees).
vectors : str
``vectors = 'mode_file'``. Plot vectors showing the
principal directions given in the *mode_file* file.
Alternatively, specify ``vectors`` to compute and plot
mean direction. See ``vector_params`` to control the vector
attributes. Finally, to instead save the computed mean
direction and other statistics, use
``vectors = '+wmode_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
``alpha``.
vector_params : str
Used with ``vectors`` to modify vector parameters. For
vector heads, append vector head size [Default is 0, i.e., a
line]. See :gmt-docs:`rose.html#vector-attributes` for
specifying additional attributes. If ``vectors`` is not
given and the current plot mode is to draw a windrose diagram
then using ``vector_params`` will add vector heads to all
individual directions using the supplied attributes.
alpha : float or str
Sets the confidence level used to determine if the mean
resultant is significant (i.e., Lord Rayleigh test for
uniformity) [``alpha = 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.
Berens, P., 2009, CircStat: A MATLAB Toolbox for Circular
Statistics, *J. Stat. Software*, 31(10), 1-21,
https://doi.org/10.18637/jss.v031.i10.
{U}
{V}
{XY}
{b}
{c}
{d}
{e}
{h}
{i}
{p}
{t}
{w}
"""
kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access
with Session() as lib:
# Choose how data will be passed into the module
file_context = lib.virtualfile_from_data(
check_kind="vector", data=data, x=length, y=azimuth
)
with file_context as fname:
arg_str = " ".join([fname, build_arg_string(kwargs)])
lib.call_module("rose", arg_str)