DOC: Add basic tutorial "Plotting single-parameter symbols"

examples/tutorials/basics/symbols.py

@@ -0,0 +1,94 @@
+"""
+Plotting symbols
+================
+
+The :meth:`pygmt.Figure.plot` method can plot symbols via the ``style``,
+``size``, and ``symbol`` parameters.
+"""
+
+# %%
+import pygmt
+
+# Set up five sample data points as lists for the x and y values
+x = [-4, -2, 0, 2, 4]
+y = [0] * len(x)
+
+
+# %%
+# Use the ``style`` parameter of the :meth:`pygmt.Figure.plot` method to plot all data
+# points with the same symbol and size. Via the ``fill`` parameter the symbols can be
+# filled with a color or pattern, and ``pen`` can add an outline (pass an argument in
+# the form *width*,\ *color*,\ *style*). The defaults are no fill and a 0.25-points
+# thick, black, solid outline.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -2, 2], projection="X10c/4c", frame=True)
+
+# Plot circles (first "c") with a diameter of 0.5 centimeters (second "c")
+fig.plot(x=x, y=y, style="c0.5c", fill="gray", pen="1p,orange")
+
+fig.show()
+
+
+# %%
+# Use the ``size`` parameter to plot the data points with individual sizes.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -2, 2], projection="X10c/4c", frame=True)
+
+fig.plot(
+    x=x,
+    y=y,
+    # Plot circles (first "c") with a diameter in centimeters (second "c")
+    style="cc",
+    # Individual sizes
+    size=[0.5, 0.2, 0.4, 0.6, 0.3],
+    fill="gray",
+    pen="1p,orange",
+)
+
+fig.show()
+
+
+# %%
+# Use the ``symbol`` parameter to plot the data points with individual symbols.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -2, 2], projection="X10c/4c", frame=True)
+
+fig.plot(
+    x=x,
+    y=y,
+    # Constant size of 0.5 centimeters
+    style="0.5c",
+    # Plot a circle, a square, a triangle, a inverse triangle, a diamond
+    symbol=["c", "s", "t", "i", "d"],
+    fill="gray",
+    pen="1p,orange",
+)
+
+fig.show()
+
+
+# %%
+# Use the ``symbol`` and ``size`` parameters together to plot the data points with
+# individual symbols and sizes. ``symbol`` and ``size`` need to have the same length.
+# The unit used by ``size`` is now set via the GMT default parameter
+# ``PROJ_LENGTH_UNIT`` and is by default centimeters. Use :class:`pygmt.config`
+# to change this.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -2, 2], projection="X10c/4c", frame=True)
+
+fig.plot(
+    x=x,
+    y=y,
+    symbol=["c", "s", "t", "i", "d"],
+    size=[0.5, 0.2, 0.4, 0.6, 0.3],
+    fill="gray",
+    pen="1p,orange",
+)
+
+fig.show()
+
+# sphinx_gallery_thumbnail_number = 4