Wrap velo (GenericMappingTools#525)

Add `velo` function for plotting velocity vectors, crosses, anisotropy
bars, and wedges. Original GMT velo function can be found at
https://docs.generic-mapping-tools.org/6.1/supplements/geodesy/velo.html

* clarify the type of data input
* raise error if alias S is not defined
* Refactor velo to use virtualfile_from_data and add three more unit tests
* Alias panel (c) for velo, and lightly edit some docstrings
* Alias scale (H), intensity (I) and zvalue (Z) from GMT 6.2.0

Update docstring to include new options in `velo`
from the upcoming GMT 6.2.0 that were added in
GenericMappingTools/gmt#4970,
GenericMappingTools/gmt#4901, and
GenericMappingTools/gmt#4907.
Removed the default vector="+p1p+e" argument, and
formatted docstring to have nested lists to be nicer looking.

* Fix typos and add intersphinx mappings
* Update the frame, region, projection and color of velo example
* Rename alias intensity for -I to shading
* Rename alias facecolor for -G to color
* Move docstring for projection (J) and region (R) up a bit
* Rename alias to spec (S) and update baseline images for GMT 6.2.0rc1
* Mark fig.velo tests with xfail
* Rename alias uncertainty_color to uncertaintycolor for parameter E
* Move velo_arrow_ellipse.py under "Seismology and Geodesy" category

Co-authored-by: Wei Ji <[email protected]>
Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Michael Grund <[email protected]>
Co-authored-by: Meghan Jones <[email protected]>

doc/api/index.rst

@@ -43,6 +43,7 @@ Plotting data and laying out the map:
     Figure.solar
     Figure.subplot
     Figure.text
+    Figure.velo
     Figure.wiggle
 
 Color palette table generation:

examples/gallery/seismology/velo_arrow_ellipse.py

@@ -0,0 +1,41 @@
+"""
+Velocity arrows and confidence ellipses
+---------------------------------------
+
+The :meth:`pygmt.Figure.velo` method can be used to plot mean velocity arrows
+and confidence ellipses. The example below plots red velocity arrows with
+light-blue confidence ellipses outlined in red with the east_velocity x
+north_velocity used for the station names. Note that the velocity arrows are
+scaled by 0.2 and the 39% confidence limit will give an ellipse which fits
+inside a rectangle of dimension east_sigma by north_sigma.
+"""
+
+import pandas as pd
+import pygmt
+
+fig = pygmt.Figure()
+df = pd.DataFrame(
+    data={
+        "x": [0, -8, 0, -5, 5, 0],
+        "y": [-8, 5, 0, -5, 0, -5],
+        "east_velocity": [0, 3, 4, 6, -6, 6],
+        "north_velocity": [0, 3, 6, 4, 4, -4],
+        "east_sigma": [4, 0, 4, 6, 6, 6],
+        "north_sigma": [6, 0, 6, 4, 4, 4],
+        "correlation_EN": [0.5, 0.5, 0.5, 0.5, -0.5, -0.5],
+        "SITE": ["0x0", "3x3", "4x6", "6x4", "-6x4", "6x-4"],
+    }
+)
+fig.velo(
+    data=df,
+    region=[-10, 8, -10, 6],
+    pen="0.6p,red",
+    uncertaintycolor="lightblue1",
+    line=True,
+    spec="e0.2/0.39/18",
+    frame=["WSne", "2g2f"],
+    projection="x0.8c",
+    vector="0.3c+p1p+e+gred",
+)
+
+fig.show()

pygmt/figure.py

@@ -426,6 +426,7 @@ def _repr_html_(self):
         solar,
         subplot,
         text,
+        velo,
         wiggle,
     )
 

pygmt/src/__init__.py

@@ -32,6 +32,7 @@
 from pygmt.src.subplot import set_panel, subplot
 from pygmt.src.surface import surface
 from pygmt.src.text import text_ as text  # "text" is an argument within "text_"
+from pygmt.src.velo import velo
 from pygmt.src.which import which
 from pygmt.src.wiggle import wiggle
 from pygmt.src.x2sys_cross import x2sys_cross

pygmt/src/velo.py

@@ -0,0 +1,247 @@
+"""
+velo - Plot velocity vectors, crosses, anisotropy bars, and wedges.
+"""
+import numpy as np
+import pandas as pd
+from pygmt.clib import Session
+from pygmt.exceptions import GMTInvalidInput
+from pygmt.helpers import build_arg_string, fmt_docstring, kwargs_to_strings, use_alias
+
+
+@fmt_docstring
+@use_alias(
+    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",
+    p="perspective",
+    t="transparency",
+)
+@kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
+def velo(self, data=None, **kwargs):
+    r"""
+    Plot velocity vectors, crosses, anisotropy bars, and wedges.
+
+    Reads data values from files, :class:`numpy.ndarray` or
+    :class:`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 :gmt-docs:`supplements/geodesy/velo.html`
+
+    {aliases}
+
+    Parameters
+    ----------
+    data : str or numpy.ndarray or pandas.DataFrame
+        Either a file name, a 2D :class:`numpy.ndarray` or a
+        :class:`pandas.DataFrame` with 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
+        :gmt-term:`PROJ_LENGTH_UNIT` unless **c**, **i**, or **p** is
+        appended).
+
+        - **e**\ [*velscale*/]\ *confidence*\ [**+f**\ *font*]
+
+          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 **+f**\ 0 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*\ [**+f**\ *font*]
+
+          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 **+f**\ 0 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.
+
+    {J}
+    {R}
+    vector : bool or str
+        Modify vector parameters. For vector heads, append vector head *size*
+        [Default is 9p]. See
+        :gmt-docs:`supplements/geodesy/velo.html#vector-attributes` for
+        specifying additional attributes.
+    {B}
+    {CPT}
+    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
+        :gmt-docs:`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
+        :gmt-docs:`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].
+    {U}
+    {V}
+    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.
+    {XY}
+    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 **m**\ agnitude (vector magnitude
+        or rotation magnitude), **e**\ ast-west velocity, **n**\ orth-south
+        velocity, or **u**\ ser-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**.
+    {c}
+    {p}
+    {t}
+    """
+    kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
+
+    if "S" not in kwargs or ("S" in kwargs and not isinstance(kwargs["S"], str)):
+        raise GMTInvalidInput("Spec is a required argument and has to be a string.")
+
+    if isinstance(data, np.ndarray) and not pd.api.types.is_numeric_dtype(data):
+        raise GMTInvalidInput(
+            "Text columns are not supported with numpy.ndarray type inputs. "
+            "They are only supported with file or pandas.DataFrame inputs."
+        )
+
+    with Session() as lib:
+        # Choose how data will be passed in to the module
+        file_context = lib.virtualfile_from_data(check_kind="vector", data=data)
+
+        with file_context as fname:
+            arg_str = " ".join([fname, build_arg_string(kwargs)])
+            lib.call_module("velo", arg_str)

pygmt/tests/baseline/test_velo_numpy_array_numeric_only.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: 64e45d586112fc131090cfac2c104b63
+  size: 45483
+  path: test_velo_numpy_array_numeric_only.png

pygmt/tests/baseline/test_velo_pandas_dataframe.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: 60dff1a72e6d984f095fb4973cecaec7
+  size: 42430
+  path: test_velo_pandas_dataframe.png