Specify rectangle's width and height via style parameter in multi-parameter symbols example

[core-man]

Description of proposed changes

GMT 6.2 allows specifying rectangle's width and height via style parameter in GenericMappingTools/gmt#4164.
This PR adds this new feature in the example of multi-parameter symbols (Originally posted in #392 (comment)).

See GMT Documentation: -S

Fixes #392

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 adding new functionality, add an example to docstrings or tutorials.

Slash Commands

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

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[weiji14]

Just one more suggestion, otherwise looks good to me!

[michaelgrund]

Looks good to me!

[seisman]

#392 (comment)

Please note that we already have an example for rectangles (pygmt.org/latest/gallery/symbols/multi_parameter_symbols.html), but in this example we read the "sizes" from the input file, rather than in the style parameter.

I feel we can simply update that example, rather than adding a new gallery example.

Sorry, I feel the changes may cause more confusion for users.

For rectangle (-Sr), there are two different ways to pass the data. Why there is only one way for -Se?

[weiji14]

#392 (comment)

Please note that we already have an example for rectangles (pygmt.org/latest/gallery/symbols/multi_parameter_symbols.html), but in this example we read the "sizes" from the input file, rather than in the style parameter.
I feel we can simply update that example, rather than adding a new gallery example.

Sorry, I feel the changes may cause more confusion for users.

For rectangle (-Sr), there are two different ways to pass the data. Why there is only one way for -Se?

Do you mean modifying the 5 examples to include the two methods of specifying the shapes? I.e. have ellipse (e), rotated rectangle (j), rectangle (r), rounded rectangle (R) and pie wedge (w) all use two methods?

Img ref: https://docs.generic-mapping-tools.org/6.2/plot.html#id2

[core-man]

Do you mean modifying the 5 examples to include the two methods of specifying the shapes? I.e. have ellipse (e), rotated rectangle (j), rectangle (r), rounded rectangle (R) and pie wedge (w) all use two methods?

Sounds good~ The new styles are added for all the multi-parameter symbols in c45d5ea.

[seisman]

Do you mean modifying the 5 examples to include the two methods of specifying the shapes? I.e. have ellipse (e), rotated rectangle (j), rectangle (r), rounded rectangle (R) and pie wedge (w) all use two methods?

Sounds good~ The new styles are added for all the multi-parameter symbols in c45d5ea.

Looks good. The docstrings should also be updated. Now the docstrings only talk about how to pass the 2D array data to plotting modules.

[core-man]

Looks good. The docstrings should also be updated. Now the docstrings only talk about how to pass the 2D array data to plotting modules.

also done in c45d5ea.

[seisman]

I feel that the example description is very confusing, especially the meaning of "required parameters".

Shall we split the example into two figures (two figures on the same page)?

The first figure uses x=0.5, y=1.5, style="e45/3/1". This method is similar to any other simple symbols (e.g., style="c0.2c", and can plot multiple data points using the same symbol parameters.

The second figure uses [[0.5, 0.5, 45, 3, 1]]. It's more complicated but allows different symbol parameters.

[weiji14]

I feel that the example description is very confusing, especially the meaning of "required parameters".

Shall we split the example into two figures (two figures on the same page)?

The first figure uses x=0.5, y=1.5, style="e45/3/1". This method is similar to any other simple symbols (e.g., style="c0.2c", and can plot multiple data points using the same symbol parameters.

Do you mean using subplots? Or something else.

The second figure uses [[0.5, 0.5, 45, 3, 1]]. It's more complicated but allows different symbol parameters.

Slightly off topic, but wanted to cross-reference #1132, as using data = [[0.5, 0.5, 45, 3, 1]] may be unintuitive to some people.

[seisman]

Do you mean using subplots? Or something else.

I don't want to complicate the example using subplots. I mean two separate figures on one page, similar to our tutorials, although only one figure will be shown as the gallery thumbnail.

Here is the example in my mind (more docstrings need to be added):

# simple way to plot multiple points using the same symbol style.
# x and y can be scalar or 1D lists.
import pygmt

fig = pygmt.Figure()
fig.basemap(region=[0, 6, 0, 2], projection="x3c", frame=True)
fig.plot(x=0.5, y=1, style="e45/3/1", color="orange", pen="2p,black")
fig.plot(x=1.5, y=1, style="j120/5/0.5", color="red3", pen="2p,black")
fig.plot(x=3, y=1, style="r4/1.5", color="dodgerblue", pen="2p,black")
fig.plot(x=4.5, y=1, style="R1.25/4/0.5", color="seagreen", pen="2p,black")
fig.plot(x=5.5, y=1, style="w2.5/45/330", color="lightgray", pen="2p,black")
fig.show()


# the 2nd way is more flexible.
# you can pass 2D arrays to `data` parameter to plot symbols with varying symbol parameters.
fig = pygmt.Figure()
fig.basemap(region=[0, 6, 0, 4], projection="x3c", frame=True)

data = [[0.5, 1, 45, 3, 1], [0.5, 3, 135, 2, 1]]
fig.plot(data=data, style="e", color="orange", pen="2p,black")
data = [[1.5, 1, 120, 5, 0.5], [1.5, 3, 50, 3, 2]]
fig.plot(data=data, style="j", color="red3", pen="2p,black")
data = [[3, 1, 4, 1.5], [3, 3, 3, 1.5]]
fig.plot(data=data, style="r", color="dodgerblue", pen="2p,black")
data = [[4.5, 1, 1.25, 4, 0.5], [4.5, 3, 2.0, 3.0, 0.2]]
fig.plot(data=data, style="R", color="seagreen", pen="2p,black")
data = [[5.5, 1, 2.5, 45, 330], [5.5, 3, 1.5, 30, 150]]
fig.plot(data=data, style="w", color="lightgray", pen="2p,black")
fig.show()

Here are the two images:

[core-man]

Good. We could just plot them in one figure instead of two. A quick revision based on @seisman's demo.

import pygmt

fig = pygmt.Figure()
fig.basemap(region=[0, 6, 0, 7], projection="x3c", frame=True)

# a simple way to plot multiple points using the same symbol style.
# x and y can be scalar or 1D lists.
fig.plot(x=0.5, y=6, style="e45/3/1", color="orange", pen="2p,black")
fig.plot(x=1.5, y=6, style="j120/5/0.5", color="red3", pen="2p,black")
fig.plot(x=3, y=6, style="r4/1.5", color="dodgerblue", pen="2p,black")
fig.plot(x=4.5, y=6, style="R1.25/4/0.5", color="seagreen", pen="2p,black")
fig.plot(x=5.5, y=6, style="w2.5/45/330", color="lightgray", pen="2p,black")

# the 2nd way is more flexible.
# you can pass 2D arrays to `data` parameter to plot symbols with varying symbol parameters.
data = [[0.5, 1, 45, 3, 1], [0.5, 3, 135, 2, 1]]
fig.plot(data=data, style="e", color="orange", pen="2p,black")
data = [[1.5, 1, 120, 5, 0.5], [1.5, 3, 50, 3, 2]]
fig.plot(data=data, style="j", color="red3", pen="2p,black")
data = [[3, 1, 4, 1.5], [3, 3, 3, 1.5]]
fig.plot(data=data, style="r", color="dodgerblue", pen="2p,black")
data = [[4.5, 1, 1.25, 4, 0.5], [4.5, 3, 2.0, 3.0, 0.2]]
fig.plot(data=data, style="R", color="seagreen", pen="2p,black")
data = [[5.5, 1, 2.5, 45, 330], [5.5, 3, 1.5, 30, 150]]
fig.plot(data=data, style="w", color="lightgray", pen="2p,black")

fig.show()

[weiji14]

I kinda prefer @seisman's two figure plot so that the gallery thumbnail looks nice and small. Assuming that only the first figure will show up?

[seisman]

Assuming that only the first figure will show up?

Only one figure will be shown as thumbnail, but we can control which one to show by setting sphinx_gallery_thumbnail_number to 1 or 2.

[core-man]

I kinda prefer @seisman's two figure plot so that the gallery thumbnail looks nice and small. Assuming that only the first figure will show up?

• Codes updated in 2f7db26 based on seisman's style
• Comments updated in fcea6c5

Assuming that only the first figure will show up?

Only one figure will be shown as thumbnail, but we can control which one to show by setting sphinx_gallery_thumbnail_number to 1 or 2.

Yes, the first figure will show up.

23e97cb set sphinx_gallery_thumbnail_number=2, but we can decide if we want it.

[seisman]

What I expect to see is:

A paragraph about passing parameters to the style parameter.

The first figure.

A paragraph about passing numpy arrays to the data parameter to plot symbols with varying parameters.

The 2nd figure.

[core-man]

What I expect to see is:

A paragraph about passing parameters to the style parameter.
The first figure.
A paragraph about passing numpy arrays to the data parameter to plot symbols with varying parameters.
The 2nd figure.

Updated in 739de0d, but it looks a little longer like a tutorial.

[seisman]

Looks good to me.

[maxrjones]

Great work, everyone! We can leave this open for a few more hours in case there are any comments on the latest iteration, but if not then should merge by ~2300 UTC so it will be included in v0.4.0.