Tutorial and Intro for Figure.grdcontour: Adjust line length and parameter order (#3212)

Author: yvonnefroehlich

examples/get_started/02_contour_map.py

@@ -2,12 +2,10 @@
 2. Create a contour map
 =======================
 
-This tutorial page covers the basics of creating a figure of the Earth
-relief, using a remote dataset hosted by GMT, using the method
-:meth:`pygmt.datasets.load_earth_relief`. It will use the
-:meth:`pygmt.Figure.grdimage`, :meth:`pygmt.Figure.grdcontour`,
-:meth:`pygmt.Figure.colorbar`, and :meth:`pygmt.Figure.coast` methods for
-plotting.
+This tutorial page covers the basics of creating a figure of the Earth relief, using a
+remote dataset hosted by GMT, using the method :meth:`pygmt.datasets.load_earth_relief`.
+It will use the :meth:`pygmt.Figure.grdimage`, :meth:`pygmt.Figure.grdcontour`,
+:meth:`pygmt.Figure.colorbar`, and :meth:`pygmt.Figure.coast` methods for plotting.
 """
 
 # %%
@@ -17,13 +15,12 @@
 # Loading the Earth relief dataset
 # --------------------------------
 #
-# The first step is to use :meth:`pygmt.datasets.load_earth_relief`.
-# The ``resolution`` parameter sets the resolution of the remote grid file,
-# which will affect the resolution of the plot made later in the tutorial.
-# The ``registration`` parameter determines the grid registration.
+# The first step is to use :meth:`pygmt.datasets.load_earth_relief`. The ``resolution``
+# parameter sets the resolution of the remote grid file, which will affect the
+# resolution of the plot made later in the tutorial. The ``registration`` parameter
+# determines the grid registration.
 #
-# This grid region covers the islands of Guam and Rota in the western Pacific
-# Ocean.
+# This grid region covers the islands of Guam and Rota in the western Pacific Ocean.
 
 grid = pygmt.datasets.load_earth_relief(
     resolution="30s", region=[144.5, 145.5, 13, 14.5], registration="gridline"
@@ -34,18 +31,16 @@
 # Plotting Earth relief
 # ---------------------
 #
-# To plot Earth relief data, the method :meth:`pygmt.Figure.grdimage` can be
-# used to plot a color-coded figure to display the topography and bathymetry
-# in the grid file. The ``grid`` parameter accepts the input grid, which in
-# this case is the remote file downloaded in the previous step. If the
-# ``region`` parameter is not set, the region boundaries of the input grid are
-# used.
+# To plot Earth relief data, the method :meth:`pygmt.Figure.grdimage` can be used to
+# plot a color-coded figure to display the topography and bathymetry in the grid file.
+# The ``grid`` parameter accepts the input grid, which in this case is the remote file
+# downloaded in the previous step. If the ``region`` parameter is not set, the region
+# boundaries of the input grid are used.
 #
-# The ``cmap`` parameter sets the color palette table (CPT) used for portraying
-# the Earth relief. The :meth:`pygmt.Figure.grdimage` method uses the input
-# grid to relate the Earth relief values to a specific color within the CPT.
-# In this case, the CPT "oleron" is used; a full list of CPTs can be found
-# at :gmt-docs:`reference/cpts.html`.
+# The ``cmap`` parameter sets the color palette table (CPT) used for portraying the
+# Earth relief. The :meth:`pygmt.Figure.grdimage` method uses the input grid to relate
+# the Earth relief values to a specific color within the CPT. In this case, the CPT
+# "oleron" is used; a full list of CPTs can be found at :gmt-docs:`reference/cpts.html`.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="oleron")
@@ -56,17 +51,17 @@
 # Adding a colorbar
 # -----------------
 #
-# To show how the plotted colors relate to the Earth relief, a colorbar can be
-# added using the :meth:`pygmt.Figure.colorbar` method.
+# 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, 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.
 #
-# By default, the CPT for the colorbar is the same as the one set
-# in :meth:`pygmt.Figure.grdimage`.
+# 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="oleron")
@@ -78,18 +73,16 @@
 # Adding contour lines
 # --------------------
 #
-# To add contour lines to the color-coded figure, the
-# :meth:`pygmt.Figure.grdcontour` method is used. The ``frame`` and
-# ``projection`` are already set using :meth:`pygmt.Figure.grdimage` and are
-# not needed again. However, the same input for ``grid`` (in this case, the
-# variable named "grid") must be input again. The ``levels`` parameter sets
-# the spacing between adjacent contour lines (in this case, 500 meters). The
-# ``annotation`` parameter annotates the contour lines corresponding to the
-# given interval (in this case, 1,000 meters) with the related values, here
-# elevation or bathymetry. By default, these contour lines are drawn thicker.
-# Optionally, the appearance (thickness, color, style) of the annotated and
-# the not-annotated contour lines can be adjusted (separately) by specifying
-# the desired ``pen``.
+# To add contour lines to the color-coded figure, the :meth:`pygmt.Figure.grdcontour`
+# method is used. The ``frame`` and ``projection`` are already set using
+# :meth:`pygmt.Figure.grdimage` and are not needed again. However, the same input for
+# ``grid`` (in this case, the variable named "grid") must be input again. The ``levels``
+# parameter sets the spacing between adjacent contour lines (in this case, 500 meters).
+# The ``annotation`` parameter annotates the contour lines corresponding to the given
+# interval (in this case, 1,000 meters) with the related values, here elevation or
+# bathymetry. By default, these contour lines are drawn thicker. Optionally, the
+# appearance (thickness, color, style) of the annotated and the not-annotated contour
+# lines can be adjusted (separately) by specifying the desired ``pen``.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="oleron")
@@ -102,10 +95,9 @@
 # Color in land
 # -------------
 #
-# To make it clear where the islands are located, the
-# :meth:`pygmt.Figure.coast` method can be used to color in the landmasses.
-# The ``land`` is colored in as "lightgray", and the ``shorelines`` parameter
-# draws a border around the islands.
+# To make it clear where the islands are located, the :meth:`pygmt.Figure.coast` method
+# can be used to color in the landmasses. The ``land`` is colored in as "lightgray", and
+# the ``shorelines`` parameter draws a border around the islands.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="oleron")
@@ -119,25 +111,22 @@
 # Additional exercises
 # --------------------
 #
-# This is the end of the second tutorial. Here are some additional exercises
-# for the concepts that were discussed:
+# This is the end of the second tutorial. Here are some additional exercises for the
+# concepts that were discussed:
 #
-# 1. Change the resolution of the grid file to either ``"01m"`` (1 arc-minute,
-#    a lower resolution) or ``"15s"`` (15 arc-seconds, a higher resolution).
-#    Note that higher resolution grids will have larger file sizes. Available
-#    resolutions can be found `here
-#    <https://www.generic-mapping-tools.org/
-#    remote-datasets/earth-relief.html#usage>`_.
+# 1. Change the resolution of the grid file to either ``"01m"`` (1 arc-minute, a lower
+#    resolution) or ``"15s"`` (15 arc-seconds, a higher resolution). Note that higher
+#    resolution grids will have larger file sizes. Available resolutions can be found
+#    at :meth:`pygmt.datasets.load_earth_relief`.
 #
 # 2. Create a contour map of the area around Mt. Rainier. A suggestion for the
 #    ``region`` would be ``[-122, -121, 46.5, 47.5]``. Adjust the
-#    :meth:`pygmt.Figure.grdcontour` and :meth:`pygmt.Figure.colorbar`
-#    settings as needed to make the figure look good.
+#    :meth:`pygmt.Figure.grdcontour` and :meth:`pygmt.Figure.colorbar` settings as
+#    needed to make the figure look good.
 #
-# 3. Create a contour map of São Miguel Island in the Azores; a suggested
-#    ``region`` is ``[-26, -25, 37.5, 38]``. Instead of coloring in ``land``,
-#    set ``water`` to "lightblue" to only display Earth relief information for
-#    the land.
+# 3. Create a contour map of São Miguel Island in the Azores; a suggested ``region`` is
+#    ``[-26, -25, 37.5, 38]``. Instead of coloring in ``land``, set ``water`` to
+#    "lightblue" to only display Earth relief information for the land.
 #
 # 4. Try other CPTs, such as "SCM/fes" or "geo".
 

examples/tutorials/advanced/contour_map.py

@@ -16,13 +16,11 @@
 # Create contour plot
 # -------------------
 #
-# The :meth:`pygmt.Figure.grdcontour` method takes the grid input.
-# It plots annotated contour lines, which are thicker and have the
-# elevation/depth written on them, and unannotated contour lines.
-# In the example below, the default contour line intervals are 500 meters,
-# with an annotated contour line every 1,000 meters.
-# By default, it plots the map with the
-# equidistant cylindrical projection and with no frame.
+# The :meth:`pygmt.Figure.grdcontour` method takes the grid input. It plots annotated
+# contour lines, which are thicker and have the elevation/depth written on them, and
+# unannotated contour lines. In the example below, the default contour line intervals
+# are 500 meters, with an annotated contour line every 1,000 meters. By default, it
+# plots the map with the equidistant cylindrical projection and with no frame.
 
 fig = pygmt.Figure()
 fig.grdcontour(grid=grid)
@@ -33,45 +31,40 @@
 # Contour line settings
 # ---------------------
 #
-# Use the ``annotation`` and ``levels`` parameters to adjust contour line
-# intervals. In the example below, there are contour intervals every 250 meters
-# and annotated contour lines every 1,000 meters.
+# Use the ``annotation`` and ``levels`` parameters to adjust contour line intervals. In
+# the example below, there are contour intervals every 250 meters and annotated contour
+# lines every 1,000 meters.
 
 fig = pygmt.Figure()
-fig.grdcontour(annotation=1000, levels=250, grid=grid)
+fig.grdcontour(grid=grid, annotation=1000, levels=250)
 fig.show()
 
 
 # %%
 # Contour limits
 # --------------
 #
-# The ``limit`` parameter sets the minimum and maximum values for the contour
-# lines. The parameter takes the low and high values, and is either a list (as
-# below) or a string ``limit="-4000/-2000"``.
+# The ``limit`` parameter sets the minimum and maximum values for the contour lines. The
+# parameter takes the low and high values, and is either a list (as below) or a string
+# ``limit="-4000/-2000"``.
 
 fig = pygmt.Figure()
-fig.grdcontour(
-    annotation=1000,
-    levels=250,
-    grid=grid,
-    limit=[-4000, -2000],
-)
+fig.grdcontour(grid=grid, annotation=1000, levels=250, limit=[-4000, -2000])
 fig.show()
 
 
 # %%
 # Map settings
 # ------------
 #
-# The :meth:`pygmt.Figure.grdcontour` method accepts additional parameters,
-# including setting the projection and frame.
+# The :meth:`pygmt.Figure.grdcontour` method accepts additional parameters, including
+# setting the projection and frame.
 
 fig = pygmt.Figure()
 fig.grdcontour(
+    grid=grid,
     annotation=1000,
     levels=250,
-    grid=grid,
     limit=[-4000, -2000],
     projection="M10c",
     frame=True,
@@ -83,27 +76,16 @@
 # Adding a colormap
 # -----------------
 #
-# The :meth:`pygmt.Figure.grdimage` method can be used to add a
-# colormap to the contour map. It must be called prior to
-# :meth:`pygmt.Figure.grdcontour` to keep the contour lines visible on the
-# final map. If the ``projection`` parameter is specified in the
+# The :meth:`pygmt.Figure.grdimage` method can be used to add a colormap to the contour
+# map. It must be called prior to :meth:`pygmt.Figure.grdcontour` to keep the contour
+# lines visible on the final map. If the ``projection`` parameter is specified in the
 # :meth:`pygmt.Figure.grdimage` method, it does not need to be repeated in the
-# :meth:`pygmt.Figure.grdcontour` method. Finally, a colorbar is added using
-# the :meth:`pygmt.Figure.colorbar` method.
+# :meth:`pygmt.Figure.grdcontour` method. Finally, a colorbar is added using the
+# :meth:`pygmt.Figure.colorbar` method.
 
 fig = pygmt.Figure()
-fig.grdimage(
-    grid=grid,
-    cmap="haxby",
-    projection="M10c",
-    frame=True,
-)
-fig.grdcontour(
-    annotation=1000,
-    levels=250,
-    grid=grid,
-    limit=[-4000, -2000],
-)
+fig.grdimage(grid=grid, cmap="haxby", projection="M10c", frame=True)
+fig.grdcontour(grid=grid, annotation=1000, levels=250, limit=[-4000, -2000])
 fig.colorbar(frame=["x+lelevation", "y+lm"])
 fig.show()