Skip to content

WIP: Add gallery example OR tutorial showing the usage of pygmt.grdmask#4525

Draft
yvonnefroehlich wants to merge 26 commits into
mainfrom
add-gallery-grdmask
Draft

WIP: Add gallery example OR tutorial showing the usage of pygmt.grdmask#4525
yvonnefroehlich wants to merge 26 commits into
mainfrom
add-gallery-grdmask

Conversation

@yvonnefroehlich

@yvonnefroehlich yvonnefroehlich commented Apr 9, 2026

Copy link
Copy Markdown
Member

Description of proposed changes

This PR aims to add a gallery example OR a tutorial showing the usage of pygmt.grdmask.

TODO

  • Different input formats: NumPy array, GeoPandas Dataframe, ASCII file
  • Several polygons
  • Circle
  • Geospacial object, e.g., US state
  • inside, outside, edge
  • Data points -> stand alone example ?
  • Coastlines -> pygmt.grdlandmask

Preview: https://pygmt-dev--4525.org.readthedocs.build/en/4525/gallery/images/grdmask.html

Guidelines

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 yvonnefroehlich added this to the 0.19.0 milestone Apr 9, 2026
@yvonnefroehlich yvonnefroehlich self-assigned this Apr 9, 2026
@yvonnefroehlich yvonnefroehlich added the documentation Improvements or additions to documentation label Apr 9, 2026
@yvonnefroehlich yvonnefroehlich marked this pull request as draft April 9, 2026 16:38
@yvonnefroehlich yvonnefroehlich changed the title POC: WIP: Add gallery example OR tutorial showing the usage of pygmt.grdmask WIP: Add gallery example OR tutorial showing the usage of pygmt.grdmask Apr 21, 2026
@seisman seisman removed this from the 0.19.0 milestone May 23, 2026
region = [125, 135, 25, 36]

# Define two closed polygons, here a square and a triangle.
# Use an np.nan to separate the polygons

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Use an np.nan to separate the polygons
# Use a record with np.nan to separate the polygons

Comment on lines +48 to +55
# Create a grid mask based on the two polygons defined above
# Set all grid nodes outside the polygons to NaN
mask_out = pygmt.grdmask(region=region, data=polygon, spacing="30s", outside="NaN")
# Set all grid nodes inside the polygons to NaN
# Set the outside parameter to a value larger 0 to keep the nodes outside unchanged
mask_in = pygmt.grdmask(
region=region, data=polygon, spacing="30s", inside="NaN", outside=1
)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we should explain the default values for inside/outside/edge to better understand the behavior.

fig.grdimage(grid=grid_mask_in, cmap=True)
fig.plot(data=polygon, pen="2p,darkorange")

fig.colorbar(frame=True)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about removing the Figure.colorbar call because it's not the main focus of this example:

Suggested change
fig.colorbar(frame=True)

fig.show()


# %%

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A gallery example usually contains only one example, but this one has three examples. Maybe it fits the tutorial section better?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants