Specify rectangle's width and height via style parameter in multi-parameter symbols example (#1325)

* Update rectangle in the multi-parameter symbols

* Apply suggestions from code review

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

* Add new syntax for all the multi-parameter symbols

* Split the example into two figures

* Update comments

* Add gallery thumbnail number

* Update sytle

* Apply suggestions from code review

Co-authored-by: Meghan Jones <meghanj@alum.mit.edu>

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
Co-authored-by: Meghan Jones <meghanj@alum.mit.edu>

Author: 5 people

examples/gallery/symbols/multi_parameter_symbols.py

@@ -3,48 +3,87 @@
 -------------------------
 
 The :meth:`pygmt.Figure.plot` method can plot individual multi-parameter
-symbols by passing the corresponding shortcuts listed below to the ``style``
-parameter. Additionally, we must define the required parameters in a 2d list or
-numpy array (``[[parameters]]`` for a single symbol or
-``[[parameters_1],[parameters_2],[parameters_i]]`` for several ones) or use an
-appropriately formatted input file and pass it to ``data``.
-
-The following symbols are available:
-
-- **e**: ellipse, ``[[lon, lat, direction, major_axis, minor_axis]]``
-- **j**: rotated rectangle, ``[[lon, lat, direction, width, height]]``
-- **r**: rectangle, ``[[lon, lat, width, height]]``
-- **R**: rounded rectangle, ``[[lon, lat, width, height, radius]]``
-- **w**: pie wedge, ``[[lon, lat, radius, startdir, stopdir]]``, the last two
-  arguments are directions given in degrees counter-clockwise from horizontal
-
-Upper-case versions **E**, **J**, and **W** are similar to **e**, **j** and
-**w** but expect geographic azimuths and distances.
+symbols by passing the corresponding shortcuts (**e**, **j**, **r**, **R**,
+**w**) to the ``style`` parameter:
+
+- **e**: ellipse
+- **j**: rotated rectangle
+- **r**: rectangle
+- **R**: rounded rectangle
+- **w**: pie wedge
+
 """
 
+# sphinx_gallery_thumbnail_number = 2
+
 import pygmt
 
+########################################################################################
+# We can plot multi-parameter symbols using the same symbol style. We need to
+# define locations (lon, lat) via the ``x`` and ``y`` parameters (scalar for
+# a single symbol or 1d list for several ones) and two or three symbol
+# parameters after those shortcuts via the ``style`` parameter.
+#
+# The multi-parameter symbols in the ``style`` parameter are defined as:
+#
+# - **e**: ellipse, ``direction/major_axis/minor_axis``
+# - **j**: rotated rectangle, ``direction/width/height``
+# - **r**: rectangle, ``width/height``
+# - **R**: rounded rectangle, ``width/height/radius``
+# - **w**: pie wedge, ``radius/startdir/stopdir``, the last two arguments are
+#   directions given in degrees counter-clockwise from horizontal
+#
+# Upper-case versions **E**, **J**, and **W** are similar to **e**, **j** and
+# **w** but expect geographic azimuths and distances.
+
 fig = pygmt.Figure()
 fig.basemap(region=[0, 6, 0, 2], projection="x3c", frame=True)
 
-# ELLIPSE
-data = [[0.5, 1, 45, 3, 1]]
-fig.plot(data=data, style="e", color="orange", pen="2p,black")
+# Ellipse
+fig.plot(x=0.5, y=1, style="e45/3/1", color="orange", pen="2p,black")
+# Rotated rectangle
+fig.plot(x=1.5, y=1, style="j120/5/0.5", color="red3", pen="2p,black")
+# Rectangle
+fig.plot(x=3, y=1, style="r4/1.5", color="dodgerblue", pen="2p,black")
+# Rounded rectangle
+fig.plot(x=4.5, y=1, style="R1.25/4/0.5", color="seagreen", pen="2p,black")
+# Pie wedge
+fig.plot(x=5.5, y=1, style="w2.5/45/330", color="lightgray", pen="2p,black")
 
-# ROTATED RECTANGLE
-data = [[1.5, 1, 120, 5, 0.5]]
-fig.plot(data=data, style="j", color="red3", pen="2p,black")
+fig.show()
 
-# RECTANGLE
-data = [[3, 1, 4, 1.5]]
-fig.plot(data=data, style="r", color="dodgerblue", pen="2p,black")
+########################################################################################
+# We can also plot symbols with varying parameters via defining those values in
+# a 2d list or numpy array (``[[parameters]]`` for a single symbol or
+# ``[[parameters_1],[parameters_2],[parameters_i]]`` for several ones) or using
+# an appropriately formatted input file and passing it to ``data``.
+#
+# The symbol parameters in the 2d list or numpy array are defined as:
+#
+# - **e**: ellipse, ``[[lon, lat, direction, major_axis, minor_axis]]``
+# - **j**: rotated rectangle, ``[[lon, lat, direction, width, height]]``
+# - **r**: rectangle, ``[[lon, lat, width, height]]``
+# - **R**: rounded rectangle, ``[[lon, lat, width, height, radius]]``
+# - **w**: pie wedge, ``[[lon, lat, radius, startdir, stopdir]]``, the last two
+#   arguments are directions given in degrees counter-clockwise from horizontal
 
-# ROUNDED RECTANGLE
-data = [[4.5, 1, 1.25, 4, 0.5]]
-fig.plot(data=data, style="R", color="seagreen", pen="2p,black")
+fig = pygmt.Figure()
+fig.basemap(region=[0, 6, 0, 4], projection="x3c", frame=["xa1f0.2", "ya0.5f0.1"])
 
-# PIE WEDGE
-data = [[5.5, 1, 2.5, 45, 330]]
+# Ellipse
+data = [[0.5, 1, 45, 3, 1], [0.5, 3, 135, 2, 1]]
+fig.plot(data=data, style="e", color="orange", pen="2p,black")
+# Rotated rectangle
+data = [[1.5, 1, 120, 5, 0.5], [1.5, 3, 50, 3, 0.5]]
+fig.plot(data=data, style="j", color="red3", pen="2p,black")
+# Rectangle
+data = [[3, 1, 4, 1.5], [3, 3, 3, 1.5]]
+fig.plot(data=data, style="r", color="dodgerblue", pen="2p,black")
+# Rounded rectangle
+data = [[4.5, 1, 1.25, 4, 0.5], [4.5, 3, 1.25, 2.0, 0.2]]
+fig.plot(data=data, style="R", color="seagreen", pen="2p,black")
+# Pie wedge
+data = [[5.5, 1, 2.5, 45, 330], [5.5, 3, 1.5, 60, 300]]
 fig.plot(data=data, style="w", color="lightgray", pen="2p,black")
 
 fig.show()