Wrap meca

doc/api/index.rst

@@ -35,6 +35,7 @@ Plotting data and laying out the map:
     Figure.image
     Figure.shift_origin
     Figure.text
+    Figure.meca
 
 Color palette table generation:
 

examples/gallery/plot/meca.py

@@ -0,0 +1,33 @@
+"""
+Focal mechanisms
+----------------
+
+The :meth:`pygmt.Figure.meca` method can plot focal mechanisms, or beachballs.
+We can specify the focal mechanism nodal planes or moment tensor components as
+a dict using the ``spec`` argument (or they can be specified as a 1d or 2d array,
+or within a specified file). The size of plotted beachballs can be specified 
+using the ``scale`` argument.
+"""
+
+import pygmt
+
+fig = pygmt.Figure()
+
+# generate a basemap near Washington state showing coastlines, land, and water
+fig.coast(
+    region=[-125, -122, 47, 49],
+    projection="M6c",
+    land="grey",
+    water="lightblue",
+    shorelines=True,
+    resolution="f",
+    frame="a",
+)
+
+# store focal mechanisms parameters in a dict
+focal_mechanism = dict(strike=330, dip=30, rake=90, magnitude=3)
+
+# pass the focal mechanism data to meca in addition to the scale and event location
+fig.meca(focal_mechanism, scale="1c", lon=-124.3, lat=48.1, depth=12.0)
+
+fig.show()

pygmt/base_plotting.py

@@ -8,7 +8,7 @@
 import pandas as pd
 
 from .clib import Session
