pygmt.Figure.velo

Figure.velo(data=None, *, vector=None, frame=None, cmap=None, rescale=None, uncertaintycolor=None, color=None, scale=None, shading=None, projection=None, line=None, no_clip=None, region=None, spec=None, timestamp=None, verbose=None, pen=None, xshift=None, yshift=None, zvalue=None, panel=None, nodata=None, find=None, header=None, incols=None, perspective=None, transparency=None, **kwargs)

Plot velocity vectors, crosses, anisotropy bars, and wedges.

Reads data values from files, numpy.ndarray or pandas.DataFrame and plots the selected geodesy symbol on a map. You may choose from velocity vectors and their uncertainties, rotational wedges and their uncertainties, anisotropy bars, or strain crosses. Symbol fills or their outlines may be colored based on constant parameters or via color lookup tables.

Must provide data and spec.

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

Aliases:

  • A = vector

  • B = frame

  • C = cmap

  • D = rescale

  • E = uncertaintycolor

  • G = color

  • H = scale

  • I = shading

  • J = projection

  • L = line

  • N = no_clip

  • R = region

  • S = spec

  • U = timestamp

  • V = verbose

  • W = pen

  • X = xshift

  • Y = yshift

  • Z = zvalue

  • c = panel

  • d = nodata

  • e = find

  • h = header

  • i = incols

  • p = perspective

  • t = transparency

