DOC: Update Figure.colorbar to the new syntax in tutorials/examples

doc/techref/justification_codes.md

@@ -25,6 +25,7 @@ tags: [remove-input]
 Script showing the justification codes used in GMT / PyGMT.
 """
 import pygmt
+from pygmt.params import Position
 
 size = 5
 x1 = [-size, 0, size, size, size, 0, -size, -size, 0]
@@ -105,7 +106,14 @@ Script showing justification codes for plot embellishments, e.g., a colorbar.
 fig = pygmt.Figure()
 fig.basemap(projection="X10c/2c", region=[-size, size, -size, size], frame=0)
 
-fig.colorbar(cmap="SCM/buda", frame=0, position="jMC+w10c/2c+h")
+fig.colorbar(
+    cmap="SCM/buda",
+    frame=0,
+    position="MC",
+    length=10,
+    width=2,
+    orientation="horizontal"
+)
 
 for code in codes:
     fig.text(

examples/gallery/3d_plots/grdview_surface.py

@@ -18,6 +18,7 @@
 import numpy as np
 import pygmt
 import xarray as xr
+from pygmt.params import Position
 
 
 # Define an interesting function of two variables, see:
@@ -46,8 +47,7 @@ def ackley(x, y):
 SCALE = 0.5  # in centimeters
 fig.grdview(
     data,
-    # Set annotations and gridlines in steps of five, and
-    # tick marks in steps of one
+    # Set annotations and gridlines in steps of five, and tick marks in steps of one
     frame=["a5f1g5", "za5f1g5"],
     projection=f"x{SCALE}c",
     zscale=f"{SCALE}c",
@@ -57,10 +57,7 @@ def ackley(x, y):
     shading="+a45",
 )
 
-# Add colorbar for gridded data
-fig.colorbar(
-    frame="a2f1",  # Set annotations in steps of two, tick marks in steps of one
-    position="JMR",  # Place colorbar in the Middle Right (MR) corner
-)
+# Add colorbar for gridded data at the Middle Right corner.
+fig.colorbar(frame="a2f1", position=Position("MR", cstype="outside"))
 
 fig.show()

examples/gallery/basemaps/ternary.py

@@ -14,6 +14,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 fig = pygmt.Figure()
 
@@ -40,7 +41,8 @@
     ],
 )
 
-# Add a colorbar indicating the values given in the fourth column of
-# the input dataset
-fig.colorbar(position="JBC+o0c/1.5c", frame="x+lPermittivity")
+# Add a colorbar indicating the values given in the fourth column of the input dataset
+fig.colorbar(
+    position=Position("BC", cstype="outside", offset=(0, 1.5)), frame="x+lPermittivity"
+)
 fig.show()

examples/gallery/embellishments/colorbar.py

@@ -2,30 +2,18 @@
 Colorbar
 ========
 
-The :meth:`pygmt.Figure.colorbar` method creates a color scalebar.
-The colormap is set via the ``cmap`` parameter. A full list of available
-color palette tables can be found at :gmt-docs:`reference/cpts.html`.
-Use the ``frame`` parameter to add labels to the **x** and **y** axes
-of the colorbar by appending **+l** followed by the desired text. To add
-and adjust the annotations (**a**) and ticks (**f**) append the letter
-followed by the desired interval. The placement of the colorbar is set
-via the ``position`` parameter. There are the following options:
-
-- **j/J**: placed inside/outside the plot bounding box using a
-  :doc:`2-character justification code </techref/justification_codes>`, e.g.,
-  ``position="jTR"`` for Top Right.
-- **g**: using map coordinates, e.g. ``position="g170/-45"`` for longitude
-  170° East, latitude 45° South.
-- **x**: using paper coordinates, e.g. ``position="x5c/7c"`` for 5 cm, 7 cm
-  from anchor point.
-- **n**: using normalized (0-1) coordinates, e.g. ``position="n0.4/0.8"``.
-
-Note that the anchor point defaults to Bottom Left (**BL**). Append ``+h`` to
-``position`` to get a horizontal colorbar instead of a vertical one (``+v``).
+The :meth:`pygmt.Figure.colorbar` method creates a color scalebar. The colormap is set
+via the ``cmap`` parameter. A full list of available color palette tables can be found
+at :gmt-docs:`reference/cpts.html`. Use the ``frame`` parameter to add labels to the
+**x** and **y** axes of the colorbar by appending **+l** followed by the desired text.
+To add and adjust the annotations (**a**) and ticks (**f**) append the letter followed
+by the desired interval. The placement of the colorbar is set by passing a
+:class:`pygmt.params.Position` object to the ``position`` parameter.
 """
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 fig = pygmt.Figure()
 fig.basemap(region=[0, 3, 6, 9], projection="x3c", frame=["af", "WSne+tColorbars"])
