Merge branch 'main' into basemap/box

Author: seisman

examples/gallery/3d_plots/3d_bar.py

@@ -0,0 +1,69 @@
+"""
+3-D bar plot
+============
+
+A 3-D bar plot can be created from any collection of three-dimensional tabular data. The
+data points can lie on a regular grid or be irregularly scattered. A special case is
+creating such a 3-D bar plot based on a grid. This can be done in two steps:
+
+1. Converting the grid into a table via :func:`pygmt.grd2xyz`, with columns "x", "y",
+   and "z" for longitude, latitude, and the quantity displayed by the grid,
+   respectively.
+2. Plotting this table as bars in 3-D using :meth:`pygmt.Figure.plot3d`.
+
+The bars can be outlined, and the fill can be one color or based on a quantity using a
+colormap. For the latter, a fourth column needs to be added containing the values of the
+quantity for the color-coding.
+"""
+
+# %%
+import pygmt
+from pygmt.params import Position
+
+# Define a study area around northern Japan with large elevation changes
+region = [141, 147, 36, 43]
+
+# Download a grid for the Earth relief with a resolution of 10 arc-minutes
+grid = pygmt.datasets.load_earth_relief(resolution="10m", region=region)
+
+# Convert the grid into a pandas DataFrame, with columns for longitude ("x"), latitude
+# ("y") and elevation ("z")
+grd_df = pygmt.grd2xyz(grid=grid)
+zmin = grd_df["z"].min() - 50
+zmax = grd_df["z"].max() + 50
+
+# Add a fourth column "color" for the quantity used for the color-coding of the bars,
+# here we use the elevation ("z")
+grd_df["color"] = grd_df["z"]
+
+# Create a 3-D bar plot with color-coding
+fig = pygmt.Figure()
+
+fig.basemap(
+    region=[*region, zmin, zmax],
+    projection="M10c",
+    zsize="8c",
+    frame=["WSneZ", "xaf", "yag", "za1000f500+lElevation / m"],
+    perspective=(195, 30),
+)
+
+pygmt.makecpt(cmap="SCM/oleron", series=(zmin, zmax))
+fig.plot3d(
+    data=grd_df,
+    # Use "o" to plot bars and give the desired size
+    # The base of the bars is set via "+b"
+    style=f"o0.34c+b{zmin}",
+    cmap=True,
+    pen="0.01p,gray30",
+    perspective=True,
+)
+fig.colorbar(
+    frame=["xa1000f500+lElevation", "y+lm"],
+    position=Position("TR", cstype="inside", offset=1.4),
+    orientation="vertical",
+    length=7,
+    move_text="label",
+    label_as_column=True,
+)
+
+fig.show()

pygmt/src/colorbar.py

@@ -33,6 +33,59 @@ def _alias_option_D(  # noqa: N802, PLR0913
 ):
     """
     Return a list of Alias objects for the -D option.
+
+    Examples
+    --------
+    >>> def parse(**kwargs):
+    ...     return AliasSystem(D=_alias_option_D(**kwargs)).get("D")
+    >>> parse(position=Position("TL", offset=0.2), length=4, width=0.5)
+    'jTL+o0.2+w4/0.5'
+    >>> parse(orientation="horizontal")
+    '+h'
+    >>> parse(orientation="vertical")
+    '+v'
+    >>> parse(reverse=True)
+    '+r'
+    >>> parse(nan=True)
+    '+n'
+    >>> parse(nan=True, nan_position="end")
+    '+N'
+    >>> parse(fg_triangle=True, bg_triangle=True)
+    '+e'
+    >>> parse(fg_triangle=True)
+    '+ef'
+    >>> parse(bg_triangle=True)
+    '+eb'
+    >>> parse(fg_triangle=True, triangle_height=0.4)
+    '+ef0.4'
+    >>> parse(fg_triangle=True, bg_triangle=True, triangle_height=0.3)
+    '+e0.3'
+    >>> parse(move_text="annotations")
+    '+ma'
+    >>> parse(move_text="label")
+    '+ml'
+    >>> parse(move_text="unit")
+    '+mu'
+    >>> parse(move_text=["annotations", "label", "unit"])
+    '+malu'
+    >>> parse(label_as_column=True)
+    '+mc'
+    >>> parse(move_text=["annotations", "label"], label_as_column=True)
+    '+malc'
+    >>> parse(
+    ...     position=Position("BR", offset=(0.1, 0.2)),
+    ...     length=5,
+    ...     width=0.4,
+    ...     orientation="vertical",
+    ...     reverse=True,
+    ...     nan=True,
+    ...     nan_position="start",
+    ...     bg_triangle=True,
+    ...     triangle_height=0.2,
+    ...     move_text=["annotations", "unit"],
+    ...     label_as_column=True,
+    ... )
+    'jBR+o0.1/0.2+w5/0.4+v+r+n+eb0.2+mauc'
     """
     # Build the +e modifier from fg_triangle/bg_triangle/triangle_height
     if fg_triangle and bg_triangle:

pygmt/src/grdproject.py

@@ -120,6 +120,10 @@ def grdproject(  # noqa: PLR0913
         msg = "Parameter 'projection' must be specified."
         raise GMTInvalidInput(msg)
 
+    if kwargs.get("M", unit) is not None and kwargs.get("F", scaling) is not False:
+        msg = "Cannot use both 'unit' and 'scaling'."
+        raise GMTInvalidInput(msg)
+
     aliasdict = AliasSystem(
         C=Alias(center, name="center", sep="/", size=2),
         D=Alias(spacing, name="spacing", sep="/", size=2),

pygmt/tests/test_colorbar.py

@@ -4,10 +4,8 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.alias import AliasSystem
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.params.position import Position
-from pygmt.src.colorbar import _alias_option_D
 
 
 @pytest.mark.benchmark
@@ -37,59 +35,6 @@ def test_colorbar_shading_list():
     return fig
 
 
-def test_colorbar_alias_D():  # noqa: N802
-    """
-    Test the parameters for the -D option.
-    """
-
-    def alias_wrapper(**kwargs):
-        """
-        A wrapper function for testing the parameters of -D option.
-        """
-        return AliasSystem(D=_alias_option_D(**kwargs)).get("D")
-
-    argstr = alias_wrapper(position=Position("TL", offset=0.2), length=4, width=0.5)
-    assert argstr == "jTL+o0.2+w4/0.5"
-
-    assert alias_wrapper(orientation="horizontal") == "+h"
-    assert alias_wrapper(orientation="vertical") == "+v"
-
-    assert alias_wrapper(reverse=True) == "+r"
-
-    assert alias_wrapper(nan=True) == "+n"
-    assert alias_wrapper(nan=True, nan_position="end") == "+N"
-
-    assert alias_wrapper(fg_triangle=True, bg_triangle=True) == "+e"
-    assert alias_wrapper(fg_triangle=True) == "+ef"
-    assert alias_wrapper(bg_triangle=True) == "+eb"
-    assert alias_wrapper(fg_triangle=True, triangle_height=0.4) == "+ef0.4"
-    argstr = alias_wrapper(fg_triangle=True, bg_triangle=True, triangle_height=0.3)
-    assert argstr == "+e0.3"
-
-    assert alias_wrapper(move_text="annotations") == "+ma"
-    assert alias_wrapper(move_text="label") == "+ml"
-    assert alias_wrapper(move_text="unit") == "+mu"
-    assert alias_wrapper(move_text=["annotations", "label", "unit"]) == "+malu"
-    assert alias_wrapper(label_as_column=True) == "+mc"
-    argstr = alias_wrapper(move_text=["annotations", "label"], label_as_column=True)
-    assert argstr == "+malc"
-
-    argstr = alias_wrapper(
-        position=Position("BR", offset=(0.1, 0.2)),
-        length=5,
-        width=0.4,
-        orientation="vertical",
-        reverse=True,
-        nan=True,
-        nan_position="start",
-        bg_triangle=True,
-        triangle_height=0.2,
-        move_text=["annotations", "unit"],
-        label_as_column=True,
-    )
-    assert argstr == "jBR+o0.1/0.2+w5/0.4+v+r+n+eb0.2+mauc"
-
-
 @pytest.mark.mpl_image_compare(filename="test_colorbar.png")
 def test_colorbar_position_deprecated_syntax():
     """

pygmt/tests/test_grdproject.py

@@ -81,6 +81,22 @@ def test_grdproject_no_outgrid(grid, projection, expected_grid):
     xr.testing.assert_allclose(a=result, b=expected_grid)
 
 
+def test_grdproject_unit_scaling(grid):
+    """
+    Test that the input validation to prevent passing both 'unit' and
+    'scaling' is performed.
+    """
+    with pytest.raises(GMTInvalidInput):
+        grdproject(
+            grid=grid,
+            projection="M10c",
+            spacing=3,
+            unit="i",
+            scaling="k",
+            region=[-53, -51, -20, -17],
+        )
+
+
 def test_grdproject_fails(grid):
     """
     Check that grdproject fails correctly.