Parameters
  • data (str or numpy.ndarray or pandas.DataFrame or xarray.Dataset or geopandas.GeoDataFrame) – Pass in either a file name to an ASCII data table, a 2D numpy.ndarray, a pandas.DataFrame, an xarray.Dataset made up of 1D xarray.DataArray data variables, or a geopandas.GeoDataFrame containing the tabular data. Note that text columns are only supported with file or pandas.DataFrame inputs.

  • spec (str) –

    Selects the meaning of the columns in the data file and the figure to be plotted. In all cases, the scales are in data units per length unit and sizes are in length units (default length unit is controlled by PROJ_LENGTH_UNIT unless c, i, or p is appended).

    • e[velscale/]confidence[+ffont]

      Velocity ellipses in (N,E) convention. The velscale sets the scaling of the velocity arrows. If velscale is not given then we read it from the data file as an extra column. The confidence sets the 2-dimensional confidence limit for the ellipse, e.g. 0.95 for 95% confidence ellipse. Use +f to set the font and size of the text [Default is 9p,Helvetica,black]; give +f0 to deactivate labeling. The arrow will be drawn with the pen attributes specified by the pen option and the arrow-head can be colored via color. The ellipse will be filled with the color or shade specified by the uncertaintycolor option [Default is transparent], and its outline will be drawn if line is selected using the pen selected (by pen if not given by line). Parameters are expected to be in the following columns:

      • 1,2: longitude, latitude of station

      • 3,4: eastward, northward velocity

      • 5,6: uncertainty of eastward, northward velocities (1-sigma)

      • 7: correlation between eastward and northward components

      • Trailing text: name of station (optional)

    • n[barscale]

      Anisotropy bars. barscale sets the scaling of the bars. If barscale is not given then we read it from the data file as an extra column. Parameters are expected to be in the following columns:

      • 1,2: longitude, latitude of station

      • 3,4: eastward, northward components of anisotropy vector

    • r[velscale/]confidence[+ffont]

      Velocity ellipses in rotated convention. The velscale sets the scaling of the velocity arrows. If velscale is not given then we read it from the data file as an extra column. The confidence sets the 2-dimensional confidence limit for the ellipse, e.g. 0.95 for 95% confidence ellipse. Use +f to set the font and size of the text [Default is 9p,Helvetica,black]; give +f0 to deactivate labeling. The arrow will be drawn with the pen attributes specified by the pen option and the arrow-head can be colored via color. The ellipse will be filled with the color or shade specified by the uncertaintycolor option [Default is transparent], and its outline will be drawn if line is selected using the pen selected (by pen if not given by line). Parameters are expected to be in the following columns:

      • 1,2: longitude, latitude of station

      • 3,4: eastward, northward velocity

      • 5,6: semi-major, semi-minor axes

      • 7: counter-clockwise angle, in degrees, from horizontal axis to major axis of ellipse.

      • Trailing text: name of station (optional)

    • w[wedgescale/]wedgemag

      Rotational wedges. The wedgescale sets the size of the wedges. If wedgescale is not given then we read it from the data file as an extra column. Rotation values are multiplied by wedgemag before plotting. For example, setting wedgemag to 1.e7 works well for rotations of the order of 100 nanoradians/yr. Use color to set the fill color or shade for the wedge, and uncertaintycolor to set the color or shade for the uncertainty. Parameters are expected to be in the following columns:

      • 1,2: longitude, latitude of station

      • 3: rotation in radians

      • 4: rotation uncertainty in radians

    • x[cross_scale]

      Strain crosses. The cross_scale sets the size of the cross. If cross_scale is not given then we read it from the data file as an extra column. Parameters are expected to be in the following columns:

      • 1,2: longitude, latitude of station

      • 3: eps1, the most extensional eigenvalue of strain tensor, with extension taken positive.

      • 4: eps2, the most compressional eigenvalue of strain tensor, with extension taken positive.

      • 5: azimuth of eps2 in degrees CW from North.

  • projection (str) – projcode[projparams/]width. Select map projection.

  • region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • vector (bool or str) – Modify vector parameters. For vector heads, append vector head size [Default is 9p]. See https://docs.generic-mapping-tools.org/latest/supplements/geodesy/velo.html#vector-attributes for specifying additional attributes.

  • frame (bool or str or list) – Set map boundary frame and axes attributes.

  • cmap (str) – File name of a CPT file or a series of comma-separated colors (e.g., color1,color2,color3) to build a linear continuous CPT from those colors automatically.

  • rescale (str) – can be used to rescale the uncertainties of velocities (spec='e' and spec='r') and rotations (spec='w'). Can be combined with the confidence variable.

  • uncertaintycolor (str) – Sets the color or shade used for filling uncertainty wedges (spec='w') or velocity error ellipses (spec='e' or spec='r'). If uncertaintycolor is not specified, the uncertainty regions will be transparent. Note: Using cmap and zvalue='+e' will update the uncertainty fill color based on the selected measure in zvalue [magnitude error]. More details at https://docs.generic-mapping-tools.org/latest/cookbook/features.html#gfill-attrib.

  • color (str) – Select color or pattern for filling of symbols [Default is no fill]. Note: Using cmap (and optionally zvalue) will update the symbol fill color based on the selected measure in zvalue [magnitude]. More details at https://docs.generic-mapping-tools.org/latest/cookbook/features.html#gfill-attrib.

  • scale (float or bool) – [scale]. Scale symbol sizes and pen widths on a per-record basis using the scale read from the data set, given as the first column after the (optional) z and size columns [Default is no scaling]. The symbol size is either provided by spec or via the input size column. Alternatively, append a constant scale that should be used instead of reading a scale column.

  • shading (float or bool) – intens. Use the supplied intens value (nominally in the -1 to +1 range) to modulate the symbol fill color by simulating illumination [Default is none]. If intens is not provided we will instead read the intensity from an extra data column after the required input columns determined by spec.

  • line (str) – [pen[+c[f|l]]]. Draw lines. Ellipses and rotational wedges will have their outlines drawn using the current pen (see pen). Alternatively, append a separate pen to use for the error outlines. If the modifier +cl is appended then the color of the pen is updated from the CPT (see cmap). If instead modifier +cf is appended then the color from the cpt file is applied to error fill only [Default]. Use just +c to set both pen and fill color.

  • no_clip (bool or str) – Do NOT skip symbols that fall outside the frame boundary specified by region. [Default plots symbols inside frame only].

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

  • verbose (bool or 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 algorithms);

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

    • c - Compatibility warnings

    • d - Debugging messages

  • pen (str) – [pen][+c[f|l]]. Set pen attributes for velocity arrows, ellipse circumference and fault plane edges. [Defaults: width = default, color = black, style = solid]. If the modifier +cl is appended then the color of the pen is updated from the CPT (see cmap). If instead modifier +cf is appended then the color from the cpt file is applied to symbol fill only [Default]. Use just +c to set both pen and fill color.

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

  • zvalue (str) – [m|e|n|u][+e]. Select the quantity that will be used with the CPT given via cmap to set the fill color. Choose from magnitude (vector magnitude or rotation magnitude), east-west velocity, north-south velocity, or user-supplied data column (supplied after the required columns). To instead use the corresponding error estimates (i.e., vector or rotation uncertainty) to lookup the color and paint the error ellipse or wedge instead, append +e.

  • panel (bool or int or list) – [row,col|index]. Select a specific subplot panel. Only allowed when in subplot mode. Use panel=True to advance to the next panel in the selected order. Instead of row,col you may also give a scalar value index which depends on the order you set via autolabel when the subplot was defined. Note: row, col, and index all start at 0.

  • nodata (str) – i|onodata. Substitute specific values with NaN (for tabular data). For example, d="-9999" will replace all values equal to -9999 with NaN during input and all NaN values with -9999 during output. Prepend i to the nodata value for input columns only. Prepend o to the nodata value for output columns only.

  • find (str) – [~]“pattern” | [~]/regexp/[i]. Only pass records that match the given pattern or regular expressions [Default processes all records]. Prepend ~ to the pattern or regexp to instead only pass data expressions that do not match the pattern. Append i for case insensitive matching. This does not apply to headers or segment headers.

  • header (str) –

    [i|o][n][+c][+d][+msegheader][+rremark][+ttitle]. Specify that input and/or output file(s) have n header records [Default is 0]. Prepend i if only the primary input should have header records. Prepend o to control the writing of header records, with the following modifiers supported:

    • +d to remove existing header records.

    • +c to add a header comment with column names to the output [Default is no column names].

    • +m to add a segment header segheader to the output after the header block [Default is no segment header].

    • +r to add a remark comment to the output [Default is no comment]. The remark string may contain \n to indicate line-breaks.

    • +t to add a title comment to the output [Default is no title]. The title string may contain \n to indicate line-breaks.

    Blank lines and lines starting with # are always skipped.

  • incols (str or 1d array) –

    Specify data columns for primary input in arbitrary order. Columns can be repeated and columns not listed will be skipped [Default reads all columns in order, starting with the first (i.e., column 0)].

    • For 1d array: specify individual columns in input order (e.g., incols=[1,0] for the 2nd column followed by the 1st column).

    • For str: specify individual columns or column ranges in the format start[:inc]:stop, where inc defaults to 1 if not specified, with columns and/or column ranges separated by commas (e.g., incols="0:2,4+l" to input the first three columns followed by the log-transformed 5th column). To read from a given column until the end of the record, leave off stop when specifying the column range. To read trailing text, add the column t. Append the word number to t to ingest only a single word from the trailing text. Instead of specifying columns, use incols="n" to simply read numerical input and skip trailing text. Optionally, append one of the following modifiers to any column or column range to transform the input columns:

      • +l to take the log10 of the input values.

      • +d to divide the input values by the factor divisor [Default is 1].

      • +s to multiple the input values by the factor scale [Default is 1].

      • +o to add the given offset to the input values [Default is 0].

  • 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 (int or 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).

Examples using pygmt.Figure.velo