diff --git a/examples/gallery/3d_plots/3d_bar.py b/examples/gallery/3d_plots/3d_bar.py index 70837d40894..d8554162f97 100644 --- a/examples/gallery/3d_plots/3d_bar.py +++ b/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, diff --git a/examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py index 8c1814fc6eb..7279f5e02b0 100644 --- a/examples/gallery/3d_plots/grdview_surface.py +++ b/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() diff --git a/examples/gallery/basemaps/ternary.py b/examples/gallery/basemaps/ternary.py index 91da1586837..3900447cef7 100644 --- a/examples/gallery/basemaps/ternary.py +++ b/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() diff --git a/examples/gallery/embellishments/colorbar.py b/examples/gallery/embellishments/colorbar.py index 4e6c6be3701..7beda96c5e3 100644 --- a/examples/gallery/embellishments/colorbar.py +++ b/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, ) diff --git a/examples/gallery/embellishments/colorbars_multiple.py b/examples/gallery/embellishments/colorbars_multiple.py index 0edd822b8ce..913ff49ee21 100644 --- a/examples/gallery/embellishments/colorbars_multiple.py +++ b/examples/gallery/embellishments/colorbars_multiple.py @@ -29,7 +29,7 @@ # "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): @@ -37,6 +37,6 @@ # "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() diff --git a/examples/gallery/histograms/blockm.py b/examples/gallery/histograms/blockm.py index ba509d6dc0c..73bce35d0ac 100644 --- a/examples/gallery/histograms/blockm.py +++ b/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() diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py index 019c69a1a9b..10033b615c8 100644 --- a/examples/gallery/images/cross_section.py +++ b/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 diff --git a/examples/gallery/images/grdclip.py b/examples/gallery/images/grdclip.py index 522e6e3dba0..17990e6f641 100644 --- a/examples/gallery/images/grdclip.py +++ b/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, ) diff --git a/examples/gallery/images/grdgradient.py b/examples/gallery/images/grdgradient.py index 8fd4976eeb6..86cf9fc8cf8 100644 --- a/examples/gallery/images/grdgradient.py +++ b/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 ----------- diff --git a/examples/gallery/images/grdgradient_shading.py b/examples/gallery/images/grdgradient_shading.py index a2fc6978433..f040c19b49e 100644 --- a/examples/gallery/images/grdgradient_shading.py +++ b/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() diff --git a/examples/gallery/maps/choropleth_map.py b/examples/gallery/maps/choropleth_map.py index 0a43f0629ea..3b22806855b 100644 --- a/examples/gallery/maps/choropleth_map.py +++ b/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, diff --git a/examples/intro/02_contour_map.py b/examples/intro/02_contour_map.py index 3868f1a45fd..0adc63cf6b5 100644 --- a/examples/intro/02_contour_map.py +++ b/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() diff --git a/examples/tutorials/advanced/3d_perspective_image.py b/examples/tutorials/advanced/3d_perspective_image.py index 1f83def5499..aec98b5b9fe 100644 --- a/examples/tutorials/advanced/3d_perspective_image.py +++ b/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 diff --git a/examples/tutorials/advanced/contour_map.py b/examples/tutorials/advanced/contour_map.py index f36739822ef..76b8f515454 100644 --- a/examples/tutorials/advanced/contour_map.py +++ b/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 diff --git a/examples/tutorials/advanced/draping_on_3d_surface.py b/examples/tutorials/advanced/draping_on_3d_surface.py index f0c83765638..8a35d2797a3 100644 --- a/examples/tutorials/advanced/draping_on_3d_surface.py +++ b/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() diff --git a/examples/tutorials/advanced/earth_relief.py b/examples/tutorials/advanced/earth_relief.py index 4038eb6ebb9..1651a185d57 100644 --- a/examples/tutorials/advanced/earth_relief.py +++ b/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 diff --git a/examples/tutorials/advanced/focal_mechanisms.py b/examples/tutorials/advanced/focal_mechanisms.py index d4f76e49d7d..abd6a090c35 100644 --- a/examples/tutorials/advanced/focal_mechanisms.py +++ b/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, diff --git a/examples/tutorials/advanced/working_with_panel.py b/examples/tutorials/advanced/working_with_panel.py index e9365489a94..55271254cd8 100644 --- a/examples/tutorials/advanced/working_with_panel.py +++ b/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 diff --git a/examples/tutorials/basics/plot.py b/examples/tutorials/basics/plot.py index e402376eb71..5ffdc024387 100644 --- a/examples/tutorials/basics/plot.py +++ b/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),