Figure.coast: Plot continents, countries, shorelines, rivers, and borders #4240

Activity

1. seisman

   added this to the 0.1.x milestone on Dec 4, 2025
2. seisman

   added

   feature requestNew feature wantedNew feature wanted

   on Dec 4, 2025
3. seisman

   added this to PyGMT: Wrapping GMT moduleson Dec 4, 2025
4. github-project-automation

   moved this to 0) Wishlist in PyGMT: Wrapping GMT moduleson Dec 4, 2025
5. seisman

   closed this as completedon Dec 4, 2025
6. github-project-automation

   moved this from 0) Wishlist to 4) Gallery|tutorial example in PyGMT: Wrapping GMT moduleson Dec 4, 2025
7. seisman commented on Aug 10, 2026

   

   seisman

   on Aug 10, 2026

   Last edited by seisman

   MemberAuthor

   More actions

   Implementation of the -E Option

   The coast module’s -E option paints or fills country polygons using the DCW dataset, rather than the GSHHG dataset. As a result, many coast options, such as -A, -C, -D, -F, -G, -I, -L, -N, -S, -T, and -W, do not affect -E.

   The -E option is also quite flexible and complex. See the GMT documentation for details. Common examples include:

   • -EJP+p1p+gblue
   • -EJP,CN+p1p+gblue
   • -EJP,CN+p1p+gblue -EAU,NZ+p1p+gred

   1. Current Syntax

   • Figure.coast(dcw="JP+p1p+gblue")
   • Figure.coast(dcw="JP,CN+p1p+gblue")
   • Figure.coast(dcw=["JP,CN+p1p+gblue", "AU,NZ+p1p+gred"])

   This syntax is simple, but not very Pythonic.

   2. Dictionary-Like Syntax

   • Figure.coast(dcw={"code": "JP", "pen": "1p", "fill": "blue"})
   • Figure.coast(dcw={"code": ["JP", "CN"], "pen": "1p", "fill": "blue"})
   • Figure.coast(dcw=[ {"code": ["JP", "CN"], "pen": "1p", "fill": "blue"}, {"code": ["AU", "NZ"], "pen": "1p", "fill": "red"}, ])

   This syntax is more readable, but still somewhat complicated because users need to carefully combine lists and dictionaries. The dict-like syntax also doesn't support auto-completion well.

   3. A Separate Figure.dcw Method

   • Figure.dcw(code="JP", pen="1p", fill="blue")
   • Figure.dcw(code=["JP", "CN"], pen="1p", fill="blue")

   To keep the method simple, users should call Figure.dcw multiple times when applying different pen or fill settings to different country codes.

   I prefer the separate Figure.dcw method for several reasons:

   • Most coast options do not affect DCW painting, so Figure.dcw would only need a small number of parameters.
   • We likely need substantial documentation explaining country, state, and continent codes. A separate method would keep the Figure.coast docstring much shorter.
   • The -E option itself has many advanced modifiers, such as +f for specifying a different DCW file; +l, +L, and +n for listing country codes; and +e, +r, and +R for adjusting the region. Implementing these options Pythonically would require adding several parameters to Figure.coast, whereas adding them to Figure.dcw would be cleaner and easier.

   @GenericMappingTools/pygmt-maintainers What do you think? If OK with a separate Figure.dcw method, I'll open a separate issue for tracking the wrapper and discuss the implementation details there.

   Also see #2646 (comment).
8. seisman

   reopened this on Aug 10, 2026