DOC/Gallery example "Cross-section along a transect": General improvements (#3623)

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Michael Grund <[email protected]>

Author: 3 people

examples/gallery/images/cross_section.py

@@ -2,13 +2,11 @@
 Cross-section along a transect
 ==============================
 
-:func:`pygmt.project` and :func:`pygmt.grdtrack` can be used to focus on
-a quantity and its variation along a desired survey line.
-In this example, the elevation is extracted from a grid provided via
-:func:`pygmt.datasets.load_earth_relief`.
-The figure consists of two parts, a map of the elevation in the study
-area showing the survey line and a Cartesian plot showing the elevation
-along the survey line.
+:func:`pygmt.project` and :func:`pygmt.grdtrack` can be used to focus on a quantity and
+its variation along a desired survey line. In this example, the elevation is extracted
+from a grid provided via :func:`pygmt.datasets.load_earth_relief`. The figure consists
+of two parts, a map of the elevation in the study area showing the survey line and a
+Cartesian plot showing the elevation along the survey line.
 
 *This example is orientated on an example in the GMT/China documentation*:
 https://docs.gmt-china.org/latest/examples/ex026/
@@ -27,33 +25,24 @@
 # ----------------------------------------------------------------------------
 # Bottom: Map of elevation in study area
 
-# Set up basic map
-fig.basemap(
-    region=region_map,
-    projection="M12c",  # Mercator projection with a width of 12 centimeters
-    frame="af",
-)
+# Set up basic map using a Mercator projection with a width of 12 centimeters
+fig.basemap(region=region_map, projection="M12c", frame="af")
 
-# Download grid for Earth relief with a resolution of 10 arc-minutes and
-# gridline registration [Default]
-grid_map = pygmt.datasets.load_earth_relief(
-    resolution="10m",
-    region=region_map,
-)
+# Download grid for Earth relief with a resolution of 10 arc-minutes and gridline
+# registration [Default]
+grid_map = pygmt.datasets.load_earth_relief(resolution="10m", region=region_map)
 
 # Plot the downloaded grid with color-coding based on the elevation
 fig.grdimage(grid=grid_map, cmap="oleron")
 
 # Add a colorbar for the elevation
 fig.colorbar(
-    # Place the colorbar inside the plot (lower-case "j") in the Bottom
-    # Right (BR) corner with an offset ("+o") of 0.7 centimeters and
-    # 0.3 centimeters in x or y directions, respectively
-    # Move the x label above the horizontal colorbar ("+ml")
+    # Place the colorbar inside the plot (lower-case "j") in the Botton Right (BR)
+    # corner with an offset ("+o") of 0.7 centimeters and 0.3 centimeters in x or y
+    # directions, respectively; move the x label above the horizontal colorbar ("+ml")
     position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml",
-    # Add a box around the colobar with a fill ("+g") in "white" color and
-    # a transparency ("@") of 30 % and with a 0.8-points thick black
-    # outline ("+p")
+    # Add a box around the colobar with a fill ("+g") in "white" color and a
+    # transparency ("@") of 30 % and with a 0.8-points thick, black, outline ("+p")
     box="+gwhite@30+p0.8p,black",
     # Add x and y labels ("+l")
     frame=["x+lElevation", "y+lm"],
@@ -63,7 +52,7 @@
 fig.plot(
     x=[126, 146],  # Longitude in degrees East
     y=[42, 40],  # Latitude in degrees North
-    # Draw a 2-points thick red dashed line for the survey line
+    # Draw a 2-points thick, red, dashed line for the survey line
     pen="2p,red,dashed",
 )
 
@@ -79,16 +68,15 @@
 # ----------------------------------------------------------------------------
 # Top: Elevation along survey line
 
-# Shift plot origin 12.5 centimeters to the top
-fig.shift_origin(yshift="12.5c")
+# Shift plot origin to the top by the height of the map ("+h") plus 1.5 centimeters
+fig.shift_origin(yshift="h+1.5c")
 
 fig.basemap(
     region=[0, 15, -8000, 6000],  # x_min, x_max, y_min, y_max
-    # Cartesian projection with a width of 12 centimeters and
-    # a height of 3 centimeters
+    # Cartesian projection with a width of 12 centimeters and a height of 3 centimeters
     projection="X12c/3c",
-    # Add annotations ("a") and ticks ("f") as well as labels ("+l")
-    # at the west or left and south or bottom sides ("WSrt")
+    # Add annotations ("a") and ticks ("f") as well as labels ("+l") at the west or
+    # left and south or bottom sides ("WSrt")
     frame=["WSrt", "xa2f1+lDistance+u°", "ya4000+lElevation / m"],
 )
 
@@ -101,28 +89,24 @@
     font="10p",  # Use a font size of 10 points
 )
 
-# Generate points along a great circle corresponding to the survey line
-# and store them in a pandas.DataFrame
+# Generate points along a great circle corresponding to the survey line and store them
+# in a pandas.DataFrame
 track_df = pygmt.project(
-    center="126/42",  # Start point of survey line (longitude/latitude)
-    endpoint="146/40",  # End point of survey line (longitude/latitude)
-    generate="0.1",  # Output data in steps of 0.1 degrees
+    center=[126, 42],  # Start point of survey line (longitude, latitude)
+    endpoint=[146, 40],  # End point of survey line (longitude, latitude)
+    generate=0.1,  # Output data in steps of 0.1 degrees
 )
 
-# Extract the elevation at the generated points from the downloaded grid
-# and add it as new column "elevation" to the pandas.DataFrame
-track_df = pygmt.grdtrack(
-    grid=grid_map,
-    points=track_df,
-    newcolname="elevation",
-)
+# Extract the elevation at the generated points from the downloaded grid and add it as
+# new column "elevation" to the pandas.DataFrame
+track_df = pygmt.grdtrack(grid=grid_map, points=track_df, newcolname="elevation")
 
 # Plot water masses
 fig.plot(
     x=[0, 15],
     y=[0, 0],
     fill="lightblue",  # Fill the polygon in "lightblue"
-    # Draw a 0.25-points thick black solid outline
+    # Draw a 0.25-points thick, black, solid outline
     pen="0.25p,black,solid",
     close="+y-8000",  # Force closed polygon
 )
@@ -132,7 +116,7 @@
     x=track_df.p,
     y=track_df.elevation,
     fill="gray",  # Fill the polygon in "gray"
-    # Draw a 1-point thick black solid outline
+    # Draw a 1-point thick, black, solid outline
     pen="1p,black,solid",
     close="+y-8000",  # Force closed polygon
 )