@@ -41,9 +29,12 @@
 # Create a colorbar showing the scientific rainbow - batlow
 fig.colorbar(
     cmap="SCM/batlow",
-    # Colorbar positioned at map coordinates (g) longitude/latitude 0.3/8.7,
-    # with a length/width (+w) of 4 cm by 0.5 cm, and plotted horizontally (+h)
-    position="g0.3/8.7+w4c/0.5c+h",
+    # A horizontal colorbar positioned at map coordinates (0.3, 8.7), with a
+    # length of 4 cm and width of 0.5 cm.
+    position=Position((0.3, 8.7), cstype="mapcoords"),
+    length=4,
+    width=0.5,
+    orientation="horizontal",
     box=True,
     frame=["x+lTemperature", "y+l°C"],
     scale=100,
@@ -53,13 +44,17 @@
 # Create a colorbar suitable for surface topography - oleron
 fig.colorbar(
     cmap="SCM/oleron",
-    # Colorbar placed outside the plot bounding box (J) at Middle Right (MR),
-    # offset (+o) by 1 cm horizontally and 0 cm vertically from anchor point,
-    # with a length/width (+w) of 7 cm by 0.5 cm and a box for NaN values (+n)
-    position="JMR+o1c/0c+w7c/0.5c+n+mc",
+    # Colorbar placed at Middle Right (MR) outside the plot bounding box, offset by 1 cm
+    # horizontally and 0 cm vertically from anchor point, with a length of 7 cm and
+    # width of 0.5 cm, and a rectangle for NaN values.
     # Note that the label 'Elevation' is moved to the opposite side and plotted
-    # vertically as a column of text using '+mc' in the position parameter
-    # above
+    # vertically as a column of text.
+    position=Position("MR", cstype="outside", offset=(1, 0)),
+    length=7,
+    width=0.5,
+    nan=True,
+    move_text=["annotations", "label"],
+    label_as_column=True,
     frame=["x+lElevation", "y+lm"],
     scale=10,
 )
@@ -76,10 +71,11 @@
 # Plot the colorbar
 fig.colorbar(
     cmap=True,  # Use colormap set up above
-    # Colorbar placed inside the plot bounding box (j) in the Bottom Left (BL) corner,
-    # with an offset (+o) by 0.5 cm horizontally and 0.8 cm vertically from the anchor
-    # point, and plotted horizontally (+h)
-    position="jBL+o0.5c/0.8c+h",
+    # Colorbar placed at the Bottom Left (BL) corner inside the plot bounding box, with
+    # an offset by 0.5 cm horizontally and 0.8 cm vertically from the anchor point, and
+    # plotted horizontally.
+    position=Position("BL", offset=(0.5, 0.8)),
+    orientation="horizontal",
     box=True,
     # Divide colorbar into equal-sized rectangles
     equalsize=0.5,

examples/gallery/images/cross_section.py

@@ -14,7 +14,7 @@
 
 # %%
 import pygmt
-from pygmt.params import Box
+from pygmt.params import Box, Position
 
 # Define region of study area
 # lon_min, lon_max, lat_min, lat_max in degrees East and North
@@ -41,10 +41,14 @@
 
 # Add a colorbar for the elevation
 fig.colorbar(
-    # Place the colorbar inside the plot (lowercase "j") in the Bottom Right (BR)
-    # corner with an offset ("+o") of 0.7 centimeters and 0.3 centimeters in x- or y-
-    # directions, respectively; move the x-label above the horizontal colorbar ("+ml")
-    position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml",
+    # Place the colorbar inside the plot in the Bottom Right (BR) corner with an offset
+    # of 0.7 centimeters and 0.3 centimeters in x- or y-directions, respectively;
+    # move the x-label above the horizontal colorbar.
+    position=Position("BR", offset=(0.7, 0.8)),
+    length=5,
+    width=0.3,
+    orientation="horizontal",
+    move_text="label",
     # Add a box around the colobar, filled in white and a 30 % transparency, with a
     # 0.8-point thick, black, outline.
     box=Box(pen="0.8p,black", fill="white@30"),

examples/gallery/images/grdclip.py

@@ -2,14 +2,15 @@
 Clipping grid values
 ====================
 
-The :func:`pygmt.grdclip` function allows to clip defined ranges of grid
-values. In the example shown below we set all elevation values (grid points)
-smaller than 0 m (in general the bathymetric part of the grid) to a common
-value of -2000 m via the ``below`` parameter.
+The :func:`pygmt.grdclip` function allows to clip defined ranges of grid values. In the
+example shown below we set all elevation values (grid points) smaller than 0 m (in
+general the bathymetric part of the grid) to a common value of -2000 m via the ``below``
+parameter.
 """
 
 # %%
 import pygmt
+from pygmt.params.position import Position
 
 fig = pygmt.Figure()
 
@@ -41,6 +42,10 @@
     frame=["wSne+tclipped grid", "xa5f1", "ya2f1"],
 )
 fig.grdimage(grid=grid)
-fig.colorbar(frame=["x+lElevation", "y+lm"], position="JMR+o0.5c/0c+w8c")
+fig.colorbar(
+    frame=["x+lElevation", "y+lm"],
+    position=Position("MR", cstype="outside", offset=(0.5, 0)),
+    length=8,
+)
 
 fig.show()

examples/gallery/images/grdgradient.py

@@ -13,6 +13,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 # Define region of interest around Yosemite valley
 region = [-119.825, -119.4, 37.6, 37.825]
@@ -37,8 +38,12 @@
     frame=["WSrt+tOriginal Data Elevation Model", "xa0.1", "ya0.1"],
     cmap=True,
 )
-
-fig.colorbar(position="JML+o1.4c/0c+w7c/0.5c", frame=["xa1000f500+lElevation", "y+lm"])
+fig.colorbar(
+    position=Position("ML", cstype="outside", offset=(1.4, 0)),
+    length=7,
+    width=0.5,
+    frame=["xa1000f500+lElevation", "y+lm"],
+)
 
 # --------------- plotting the hillshade map -----------
 

examples/gallery/images/grdgradient_shading.py

@@ -20,6 +20,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 # Load the 3 arc-minutes global relief grid in the target area around Caucasus
 grid = pygmt.datasets.load_earth_relief(resolution="03m", region=[35, 50, 35, 45])
@@ -59,6 +60,12 @@
                 panel=True,
             )
 
-fig.colorbar(position="JBC+w10c/0.25c+h", frame="xa2000f500+lElevation (m)")
+fig.colorbar(
+    position=Position("BC", cstype="outside"),
+    length=10,
+    width=0.25,
+    orientation="horizontal",
+    frame="xa2000f500+lElevation (m)",
+)
 
 fig.show()

examples/gallery/images/grdlandmask.py

@@ -8,6 +8,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 fig = pygmt.Figure()
 
@@ -33,6 +34,6 @@
 pygmt.makecpt(cmap="SCM/batlow", series=(0, 1, 1), color_model="+cwater,land")
 
 fig.grdimage(grid=grid, cmap=True)
-fig.colorbar(position="JMR+o0.5c/0c+w8c")
+fig.colorbar(position=Position("MR", cstype="outside", offset=(0.5, 0)), length=8)
 
 fig.show()

examples/gallery/maps/choropleth_map.py

@@ -16,6 +16,7 @@
 # %%
 import geopandas as gpd
 import pygmt
+from pygmt.params.position import Position
 
 provider = "https://naciscdn.org/naturalearth"
 world = gpd.read_file(f"{provider}/110m/cultural/ne_110m_admin_0_countries.zip")
@@ -36,6 +37,13 @@
 fig.plot(data=africa, pen="0.8p,gray50", fill="+z", cmap=True, aspatial="Z=POP_EST")
 
 # Add colorbar legend.
-fig.colorbar(frame="x+lPopulation (millions)", position="jML+o2c/-2.5c+w5c+ef0.2c+ml")
+fig.colorbar(
+    frame="x+lPopulation (millions)",
+    position=Position("ML", offset=(2, -2.5)),
+    length=5,
+    fg_triangle=True,
+    triangle_height=0.2,
+    move_text="label",
+)
 
 fig.show()

examples/tutorials/advanced/draping_on_3d_surface.py

@@ -70,7 +70,7 @@
 )
 
 # Add colorbar for the crustal age
-fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], position="+n")
+fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], nan=True)
 
 fig.show()
 

examples/tutorials/advanced/grid_equalization.py

@@ -8,6 +8,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 # %%
 # Load sample data
@@ -56,7 +57,12 @@
             histtype=1,
             pen="1p,black",
         )
-        fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True)
+        fig.colorbar(
+            position=Position("MR", cstype="outside", offset=(1.5, 0)),
+            length=3,
+            width=0.3,
+            frame=True,
+        )
 fig.show()
 
 
@@ -125,7 +131,12 @@
             pen="1p,black",
             center=True,
         )
-        fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True)
+        fig.colorbar(
+            position=Position("MR", cstype="outside", offset=(1.5, 0)),
+            length=3,
+            width=0.3,
+            frame=True,
+        )
 fig.show()
 
 
@@ -174,7 +185,12 @@
             histtype=1,
             pen="1p,black",
         )
-        fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True)
+        fig.colorbar(
+            position=Position("MR", cstype="outside", offset=(1.5, 0)),
+            length=3,
+            width=0.3,
+            frame=True,
+        )
 fig.show()
 
 
@@ -239,7 +255,12 @@
             pen="1p,black",
             center=True,
         )
-        fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True)
+        fig.colorbar(
+            position=Position("MR", cstype="outside", offset=(1.5, 0)),
+            length=3,
+            width=0.3,
+            frame=True,
+        )
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 3

pygmt/src/_common.py

@@ -345,7 +345,7 @@ def _parse_position(
         case str() if position in _valid_anchors:  # Anchor code
             position = Position(position, cstype="inside")
         case str():  # Raw GMT command string.
-            if any(v is not None for v in kwdict.values()):
+            if any(v is not None and v is not False for v in kwdict.values()):
                 msg = (
                     "Parameter 'position' is given with a raw GMT command string, and "
                     f"conflicts with parameters {', '.join(repr(c) for c in kwdict)}."