WIP: Add gallery example showing how to create a stem plot

[yvonnefroehlich]

Description of proposed changes

This PR is converted to draft as a high-level method is planned for creating a stem plot

This PR adds a gallery example showing how to create a stem plot in PyGMT:

• Define function to prepare the data
• Document this function
• Add example plot
• Vary the appearance of the stem symbol and stem line, as well as the baseline
• Add comments

Preview: https://pygmt-dev--3052.org.readthedocs.build/en/3052/gallery/lines/stem_plot.html

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[yvonnefroehlich]

/format

[yvonnefroehlich]

@GenericMappingTools/pygmt-maintainers this gallery example should be ready for a first round of review 🙂.

[seisman]

I see that you implement the stem plot using GMT's decorated lines. I'm wondering whether it would be easier to just call plot twice, one for lines and one for symbols.

[yvonnefroehlich]

I see that you implement the stem plot using GMT's decorated lines. I'm wondering whether it would be easier to just call plot twice, one for lines and one for symbols.

You mean something like:

import numpy as np
import pygmt

# -----------------------------------------------------------------------------
# Define function to make data usable for a stem plot in PyGMT
def make_stem_data_from_xy(x, y, base=0):
    x_stem = []
    y_stem = []
    for i_rec in range(len(x)):
        x_temp = x[i_rec]
        y_temp = y[i_rec]
        x_stem.append(x_temp)
        x_stem.append(x_temp)
        x_stem.append(np.nan)
        y_stem.append(0 + base)
        y_stem.append(y_temp + base)
        y_stem.append(np.nan)

    return (x_stem, y_stem)


# -----------------------------------------------------------------------------
# Define sample data
x = np.arange(-np.pi * 4, np.pi * 4, 0.2)
y = np.sin(x * 3)

# Create new Figure instance
fig = pygmt.Figure()

size = 5
fig.basemap(region=[-size, size, -size, size], projection="X10/5c", frame=True)

x_stem, y_stem = make_stem_data_from_xy(x, y)

# Draw base line
fig.plot(x=[x_stem[0], x_stem[-2]],y=np.array([0, 0]), pen="0.5p,black")

# Plot stem lines
fig.plot(x=x_stem, y=y_stem, pen="0.5p,black,solid")

# Plot stem symbols
fig.plot(x=x, y=y, style="c0.1c", pen="1p,steelblue", fill="white", label="baseline at y=0")

fig.legend()

fig.show()

I personally like to use plot only once. In this case, both the line and the symbol are included in the legend entry. When using plot we probably have to use two different "versions" of the data. But on the other hand side, for non-native GMT users decorated lines may be not so intuitive.