Migrate basics frames tutorial to use the Axis/Frame class (#4596)

Author: seisman

examples/tutorials/basics/frames.py

@@ -2,114 +2,107 @@
 Frames, ticks, titles, and labels
 =================================
 
-Setting frame, ticks, title, etc., of the plot is handled by the ``frame``
-parameter that most plotting methods of the :class:`pygmt.Figure` class
-contain.
+Setting frame, ticks, titles, and labels is handled by the ``frame`` parameter that
+many plotting methods of the :class:`pygmt.Figure` class accept. This tutorial focuses
+on setting the ``frame`` parameter using the :class:`pygmt.params.Axis` and
+:class:`pygmt.params.Frame` classes.
 """
 
 # %%
 import pygmt
-from pygmt.params import Axis
+from pygmt.params import Axis, Frame
 
 # %%
 # Plot frame
 # ----------
 #
-# By default, PyGMT does not add a frame to your plot. For example, we can plot
-# the coastlines of the world with a Mercator projection:
+# By default, PyGMT does not add a frame to your plot. For example, we can plot the
+# coastlines of the world with a Mercator projection:
 
 fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
+fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M15c")
 fig.show()
 
 # %%
-# To add the default GMT frame style to the plot, use ``frame="f"`` in
-# :meth:`pygmt.Figure.basemap` or another plotting method (which has the
-# ``frame`` parameter, with the exception of :meth:`pygmt.Figure.colorbar`):
+# To add the default GMT frame style to the plot, use ``frame=True`` in
+# :meth:`pygmt.Figure.basemap` or another plotting method that accepts a ``frame``
+# parameter:
 
 fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
-fig.basemap(frame="f")
+fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M15c")
+fig.basemap(frame=True)
 fig.show()
 
 
 # %%
-# Ticks and grid lines
-# --------------------
+# Annotations, tick marks and grid lines
+# --------------------------------------
 #
-# The automatic frame (``frame=True`` or ``frame="af"``) adds the default GMT
-# frame style and automatically determines tick labels from the plot region.
-# In GMT the tick labels are called **a**\ nnotations.
-
-fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
-fig.basemap(frame="af")
-fig.show()
-
-# %%
-# Add automatic grid lines to the plot by passing ``g`` through the ``frame``
-# parameter:
+# The default frame style includes tick labels (called annotations in GMT) and tick
+# marks at intervals determined by GMT, but doesn't include grid lines. To control
+# the presence and intervals of annotations, tick marks, and grid lines, you can use the
+# :class:`pygmt.params.Axis` class. The ``annot``, ``tick``, and ``grid`` attributes of
+# :class:`pygmt.params.Axis` control the presence and intervals of annotations, tick
+# marks, and grid lines, respectively. Setting them to ``True`` adds them at intervals
+# determined by GMT:
 
 fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
-fig.basemap(frame=Axis(annot=True, grid=True))
+fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M15c")
+fig.basemap(frame=Axis(annot=True, tick=True, grid=True))
 fig.show()
 
 # %%
-# To adjust the step widths of annotations, frame, and grid lines we can
-# add the desired step widths after ``a``, ``f``, or ``g``. In the example
-# below, the step widths are set to 30°, 7.5°, and 15°, respectively.
+# To set specific intervals, pass values to ``annot``, ``tick``, and ``grid``. In the
+# example below, the annotation, tick, and gridline intervals are set to 30, 7.5, and
+# 15 degrees, respectively.
 
 fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
-fig.basemap(frame="a30f7.5g15")
+fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M15c")
+fig.basemap(frame=Axis(annot=30, tick=7.5, grid=15))
 fig.show()
 
-
 # %%
 # Title
 # -----
 #
-# The figure title can be set by passing **+t**\ *title* to the ``frame``
-# parameter of :meth:`pygmt.Figure.basemap`. Passing multiple arguments to
-# ``frame`` can be done by using a list, as shown in the example below.
+# The :class:`pygmt.params.Frame` class lets us configure frame-wide settings such as
+# titles. Combine it with an :class:`Axis` object to keep automatic annotations.
 
 fig = pygmt.Figure()
 # region="TT" specifies Trinidad and Tobago using the ISO country code
-fig.coast(shorelines="1/0.5p", region="TT", projection="M25c")
-fig.basemap(frame=["a", "+tTrinidad and Tobago"])
+fig.coast(shorelines="1/0.5p", region="TT", projection="M15c")
+fig.basemap(frame=Frame(title="Trinidad and Tobago", axis=Axis(annot=True)))
 fig.show()
 
 
 # %%
 # Axis labels
 # -----------
 #
-# Axis labels, in GMT simply called labels, can be set by passing
-# **x+l**\ *label* (or starting with **y** if
-# labeling the y-axis) to the ``frame`` parameter of
-# :meth:`pygmt.Figure.basemap`. The map boundaries (or plot axes) are named as
-# West/west/left (**W**, **w**, **l**), South/south/bottom
-# (**S**, **s**, **b**), North/north/top (**N**, **n**, **t**), and
-# East/east/right (**E**, **e**, **r**) sides of a figure. If an uppercase
-# letter (**W**, **S**, **N**, **E**) is passed, the axis is plotted with
-# tick marks and annotations. The lowercase version
-# (**w**, **s**, **n**, **e**) plots the axis only with tick marks.
-# To only plot the axis pass **l**, **b**, **t**, **r**. By default
-# (``frame=True`` or ``frame="af"``), the West and the South axes are
-# plotted with both tick marks and annotations.
+# Axis labels, in GMT simply called labels, can be set through the ``xaxis`` and
+# ``yaxis`` parameters of :class:`Frame`. The map boundaries (or plot axes) are named as
+# West/west/left (**W**, **w**, **l**), South/south/bottom (**S**, **s**, **b**),
+# North/north/top (**N**, **n**, **t**), and East/east/right (**E**, **e**, **r**) sides
+# of a figure. Uppercase letters (**W**, **S**, **N**, **E**) draw axes with annotations
+# and tick marks, lowercase letters (**w**, **s**, **n**, **e**) draw axes with tick
+# marks only, and **l**, **b**, **t**, **r** draw plain axis lines without ticks or
+# annotations. A frame like ``Frame(axes="WS")`` draws annotated west and south axes
+# only.
 #
-# The example below uses a Cartesian projection, as GMT does not allow
-# labels to be set for geographic maps.
+# The example below uses a Cartesian projection, as GMT does not allow labels to be set
+# for geographic maps.
 
 fig = pygmt.Figure()
 fig.basemap(
     region=[0, 10, 0, 20],
     projection="X10c/8c",
-    # Plot axis with tick marks, annotations, and labels on the
-    # West and South axes
+    # Plot axis with tick marks, annotations, and labels on the West and South axes.
     # Plot axis with tick marks on the north and east axes
-    frame=["WSne", "xaf+lx-axis", "yaf+ly-axis"],
+    frame=Frame(
+        axes="WSne",
+        xaxis=Axis(annot=True, tick=True, label="x-axis"),
+        yaxis=Axis(annot=True, tick=True, label="y-axis"),
+    ),
 )
 fig.show()