pygmt.grdmask: Create mask grid from polygons or point coverage(required arguments)

[Chuan1937]

pygmt.grdmask: Create mask grid from polygons or point coverage(required arguments)

Preview: https://pygmt-dev--4428.org.readthedocs.build/en/4428/api/generated/pygmt.grdmask.html#pygmt.grdmask

[seisman]

Both GMT and GMT.jl use out_edge_in, but I feel mask_values is readable and more consistent with modules like grdlandmask and select.

What's your plan about syntax like -Nz/-NZ/-Np/-NP?

[Chuan1937]

The plan is to make the mask_values parameter support both lists and strings:
List format: mask_values=[0, 0, 1] (current usage),
String format: mask_values="Nz" / “NZ” / ‘Np’ / “NP” (corresponding to GMT's -Nz/-NZ/-Np/-NP),
What are your thoughts?

[seisman]

Looking at the GMT documentation, it seems the syntax is more complicated than that. The following are also valid: -Nz/1, -Np5, but syntax like mask_values="z/1", or mask_values="p5" are still not Pythonic.

[Chuan1937]

Three new parameters—id_mode, id_start, and out_value—can be added to correspond to -Nz/Z/p/P and their variants, while being mutually exclusive with mask_values.

[seisman]

I'm thinking about outside, edge, inside rather than mask_values.

[seisman]

I see that you've already implemented the outside/edge/inside options. Could you please elaborate on the other related parameters? Just describe what you're planning to do, and there's no need to implement it yet. That way, we can review whether the proposed approach makes sense before moving forward.

[seisman]

use -Nz to set polygon insides to the z-value obtained from the data (either segment header -Zzval, -Lheader or via -aZ=name); use -NZ to consider the polygon boundary as part of the inside. Alternatively, use -Np to use a running number as polygon ID; optionally append start of the sequence [0].

Actually, I don't fully understand the GMT documentation. As I understand it, -Nz and -Np control the value for polygon inside. -Nz sets the inside to be the z-value from the segment header, and -Np sets it to a polygon ID (starting from 0). Then -NZ and -NP have the same meaning but also force edge to be the same as inside. So, maybe we should allow syntax like inside="z" and inside="id".

• outside=1, edge=2, inside=3 -> 1/2/3
• inside="z" -> -Nz
• inside="id" -> -Np
• outside=1, inside="z" -> -Nz/1 [Can we set edge in this case?]
• outside=1, inside="id" -> -Np/1 [Can we set edge in this case?]
• outside=1, inside="z", edge="z" -> -NZ/1
• outside=1, inside="id", edge="id" -> -NP/1
• outside=1, inside="z", edge="id": invalid

[Chuan1937]

search_radius (-S):

search_radius="50k" → -S50k (point coverage mode, 50km search radius)
search_radius="z" → -Sz (read radius from data column 3)
search_radius="1c" → -S1c (1 grid cell)

clobber (-C):

clobber="first" → -Cf (use the first overlapping polygon)
clobber="last" → -Co (use the last overlapping polygon)
clobber="low" → -Cl (use the polygon with the lowest z-value)
clobber="upper" → -Cu (use the polygon with the highest z-value)

straight_line (-A):

straight_line=True → -A (Use straight lines instead of great circles for geographic coordinates)
straight_line="m" → -Am (Meridians first, parallels second)
straight_line="p" → -Ap (Parallels first, meridians second)

[seisman]

Please put the related codes into a private function (e.g., _build_N_option).