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

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

Author: 3 people

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()