Figure.colorbar: Update gallery examples to use new label/unit/annot/tick/grid parameters

examples/gallery/3d_plots/3d_bar.py

@@ -58,7 +58,10 @@
     perspective=True,
 )
 fig.colorbar(
-    frame=["xa1000f500+lElevation", "y+lm"],
+    annot=1000,
+    tick=500,
+    label="Elevation",
+    unit="m",
     position=Position("TR", cstype="inside", offset=1.4),
     orientation="vertical",
     length=7,

examples/gallery/3d_plots/grdview_surface.py

@@ -57,6 +57,6 @@ def ackley(x, y):
 )
 
 # Add colorbar for gridded data in the Middle Right corner.
-fig.colorbar(frame="a2f1", position=Position("MR", cstype="outside"))
+fig.colorbar(annot=2, tick=1, position=Position("MR", cstype="outside"))
 
 fig.show()

examples/gallery/basemaps/ternary.py

@@ -43,6 +43,6 @@
 
 # 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"
+    position=Position("BC", cstype="outside", offset=(0, 1.5)), label="Permittivity"
 )
 fig.show()

examples/gallery/embellishments/colorbar.py

@@ -4,11 +4,11 @@
 
 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.
+at :gmt-docs:`reference/cpts.html`. Use the ``label`` and ``unit`` parameters to set the
+labels along the long and short dimensions of the colorbar, respectively. To set the
+annotation and tick intervals, use the ``annot`` and ``tick`` parameters. The placement
+of the colorbar is set by passing a :class:`pygmt.params.Position` object to the
+``position`` parameter.
 """
 
 # %%
@@ -21,22 +21,20 @@
 # ============
 # Create a colorbar designed for seismic tomography - roma
 # Colorbar is placed at Bottom Center (BC) by default if no position is given
-# Add quantity and unit as labels ("+l") to the x and y axes
-# Add annotations ("+a") in steps of 0.5 and ticks ("+f") in steps of 0.1
-fig.colorbar(cmap="SCM/roma", frame=["xa0.5f0.1+lVelocity", "y+lm/s"])
+fig.colorbar(cmap="SCM/roma", annot=0.5, tick=0.1, label="Velocity", unit="m/s")
 
 # ============
 # Create a colorbar showing the scientific rainbow - batlow
 fig.colorbar(
     cmap="SCM/batlow",
-    # A horizontal colorbar positioned at map coordinates (0.3, 8.7), with a
-    # length of 4 cm and a width of 0.5 cm.
+    # A horizontal colorbar positioned at map coordinates (0.3, 8.7).
     position=Position((0.3, 8.7), cstype="mapcoords"),
     length=4,
     width=0.5,
     orientation="horizontal",
     box=True,
-    frame=["x+lTemperature", "y+l°C"],
+    label="Temperature",
+    unit="°C",
     scale=100,
 )
 
@@ -45,15 +43,16 @@
 fig.colorbar(
     cmap="SCM/oleron",
     # 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 plotted vertically as a column of characters.
+    # horizontally and 0 cm vertically from anchor point, with a rectangle for NaN
+    # values. Note that the label 'Elevation' is plotted vertically as a column of
+    # characters.
     position=Position("MR", cstype="outside", offset=(1, 0)),
     length=7,
     width=0.5,
     nan=True,
     label_as_column=True,
-    frame=["x+lElevation", "y+lm"],
+    label="Elevation",
+    unit="m",
     scale=10,
 )
 

examples/gallery/embellishments/colorbars_multiple.py

@@ -29,14 +29,14 @@
         # "R?" means Winkel Tripel projection with map width automatically determined
         # from the subplot width.
         fig.grdimage(grid=grid_globe, projection="R?", region="g", frame="a")
-        fig.colorbar(frame=["a4000f2000", "x+lElevation", "y+lm"])
+        fig.colorbar(annot=4000, tick=2000, label="Elevation", unit="m")
     # Activate the second panel so that the colormap created by the makecpt function is
     # a panel-level CPT
     with fig.set_panel(panel=1):
         pygmt.makecpt(cmap="gmt/globe", series=[-6000, 3000])
         # "M?" means Mercator projection with map width also automatically determined
         # from the subplot width.
         fig.grdimage(grid=grid_subset, projection="M?", region=subset_region, frame="a")
-        fig.colorbar(frame=["a2000f1000", "x+lElevation", "y+lm"])
+        fig.colorbar(annot=2000, tick=1000, label="Elevation", unit="m")
 
 fig.show()

examples/gallery/histograms/blockm.py

@@ -39,7 +39,7 @@
 fig.coast(land="darkgray", transparency=40)
 # Plot original data points
 fig.plot(x=data.longitude, y=data.latitude, style="c0.3c", fill="white", pen="1p,black")
-fig.colorbar(frame="x+lkm")
+fig.colorbar(label="km")
 
 fig.shift_origin(xshift="w+5c")
 
@@ -56,6 +56,6 @@
 )
 fig.coast(land="darkgray", transparency=40)
 fig.plot(x=data.longitude, y=data.latitude, style="c0.3c", fill="white", pen="1p,black")
-fig.colorbar(frame="x+lcount")
+fig.colorbar(label="Count")
 
 fig.show()

examples/gallery/images/cross_section.py

@@ -42,18 +42,15 @@
 # Add a colorbar for the elevation
 fig.colorbar(
     # 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.
+    # of 0.7 centimeters and 0.3 centimeters in x- or y-directions, respectively.
     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.
+    move_text="label",  # move the x-label above the horizontal colorbar.
     box=Box(pen="0.8p,black", fill="white@30"),
-    # Add x- and y-labels ("+l")
-    frame=["x+lElevation", "y+lm"],
+    label="Elevation",
+    unit="m",
 )
 
 # Plot the survey line

examples/gallery/images/grdclip.py

@@ -43,7 +43,8 @@
 )
 fig.grdimage(grid=grid)
 fig.colorbar(
-    frame=["x+lElevation", "y+lm"],
+    label="Elevation",
+    unit="m",
     position=Position("MR", cstype="outside", offset=(0.5, 0)),
     length=8,
 )

examples/gallery/images/grdgradient.py

@@ -42,7 +42,10 @@
     position=Position("ML", cstype="outside", offset=(1.4, 0)),
     length=7,
     width=0.5,
-    frame=["xa1000f500+lElevation", "y+lm"],
+    annot=1000,
+    tick=500,
+    label="Elevation",
+    unit="m",
 )
 
 # --------------- plotting the hillshade map -----------

examples/gallery/images/grdgradient_shading.py

@@ -71,7 +71,9 @@
     length=14,
     width=0.4,
     orientation="horizontal",
-    frame="xa2000f500+lElevation (m)",
+    annot=2000,
+    tick=500,
+    label="Elevation (m)",
 )
 
 fig.show()

examples/gallery/maps/choropleth_map.py

@@ -38,7 +38,7 @@
 
 # Add colorbar legend.
 fig.colorbar(
-    frame="x+lPopulation (millions)",
+    label="Population (millions)",
     position=Position("ML", offset=(2, -2.5)),
     length=5,
     fg_triangle=True,

examples/intro/02_contour_map.py

@@ -54,18 +54,17 @@
 # To show how the plotted colors relate to the Earth relief, a colorbar can be added
 # using the :meth:`pygmt.Figure.colorbar` method.
 #
-# To control the annotation and labels on the colorbar, a list is passed to the
-# ``frame`` parameter. The value beginning with ``"a"`` sets the interval for the
-# annotation on the colorbar, in this case every 1,000 meters. To set the label for an
-# axis on the colorbar, the argument begins with either ``"x+l"`` (x-axis) or ``"y+l"``
-# (y-axis), followed by the intended label.
+# To control the annotation and labels on the colorbar, use the ``annot`` parameter to
+# set the annotation interval (in this case every 1,000 meters), the ``label`` and
+# ``unit``parameters to set the labels along the long and short dimensions of the
+# colorbar, respectively.
 #
 # By default, the CPT for the colorbar is the same as the one set in
 # :meth:`pygmt.Figure.grdimage`.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="SCM/oleron")
-fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
+fig.colorbar(annot=1000, label="Elevation", unit="m")
 fig.show()
 
 
@@ -87,7 +86,7 @@
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="SCM/oleron")
 fig.grdcontour(grid=grid, levels=500, annotation=1000)
-fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
+fig.colorbar(annot=1000, label="Elevation", unit="m")
 fig.show()
 
 
@@ -103,7 +102,7 @@
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="SCM/oleron")
 fig.grdcontour(grid=grid, levels=500, annotation=1000)
 fig.coast(shorelines="2p", land="lightgray")
-fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
+fig.colorbar(annot=1000, label="Elevation", unit="m")
 fig.show()
 
 

examples/tutorials/advanced/3d_perspective_image.py

@@ -93,7 +93,7 @@
     # Set the contour pen thickness to 0.1 points
     contour_pen="0.1p",
 )
-fig.colorbar(perspective=True, frame=["a500", "x+lElevation", "y+lm"])
+fig.colorbar(perspective=True, annot=500, label="Elevation", unit="m")
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 4

examples/tutorials/advanced/contour_map.py

@@ -86,7 +86,7 @@
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, cmap="gmt/haxby", projection="M10c", frame=True)
 fig.grdcontour(grid=grid, annotation=1000, levels=250, limit=[-4000, -2000])
-fig.colorbar(frame=["x+lelevation", "y+lm"])
+fig.colorbar(label="Elevation", unit="m")
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 5

examples/tutorials/advanced/draping_on_3d_surface.py

@@ -69,7 +69,7 @@
 )
 
 # Add colorbar for the crustal age
-fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], nan=True)
+fig.colorbar(label="Seafloor crustal age", unit="Myr", nan=True)
 
 fig.show()
 

examples/tutorials/advanced/earth_relief.py

@@ -69,15 +69,13 @@
 #
 # The :meth:`pygmt.Figure.colorbar` method displays the CPT and the associated z-values
 # of the figure, and by default uses the same CPT set by the ``cmap`` parameter for
-# :meth:`pygmt.Figure.grdimage`. The ``frame`` parameter for
-# :meth:`pygmt.Figure.colorbar` can be used to set the axis intervals and labels. A list
-# is used to pass multiple arguments to ``frame``. In the example below, ``"a2500"``
-# sets the axis interval to 2,500, ``"x+lElevation"`` sets the x-axis label, and
-# ``"y+lm"`` sets the y-axis label.
+# :meth:`pygmt.Figure.grdimage`. The ``annot`` parameter sets the annotation interval,
+# the ``label`` parameter sets the x-axis label, and the ``unit`` parameter sets the
+# y-axis label.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, projection="R12c", cmap="gmt/geo")
-fig.colorbar(frame=["a2500", "x+lElevation", "y+lm"])
+fig.colorbar(annot=2500, label="Elevation", unit="m")
 fig.show()
 
 
@@ -97,7 +95,7 @@
 grid = pygmt.datasets.load_earth_relief(resolution="10m", region=[-14, 30, 35, 60])
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, projection="M15c", frame="a", cmap="gmt/geo")
-fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
+fig.colorbar(annot=1000, label="Elevation", unit="m")
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 5

examples/tutorials/advanced/focal_mechanisms.py

@@ -309,7 +309,7 @@
 
 # Set up colormap and colorbar for hypocentral depth
 pygmt.makecpt(cmap="SCM/lajolla", series=[0, 20])
-fig.colorbar(frame=["x+lhypocentral depth", "y+lkm"])
+fig.colorbar(label="Hypocentral depth", unit="km")
 
 fig.meca(
     spec=aki_multiple,

examples/tutorials/advanced/working_with_panel.py

@@ -135,10 +135,8 @@ def view(central_lon):
         cmap=True,  # Use colormap defined above
         frame="g30",
     )
-    # Add a horizontal colorbar for the elevation
-    # with annotations (a) in steps of 2000 and ticks (f) in steps of 1000
-    # and labels (+l) at the x-axis "Elevation" and y-axis "m" (meters)
-    fig.colorbar(frame=["a2000f1000", "x+lElevation", "y+lm"])
+    # Add a horizontal colorbar for the elevation.
+    fig.colorbar(annot=2000, tick=1000, label="Elevation", unit="m")
     return fig
 
 

examples/tutorials/basics/plot.py

@@ -108,7 +108,7 @@
     style="cc",
     pen="black",
 )
-fig.colorbar(frame="xaf+lDepth (km)")
+fig.colorbar(annot=True, tick=True, label="Depth (km)")
 fig.legend(
     spec=legend,
     position=Position("BR", offset=0.2),