DOC: Update docs to use consistently x-* and y-* (with hyphen) (#3862)

michaelgrund · seisman · web-flow · commit 490d9c47082d · 2025-06-02T18:46:06.000+08:00
Co-authored-by: Dongdong Tian &lt;seisman.info@gmail.com&gt;
diff --git a/examples/gallery/3d_plots/scatter3d.py b/examples/gallery/3d_plots/scatter3d.py
@@ -92,7 +92,7 @@
     zscale=1.5,
 )
 
-# Shift the plot origin in x direction temporarily and add the colorbar
+# Shift the plot origin in x-direction temporarily and add the colorbar
 with fig.shift_origin(xshift=3.1):
     fig.colorbar()
 
diff --git a/examples/gallery/embellishments/gmt_logo.py b/examples/gallery/embellishments/gmt_logo.py
@@ -12,7 +12,7 @@
 fig.basemap(region=[0, 10, 0, 2], projection="X6c", frame=True)
 
 # Add the GMT logo in the Top Right (TR) corner of the current plot, scaled up to be 3
-# centimeters wide and offset by 0.3 cm in x direction and 0.6 cm in y direction.
+# centimeters wide and offset by 0.3 cm in x-direction and 0.6 cm in y-direction.
 fig.logo(position="jTR+o0.3c/0.6c+w3c")
 
 fig.show()
diff --git a/examples/gallery/embellishments/legend.py b/examples/gallery/embellishments/legend.py
@@ -44,7 +44,7 @@
 
 # Add a legend to the plot; place it within the plot bounding box with both
 # reference ("J") and anchor ("+j") points being the Top Right (TR) corner and an
-# offset of 0.2 centimeters in x and y directions; surround the legend with a box
+# offset of 0.2 centimeters in x- and y-directions; surround the legend with a box
 fig.legend(position="JTR+jTR+o0.2c", box=True)
 
 # -----------------------------------------------------------------------------
diff --git a/examples/gallery/embellishments/scalebar.py b/examples/gallery/embellishments/scalebar.py
@@ -30,7 +30,7 @@
    independent) code. Choose from vertical **T**\(op), **M**\(iddle), or
    **B**\(ottom) and horizontal **L**\(eft), **C**\(entre), or **R**\(ight).
  - offset: **+o**\ *offset* or **+o**\ *xoffset*/\ *yoffset*. Give either a
-   common shift or individual shifts in x (longitude) and y (latitude)
+   common shift or individual shifts in x- (longitude) and y- (latitude)
    directions.
  - height: Use :gmt-term:`MAP_SCALE_HEIGHT` via :func:`pygmt.config`.
  - fancy style: **+f**. Get a scale bar that looks like train tracks.
@@ -77,7 +77,7 @@
 # -----------------------------------------------------------------------------
 # Bottom Right: Add a scale bar valid for a specific location
 # It is placed at BottomRight (j) using MiddleRight as anchor point (+j) with
-# an offset (+o) of 1 centimeter in both x and y directions
+# an offset (+o) of 1 centimeter in both x- and y-directions
 # It applies (+c) at -7° South, add a customized label by appending text to +l
 fig.basemap(map_scale="jBR+jMR+o1c/1c+c-7+w500k+f+u+lvalid at 7° S")
 
diff --git a/examples/gallery/embellishments/timestamp.py b/examples/gallery/embellishments/timestamp.py
@@ -5,7 +5,7 @@
 The :meth:`pygmt.Figure.timestamp` method can draw the GMT timestamp logo on the plot.
 The timestamp will always be shown relative to the Bottom Left (BL) corner of the plot.
 By default, the ``offset`` and ``justify`` parameters are set to ``("-54p", "-54p")``
-(x, y directions) and ``"BL"`` (Bottom Left), respectively.
+(x-, y-directions) and ``"BL"`` (Bottom Left), respectively.
 """
 
 # %%
diff --git a/examples/gallery/histograms/blockm.py b/examples/gallery/histograms/blockm.py
@@ -18,7 +18,7 @@
 
 # Set the region for the plot
 region = [130, 152.5, 32.5, 52.5]
-# Define spacing in x and y direction (150x150 arc-minute blocks)
+# Define spacing in x- and y-direction (150x150 arc-minute blocks)
 spacing = "150m"
 
 fig = pygmt.Figure()
diff --git a/examples/gallery/histograms/scatter_and_histograms.py b/examples/gallery/histograms/scatter_and_histograms.py
@@ -42,7 +42,7 @@
 # level for all circles to deal with overplotting.
 fig.plot(x=x, y=y, style="c0.15c", fill=fill, transparency=50)
 
-# Shift the plot origin in y direction temporarily and add top margin histogram.
+# Shift the plot origin in y-direction temporarily and add top margin histogram.
 with fig.shift_origin(yshift=height + 0.25):
     fig.histogram(
         projection=f"X{width}/3",
@@ -56,7 +56,7 @@
         series=0.2,
     )
 
-# Shift the plot origin in x direction temporarily and add right margin histogram.
+# Shift the plot origin in x-direction temporarily and add right margin histogram.
 with fig.shift_origin(xshift=width + 0.25):
     # Plot the horizontal histogram.
     fig.histogram(
diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py
@@ -38,7 +38,7 @@
 # Add a colorbar for the elevation
 fig.colorbar(
     # Place the colorbar inside the plot (lowercase "j") in the Bottom Right (BR)
-    # corner with an offset ("+o") of 0.7 centimeters and 0.3 centimeters in x or y
+    # 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
@@ -61,7 +61,7 @@
     x=[126, 146],
     y=[42, 40],
     text=["A", "B"],
-    offset="0c/0.2c",  # Move text 0.2 centimeters up (y direction)
+    offset="0c/0.2c",  # Move text 0.2 centimeters up (y-direction)
     font="15p",  # Use a font size of 15 points
 )
 
diff --git a/examples/gallery/images/grdclip.py b/examples/gallery/images/grdclip.py
@@ -28,7 +28,7 @@
 fig.grdimage(grid=grid, cmap="oleron")
 
 # Shift plot origin of the second map by "width of the first map + 0.5 cm"
-# in x direction
+# in x-direction
 fig.shift_origin(xshift="w+0.5c")
 
 # Set all grid points < 0 m to a value of -2000 m.
diff --git a/examples/gallery/images/grdgradient.py b/examples/gallery/images/grdgradient.py
@@ -42,7 +42,7 @@
 
 # --------------- plotting the hillshade map -----------
 
-# Shift plot origin of the second map by 12.5 cm in x direction
+# Shift plot origin of the second map by 12.5 cm in x-direction
 fig.shift_origin(xshift="12.5c")
 
 pygmt.makecpt(cmap="gray", series=[-1.5, 0.3, 0.01])
diff --git a/examples/gallery/images/grdlandmask.py b/examples/gallery/images/grdlandmask.py
@@ -17,7 +17,7 @@
 # Assign a value of 0 for all water masses and a value of 1 for all land
 # masses.
 # Use shoreline data with (l)ow resolution and set the grid spacing to
-# 5 arc-minutes in x and y direction.
+# 5 arc-minutes in x- and y-direction.
 grid = pygmt.grdlandmask(region=region, spacing="5m", maskvalues=[0, 1], resolution="l")
 
 # Plot clipped grid
diff --git a/examples/gallery/lines/decorated_lines.py b/examples/gallery/lines/decorated_lines.py
@@ -47,7 +47,8 @@
     # Line with squares ("s") with a size of 0.7 centimeters in a distance of
     # 1 centimeter
     "~d1c:+ss0.7c+gtan+p1p,black",
-    # Shift symbols using "+n" in x and y directions relative to the main decorated line
+    # Shift symbols using "+n" in x- and y-directions relative to the main decorated
+    # line
     "~d1c:+sd0.5c+gtan+p1p,black+n-0.2c/0.1c",
     # Give the number of equally spaced symbols by using "n" instead of "d"
     "~n6:+sn0.5c+gtan+p1p,black",
diff --git a/examples/gallery/lines/envelope.py b/examples/gallery/lines/envelope.py
@@ -56,7 +56,7 @@
 # Plot the data points on top
 fig.plot(data=df_devi, style="c0.2c", pen="1p,gray30", fill="darkgray")
 
-# Shift plot origin by the figure width ("w") plus 1 centimeter in x direction
+# Shift plot origin by the figure width ("w") plus 1 centimeter in x-direction
 fig.shift_origin(xshift="w+1c")
 
 # -----------------------------------------------------------------------------
diff --git a/examples/gallery/lines/quoted_lines.py b/examples/gallery/lines/quoted_lines.py
@@ -41,7 +41,7 @@
     "qN+1:+ltext",
     # Adjust the justification of the labels via "+j", here Top Center
     "qd1c:+ltext+jTC",
-    # Shift labels using "+n" in x and y directions relative to the main
+    # Shift labels using "+n" in x- and y-directions relative to the main
     # quoted line
     "qd1c:+ltext+n-0.5c/0.1c",
     # Rotate labels via "+a" (counter-clockwise from horizontal)
@@ -54,7 +54,7 @@
     "qd1c:+ltext+p0.5p,blue,dashed",
     # Append "+o" to get a box with rounded edges
     "qd1c:+ltext+p0.5p,blue+o",
-    # Adjust the space between label and box in x and y directions via "+c"
+    # Adjust the space between label and box in x- and y-directions via "+c"
     "qd1c:+ltext+p0.5p,blue+o+c0.1c/0.1c",
     # Give a fill of the box via "+g" together with the desired color
     "qd1c:+ltext+gdodgerblue",
diff --git a/examples/gallery/symbols/basic_symbols.py b/examples/gallery/symbols/basic_symbols.py
@@ -24,7 +24,7 @@
 # upper row
 y = 2
 
-# use a dash in x direction (-) with a size of 0.9 cm,
+# use a dash in x-direction (-) with a size of 0.9 cm,
 # linewidth is set to 2p and the linecolor to "gray40"
 fig.plot(x=1, y=y, style="-0.9c", pen="2p,gray40")
 fig.text(x=1, y=y + 0.6, text="-", font=font)
@@ -101,7 +101,7 @@
 fig.plot(x=6, y=y, style="x0.9c", pen="2p,gray40")
 fig.text(x=6, y=y + 0.6, text="x", font=font)
 
-# use a dash in y direction (y) with a size of 0.9 cm,
+# use a dash in y-direction (y) with a size of 0.9 cm,
 # linewidth is set to 2p and the linecolor to "gray40"
 fig.plot(x=7, y=y, style="y0.9c", pen="2p,gray40")
 fig.text(x=7, y=y + 0.6, text="y", font=font)
diff --git a/examples/gallery/symbols/datetime_inputs.py b/examples/gallery/symbols/datetime_inputs.py
@@ -31,8 +31,8 @@
 
 fig = pygmt.Figure()
 
-# create a basemap with limits of 2010-01-01 to 2020-06-01 on the x axis and
-# 0 to 10 on the y axis
+# create a basemap with limits of 2010-01-01 to 2020-06-01 on the x-axis and
+# 0 to 10 on the y-axis
 fig.basemap(
     projection="X15c/5c",
     region=[datetime.date(2010, 1, 1), datetime.date(2020, 6, 1), 0, 10],
diff --git a/examples/intro/04_table_inputs.py b/examples/intro/04_table_inputs.py
@@ -6,7 +6,7 @@
 
 - A table is a 2-D array with rows and columns. Each column represents a different
   variable (e.g., *x*, *y* and *z*) and each row represents a different record.
-- A grid is a 2-D array of data that is regularly spaced in the x and y directions (or
+- A grid is a 2-D array of data that is regularly spaced in the x- and y-directions (or
   longitude and latitude).
 
 In this tutorial, we'll focus on working with table inputs, and cover grid inputs in a
diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
@@ -21,7 +21,7 @@
 # ``label`` parameter has to be specified to state the desired text for the legend entry
 # (white spaces are supported). Here, we use :meth:`pygmt.Figure.plot`, exemplary. By
 # default, the legend is placed in the Upper Right corner with an offset of 0.1
-# centimeters in both x and y directions, and surrounded by a box with a white fill and
+# centimeters in both x- and y-directions, and surrounded by a box with a white fill and
 # a 1-point thick, black, solid outline. The order of the legend entries (top to bottom)
 # is determine by the plotting order. Optionally, to adjust the legend, append different
 # modifiers to the string passed to ``label``. For a list of available modifiers see
@@ -47,7 +47,7 @@
 # -------------------
 #
 # Use the ``position`` parameter to adjust the position of the legend. Add an offset via
-# **+o** for the x and y directions. Additionally append **+w** to adjust the width
+# **+o** for the x- and y-directions. Additionally append **+w** to adjust the width
 # of the legend. Note, no box is drawn by default if ``position`` is used.
 
 fig = pygmt.Figure()
@@ -58,7 +58,7 @@
 fig.plot(x=[-3, 3], y=[-2, -2], pen="darkred", label="darkred line")
 
 # Set the reference point to the Top Left corner within (lowercase "j") the bounding box
-# of the plot and use offsets of 0.3 and 0.2 centimeters in the x and y directions,
+# of the plot and use offsets of 0.3 and 0.2 centimeters in the x- and y-directions,
 # respectively.
 fig.legend(position="jTL+o0.3c/0.2c")
 
diff --git a/examples/tutorials/basics/text.py b/examples/tutorials/basics/text.py
@@ -60,8 +60,8 @@
 fig.plot(x=0, y=-3, style="s0.2c", fill="darkorange", pen="0.7p,darkgray")
 fig.text(x=0, y=-3, text="my text")
 # Shift the text label relatively to the position given via the x and y parameters
-# by 1 centimeter to the right (positive x direction) and 0.5 centimeters down
-# (negative y direction)
+# by 1 centimeter to the right (positive x-direction) and 0.5 centimeters down
+# (negative y-direction)
 fig.text(x=0, y=-3, text="my text", offset="1c/-0.5c")
 
 fig.shift_origin(xshift="w+0.5c")
@@ -102,7 +102,7 @@
 #
 # * ``fill``: Fills the text box with a color.
 # * ``pen``: Outlines the text box.
-# * ``clearance``: Adds margins in x and y directions between the text and the outline
+# * ``clearance``: Adds margins in x-and y-directions between the text and the outline
 #   of the text box. Can be used to get a text box with rounded edges.
 
 fig = pygmt.Figure()
@@ -116,7 +116,7 @@
 fig.text(x=0, y=1, text="My text", pen="1p,seagreen,solid")
 
 # Add margins between the text and the outline of the text box of 0.1
-# centimeters in x direction and 0.2 centimeters in y direction
+# centimeters in x-direction and 0.2 centimeters in y-direction
 fig.text(x=0, y=-1, text="My text", pen="1p,seagreen,dashed", clearance="0.1c/0.2c")
 
 # Get rounded edges by passing "+tO" to the "clearance" parameter
diff --git a/pygmt/src/grdgradient.py b/pygmt/src/grdgradient.py
@@ -52,7 +52,7 @@ def grdgradient(
         *azim*\ [/*azim2*].
         Azimuthal direction for a directional derivative; *azim* is the
         angle in the x,y plane measured in degrees positive clockwise from
-        north (the +y direction) toward east (the +x direction). The
+        north (the positive y-direction) toward east (the positive x-direction). The
         negative of the directional derivative,
         :math:`-(\frac{{dz}}{{dx}}\sin(\mbox{{azim}}) + \
         \frac{{dz}}{{dy}}\cos(\mbox{{azim}}))`, is found; negation yields
diff --git a/pygmt/src/project.py b/pygmt/src/project.py
@@ -93,8 +93,8 @@ def project(
 
     Flat Earth (Cartesian) coordinate transformations can also be made. Set
     ``flat_earth=True`` and remember that azimuth is clockwise from North (the
-    y axis), NOT the usual cartesian theta, which is counterclockwise from the
-    x axis. azimuth = 90 - theta.
+    y-axis), NOT the usual cartesian theta, which is counterclockwise from the
+    x-axis. azimuth = 90 - theta.
 
     No assumptions are made regarding the units for
     :math:`x, y, r, s, p, q, dist, l_{{min}}, l_{{max}}, w_{{min}}, w_{{max}}`.
diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py
@@ -1,5 +1,5 @@
 """