-from .exceptions import GMTInvalidInput
+from .exceptions import GMTError, GMTInvalidInput
 from .helpers import (
     build_arg_string,
     dummy_context,
@@ -984,3 +984,213 @@ def text(
 
                 arg_str = " ".join([fname, build_arg_string(kwargs)])
                 lib.call_module("text", arg_str)
+
+    @fmt_docstring
+    @use_alias(R="region", J="projection", B="frame", C="offset")
+    @kwargs_to_strings(R="sequence",)
+    def meca(
+        self,
+        spec,
+        scale,
+        lon=None,
+        lat=None,
+        depth=None,
+        convention=None,
+        component="full",
+        plot_lon=None,
+        plot_lat=None,
+        text=None,
+        text_options="",
+        **kwargs,
+    ):
+        """
+        Plot focal mechanisms.
+
+        Full option list at :gmt-docs:`supplements/seis/meca.html`
+
+        {aliases}
+
+        Parameters
+        ----------
+        spec: dict, 1D array, 2D array, or str
+            Either a filename containing focal mechanism parameters as columns,
+            a 1- or 2-D array with the same, or a dictionary. If a filename or
+            array, `convention` is required so we know how to interpret the
+            columns/entries. If a dictionary, the following combinations of
+            keys are supported; these determine the convention.
+
+            - ``"aki"`` — *strike, dip, rake, magnitude*
+            - ``"gcmt"`` — *strike1, dip1, rake1, strike2, dip2, rake2,
+              mantissa, exponent*
+            - ``"mt"`` — *mrr, mtt, mff, mrt, mrf, mtf, exponent*
+            - ``"partial"`` — *strike1, dip1, strike2, fault_type, magnitude*
+            - ``"principal_axis"`` — *t_exponent, t_azimuth, t_plunge,
+              n_exponent, n_azimuth, n_plunge, p_exponent, p_azimuth, p_plunge,
+              exponent*
+
+        scale: str
+            Adjusts the scaling of the radius of the beachball, which is
+            proportional to the magnitude. Scale defines the size for
+            magnitude = 5 (i.e. scalar seismic moment M0 = 4.0E23 dynes-cm)
+        lon: int or float
+            Longitude of event location. Ignored if `spec` is not a dictionary.
+        lat: int or float
+            Latitude of event location. Ignored if `spec` is not a dictionary.
+        depth: int or float
+            Depth of event location in kilometers. Ignored if `spec` is not a
+            dictionary.
+        convention: str
+            ``"aki"`` (Aki & Richards), ``"gcmt"`` (global CMT), ``"mt"``
+            (seismic moment tensor), ``"partial"`` (partial focal mechanism),
+            or ``"principal_axis"`` (principal axis). Ignored if `spec` is a
+            dictionary.
+        component: str
+            The component of the seismic moment tensor to plot. ``"full"`` (the
+            full seismic moment tensor), ``"dc"`` (the closest double couple
+            with zero trace and zero determinant), ``"deviatoric"`` (zero
+            trace)
+        plot_lon: int or float
+            Longitude at which to place beachball, only used if `spec` is a
+            dictionary.
+        plot_lat: int or float
+            Latitude at which to place beachball, only used if `spec` is a
+            dictionary.
+        text: str
+            Text string to appear near the beachball, only used if `spec` is a
+            dictionary.
+        text_options: str
+            Options for text labeling of beachballs, in the format
+            ``[+aangle][+ffont][+jjustify][+odx[/dy]]``
+        offset: bool or str
+            Offsets beachballs to the longitude, latitude specified in
+            the last two columns of the input file or array, or by `plot_lon`
+            and `plot_lat` if provided. A small circle is plotted at the
+            initial location and a line connects the beachball to the circle.
+            Specify pen and optionally append ``+ssize`` to change the line
+            style and/or size of the circle.
+        {J}
+        {R}
+        {B}
+        """
+
+        # Check the spec and parse the data according to the specified
+        # convention
+        if isinstance(spec, dict):
+            if lon is None or lat is None or depth is None:
+                raise GMTError("Location not fully specified.")
+
+            AKI_PARAMS = ["strike", "dip", "rake", "magnitude"]
+            GCMT_PARAMS = [
+                "strike1",
+                "dip1",
+                "rake1",
+                "strike2",
+                "dip2",
+                "rake2",
+                "mantissa",
+                "exponent",
+            ]
+            # FIXME: allow specification of moment instead of mantissa and
+            # exponent.
+            MT_PARAMS = ["mrr", "mtt", "mff", "mrt", "mrf", "mtf", "exponent"]
+            PARTIAL_PARAMS = ["strike1", "dip1", "strike2", "fault_type", "magnitude"]
+            PRINCIPAL_AXIS_PARAMS = [
+                "t_exponent",
+                "t_azimuth",
+                "t_plunge",
+                "n_exponent",
+                "n_azimuth",
+                "n_plunge",
+                "p_exponent",
+                "p_azimuth",
+                "p_plunge",
+                "exponent",
+            ]
+
+            # Aki and Richards convention: -Sa in GMT
+            if set(spec.keys()) == set(AKI_PARAMS):
+                convention = "aki"
+                foc_params = AKI_PARAMS
+
+            # Global CMT convention: -Sc in GMT
+            elif set(spec.keys()) == set(GCMT_PARAMS):
+                convention = "gcmt"
+                foc_params = GCMT_PARAMS
+
+            # Seismic moment tensor convention: -Sm|d|z in GMT
+            elif set(spec.keys()) == set(MT_PARAMS):
+                convention = "mt"
+                foc_params = MT_PARAMS
+
+            # Partial focal mechanism convention: -Sp in GMT
+            elif set(spec.keys()) == set(PARTIAL_PARAMS):
+                convention = "partial"
+                foc_params = PARTIAL_PARAMS
+
+            # Principal axis convention: -Sx|y|t in GMT
+            elif set(spec.keys()) == set(PRINCIPAL_AXIS_PARAMS):
+                convention = "principle_axis"
+                foc_params = PRINCIPAL_AXIS_PARAMS
+
+            else:
+                raise GMTError(
+                    "Parameters in spec dictionary do not match known conventions."
+                )
+
+            # Construct the vector (note that order matters here, hence the
+            # list comprehension!)
+            spec = [lon, lat, depth] + [spec[key] for key in foc_params]
+
+            # Add in plotting options, if given, otherwise add 0s as required
+            # by GMT
+            for arg in plot_lon, plot_lat, text:
+                if arg is None:
+                    spec.append(0)
+                else:
+                    if "C" not in kwargs:
+                        kwargs["C"] = True
+                    spec.append(arg)
+
+        # Add condition and scale to kwargs
+        if convention == "aki":
+            format = "a"
+        elif convention == "gcmt":
+            format = "c"
+        elif convention == "mt":
+            # Check which component of mechanism the user wants plotted
+            if component == "deviatoric":
+                format = "z"
+            elif component == "dc":
+                format = "d"
+            else:  # component == 'full'
+                format = "m"
+        elif convention == "partial":
+            format = "p"
+        elif convention == "principal_axis":
+            # Check which component of mechanism the user wants plotted
+            if component == "deviatoric":
+                format = "t"
+            elif component == "dc":
+                format = "y"
+            else:  # component == 'full'
+                format = "x"
+        # Support old-school GMT format options
+        elif convention in ["a", "c", "m", "d", "z", "p", "x", "y", "t"]:
+            format = convention
+        else:
+            raise GMTError("Convention not recognized.")
+
+        # Assemble -S flag
+        kwargs["S"] = format + scale + text_options
+
+        kind = data_kind(spec)
+        with Session() as lib:
+            if kind == "matrix":
+                file_context = lib.virtualfile_from_matrix(np.atleast_2d(spec))
+            elif kind == "file":
+                file_context = dummy_context(spec)
+            else:
+                raise GMTInvalidInput("Unrecognized data type: {}".format(type(spec)))
+            with file_context as fname:
+                arg_str = " ".join([fname, build_arg_string(kwargs)])
+                lib.call_module("meca", arg_str)

pygmt/tests/data/fullmt_ipts1_iref1

@@ -0,0 +1,57 @@
+    -30.000000    -75.000000      0.000000 -1.954625e+00 -3.743529e+00 -3.743529e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000    -60.000000      0.000000 -5.177966e-01 -3.973692e+00 -3.973692e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000    -45.000000      0.000000  9.543192e-01 -3.933055e+00 -3.933055e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000    -30.000000      0.000000  2.361400e+00 -3.624387e+00 -3.624387e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000    -15.000000      0.000000  3.607555e+00 -3.068723e+00 -3.068723e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000      0.000000      0.000000  4.607861e+00 -2.303930e+00 -2.303930e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000     15.000000      0.000000  5.294149e+00 -1.382129e+00 -1.382129e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000     30.000000      0.000000  5.619649e+00 -3.661375e-01 -3.661375e-01  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000     45.000000      0.000000  5.562180e+00  6.748056e-01  6.748056e-01  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000     60.000000      0.000000  5.125657e+00  1.669762e+00  1.669762e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -30.000000     75.000000      0.000000  4.339830e+00  2.550926e+00  2.550926e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000    -75.000000      0.000000 -1.995262e+00 -3.455896e+00 -3.990525e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000    -60.000000      0.000000 -5.963011e-01 -3.418028e+00 -4.450852e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000    -45.000000      0.000000  8.432971e-01 -3.147228e+00 -4.607861e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000    -30.000000      0.000000  2.225426e+00 -2.661949e+00 -4.450852e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000    -15.000000      0.000000  3.455896e+00 -1.995262e+00 -3.990525e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000      0.000000      0.000000  4.450852e+00 -1.192602e+00 -3.258250e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000     15.000000      0.000000  5.142490e+00 -3.086682e-01 -2.303930e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000     30.000000      0.000000  5.483676e+00  5.963011e-01 -1.192602e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000     45.000000      0.000000  5.451158e+00  1.460633e+00  0.000000e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000     60.000000      0.000000  5.047153e+00  2.225426e+00  1.192602e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+    -15.000000     75.000000      0.000000  4.299193e+00  2.838559e+00  2.303930e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000    -75.000000      0.000000 -2.114404e+00 -3.147228e+00 -4.180051e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000    -60.000000      0.000000 -8.264647e-01 -2.821727e+00 -4.816989e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000    -45.000000      0.000000  5.177966e-01 -2.303930e+00 -5.125657e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000    -30.000000      0.000000  1.826771e+00 -1.629125e+00 -5.085021e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000    -15.000000      0.000000  3.011254e+00 -8.432971e-01 -4.697848e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000      0.000000      0.000000  3.990525e+00  0.000000e+00 -3.990525e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000     15.000000      0.000000  4.697848e+00  8.432971e-01 -3.011254e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000     30.000000      0.000000  5.085021e+00  1.629125e+00 -1.826771e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000     45.000000      0.000000  5.125657e+00  2.303930e+00 -5.177966e-01  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000     60.000000      0.000000  4.816989e+00  2.821727e+00  8.264647e-01  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000     75.000000      0.000000  4.180051e+00  3.147228e+00  2.114404e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000    -75.000000      0.000000 -2.303930e+00 -2.838559e+00 -4.299193e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000    -60.000000      0.000000 -1.192602e+00 -2.225426e+00 -5.047153e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000    -45.000000      0.000000  0.000000e+00 -1.460633e+00 -5.451158e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000    -30.000000      0.000000  1.192602e+00 -5.963011e-01 -5.483676e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000    -15.000000      0.000000  2.303930e+00  3.086682e-01 -5.142490e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000      0.000000      0.000000  3.258250e+00  1.192602e+00 -4.450852e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000     15.000000      0.000000  3.990525e+00  1.995262e+00 -3.455896e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000     30.000000      0.000000  4.450852e+00  2.661949e+00 -2.225426e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000     45.000000      0.000000  4.607861e+00  3.147228e+00 -8.432971e-01  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000     60.000000      0.000000  4.450852e+00  3.418028e+00  5.963011e-01  0.000000e+00  0.000000e+00  0.000000e+00  23
+     15.000000     75.000000      0.000000  3.990525e+00  3.455896e+00  1.995262e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000    -75.000000      0.000000 -2.550926e+00 -2.550926e+00 -4.339830e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000    -60.000000      0.000000 -1.669762e+00 -1.669762e+00 -5.125657e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000    -45.000000      0.000000 -6.748056e-01 -6.748056e-01 -5.562180e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000    -30.000000      0.000000  3.661375e-01  3.661375e-01 -5.619649e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000    -15.000000      0.000000  1.382129e+00  1.382129e+00 -5.294149e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000      0.000000      0.000000  2.303930e+00  2.303930e+00 -4.607861e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000     15.000000      0.000000  3.068723e+00  3.068723e+00 -3.607555e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000     30.000000      0.000000  3.624387e+00  3.624387e+00 -2.361400e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000     45.000000      0.000000  3.933055e+00  3.933055e+00 -9.543192e-01  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000     60.000000      0.000000  3.973692e+00  3.973692e+00  5.177966e-01  0.000000e+00  0.000000e+00  0.000000e+00  23
+     30.000000     75.000000      0.000000  3.743529e+00  3.743529e+00  1.954625e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000    -89.999000      0.000000 -3.258180e+00 -3.258250e+00 -3.258319e+00  0.000000e+00  0.000000e+00  0.000000e+00  23
+      0.000000     89.999000      0.000000  3.258319e+00  3.258250e+00  3.258180e+00  0.000000e+00  0.000000e+00  0.000000e+00  23