pygmt.Figure.rose

Figure.rose(length=None, azimuth=None, data=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 MAP_DEFAULT_PEN (see:gmt-docs:gmt.conf.html#term-MAP_DEFAULT_PEN).

Full option list at https://docs.generic-mapping-tools.org/latest/rose.html

Aliases:

  • A = sector_width

  • B = frame

  • C = cmap

  • D = shift_sectors

  • Em = plot_vectors

  • F = no_scalebar

  • G = color

  • I = inquire

  • JX = diameter

  • L = labels

  • M = vector_params

  • Q = conf_level

  • R = region

  • S = norm

  • T = orient_data

  • U = timestamp

  • V = verbose

  • W = pen

  • X = xshift

  • Y = yshift

  • Z = scale

  • i = columns

  • p = perspective

  • t = transparency

Parameters

  • length/azimuth (float or 1d arrays) – The length and azimuth values, or arrays of length and azimuth values

  • data (str or 2d array) – Either a data file name or a 2d numpy array with the tabular data. Use option columns (i) to choose which columns are length and azimuth, respectively. If a file with only azimuths are 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).

  • orient_data (bool) – 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.

  • 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. 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.

  • sector_width (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. '10r').

  • 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].

  • columns (str or 1d array) – Select input columns and transformations. E.g. choose columns = [1, 0] or columns = '1,0' if the length values are stored in the second column and the direction (azimuth) values in the first one. Note: zero-based indexing is used.

  • 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 plot_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_LANGUAGE setting will affect the words used.

  • no_scalebar (bool) – Do NOT draw the scale length bar (no_scalebar = True). Default plots scale in lower right corner provided frame is used.

  • shift_sectors (bool) – Shift sectors so that they are centered on the bin interval (e.g., first sector is centered on 0 degrees).

  • plot_vectors (str) – plot_vectors = 'mode_file'. Plot vectors showing the principal directions given in the mode_file file. Alternatively, specify plot_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 plot_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 conf_level.

  • vector_params (str) – Used with plot_vectors to modify vector parameters. For vector heads, append vector head size [Default is 0, i.e., a line]. See VECTOR ATTRIBUTES under https://docs.generic-mapping-tools.org/latest/rose.html for specifying additional attributes. If plot_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.

  • conf_level (float or str) –

    Sets the confidence level used to determine if the mean resultant is significant (i.e., Lord Rayleigh test for uniformity) [conf_level = 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, 10.18637/jss.v031.i10.

  • inquire – Inquire. Computes statistics needed to specify a useful frame. 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.

  • timestamp (bool or str) – Draw GMT time stamp logo on plot.

  • verbose (str) –

    Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:

    • q - Quiet, not even fatal error messages are produced

    • e - Error messages only

    • w - Warnings [Default]

    • t - Timings (report runtimes for time-intensive algorthms);

    • i - Informational messages (same as “verbose=True”)

    • c - Compatibility warnings

    • d - Debugging messages

  • xshift (str) – [a|c|f|r][xshift]. Shift plot origin in x-direction.

  • yshift (str) – [a|c|f|r][yshift]. Shift plot origin in y-direction. Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#xy-full.

  • perspective (list or str) – '[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]'. Select perspective view and set the azimuth and elevation angle of the viewpoint. Default is [180, 90]. Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#perspective-full.

  • transparency (float) – Set transparency level, in [0-100] percent range. Default is 0, i.e., opaque. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).