-shift_origin - Shift plot origin in x and/or y directions.
+shift_origin - Shift plot origin in x- and/or y-directions.
 """
 
 import contextlib
@@ -12,7 +12,7 @@ def shift_origin(
     self, xshift: float | str | None = None, yshift: float | str | None = None
 ):
     r"""
-    Shift the plot origin in x and/or y directions.
+    Shift the plot origin in x- and/or y-directions.
 
     The shifts can be permanent or temporary. If used as a standalone method, the shifts
     are permanent and apply to all subsequent plots. If used as a context manager, the
@@ -33,7 +33,7 @@ def shift_origin(
                 ...  # Other plot commands
                 ...
 
-    The shifts *xshift* and *yshift* in x and y directions are relative to the current
+    The shifts *xshift* and *yshift* in x- and y-directions are relative to the current
     plot origin. The default unit for shifts is centimeters (**c**) but can be changed
     to other units via :gmt-term:`PROJ_LENGTH_UNIT`. Optionally, append the length unit
     (**c** for centimeters, **i** for inches, or **p** for points) to the shifts.
@@ -59,9 +59,9 @@ def shift_origin(
     Parameters
     ----------
     xshift
-        Shift plot origin in x direction.
+        Shift plot origin in x-direction.
     yshift
-        Shift plot origin in y direction.
+        Shift plot origin in y-direction.
 
     Examples
     --------
@@ -71,11 +71,11 @@ def shift_origin(
     >>> import pygmt
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
-    >>> # Shift the plot origin in x direction by 6 cm
+    >>> # Shift the plot origin in x-direction by 6 cm
     >>> fig.shift_origin(xshift=6)
     <contextlib._GeneratorContextManager object at ...>
     >>> fig.basemap(region=[0, 7, 0, 5], projection="X7c/5c", frame=True)
-    >>> # Shift the plot origin in x direction based on the previous plot width.
+    >>> # Shift the plot origin in x-direction based on the previous plot width.
     >>> # Here, the width is 7 cm, and xshift is 8 cm.
     >>> fig.shift_origin(xshift="w+1c")
     <contextlib._GeneratorContextManager object at ...>
@@ -86,14 +86,14 @@ def shift_origin(
 
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
-    >>> # Shift the plot origin in x direction by 6 cm temporarily. The plot origin will
+    >>> # Shift the plot origin in x-direction by 6 cm temporarily. The plot origin will
     >>> # revert back to the original plot origin after the block of code is executed.
     >>> with fig.shift_origin(xshift=6):
     ...     fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
-    >>> # Shift the plot origin in y direction by 6 cm temporarily.
+    >>> # Shift the plot origin in y-direction by 6 cm temporarily.
     >>> with fig.shift_origin(yshift=6):
     ...     fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
-    >>> # Shift the plot origin in x and y directions by 6 cm temporarily.
+    >>> # Shift the plot origin in x- and y-directions by 6 cm temporarily.
     >>> with fig.shift_origin(xshift=6, yshift=6):
     ...     fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
     >>> fig.show()

Original file line number	Diff line number	Diff line change
`@@ -92,7 +92,7 @@`
`92`	`92`	`zscale=1.5,`
`93`	`93`	`)`
`94`	`94`
`95`		`-# Shift the plot origin in x direction temporarily and add the colorbar`
	`95`	`+# Shift the plot origin in x-direction temporarily and add the colorbar`
`96`	`96`	`with fig.shift_origin(xshift=3.1):`
`97`	`97`	`fig.colorbar()`
`98`	`98`