Add Figure.directional_rose to plot a directional rose on map

[seisman]

Description of proposed changes

This PR adds the Figure.directional_rose method to plot a map directional rose on map. It wraps the basemap -Td/coast -Td options.

• [g|j|J|n|x]<refpoint>[+j<justify>][+o<dx>[/<dy>]]: position
• +w<width>: width
• +f[<level>]: fancy
• +l<w,e,s,n>]: labels

Example

import pygmt
from pygmt.params import Position
fig = pygmt.Figure()
fig.basemap(region=[0, 80, -30, 30], projection="M10c", frame=True)
fig.directional_rose(width="3c")
fig.show()

Preview: https://pygmt-dev--4025.org.readthedocs.build/en/4025/api/generated/pygmt.Figure.directional_rose.html

Addressing #2831. Related to #4010. Related to #4164.

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.

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

[github-actions]

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
added	pygmt/tests/baseline/test_directional_rose.png
added	pygmt/tests/baseline/test_directional_rose_complex.png
added	pygmt/tests/baseline/test_directional_rose_fancy.png

Image diff(s)

Details

Added images

• test_directional_rose.png

• test_directional_rose_complex.png

• test_directional_rose_fancy.png

Modified images

Path	Old	New

Report last updated at commit 8d70181

[michaelgrund]

Looks good!

[seisman]

I think this feature is also ready for review. The key point that we need to reach an agreement on is the default position.

As shown below, GMT defaults to plot directional roses at x0/0, but there are some issues (potential bugs):

• It seems the anchor point is "BL" for a simple rose and "MC" for a fancy rose. So, the behavior is inconsistent.
• The box is not drawn for the simple rose when position is x0/0
• Setting position to jBL looks good, but the box for the simple rose seems to be a square which doesn't fit the simple rose well.

I'll file an upstream issue report later (GenericMappingTools/gmt#8841), but I feel in PyGMT, we should let the default position to jBL (which seems to have offsets automatically).

gmt begin map png
	gmt basemap -R100/110/30/35 -JM10c -Baf
	gmt basemap -Td+w2c -F+pblue
	gmt basemap -Td+w2c+f -F+pred

	gmt basemap -R100/110/30/35 -JM10c -Baf -Xw+2c
	gmt basemap -Tdx0/0+w2c -F+pblue
	gmt basemap -Tdx0/0+w2c+f -F+pred

	gmt basemap -R100/110/30/35 -JM10c -Baf -Xw+2c
	gmt basemap -TdjBL+w2c -F+pblue
	gmt basemap -TdjBL+w2c+f -F+pred
gmt end show

[Copilot]

Pull request overview

This PR adds the Figure.directional_rose method to plot directional roses on maps, wrapping GMT's basemap -Td / coast -Td options. It also deprecates the rose parameter in the basemap method in favor of this new dedicated method.

Changes:

• Adds new Figure.directional_rose method with support for position, width, fancy levels (1-3), custom labels, and background box
• Deprecates the rose parameter in Figure.basemap while maintaining backward compatibility
• Updates existing test to use the new method instead of the deprecated parameter

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pygmt/src/directional_rose.py	New module implementing the directional_rose method with comprehensive parameter support
pygmt/src/basemap.py	Deprecates rose parameter, adds deprecation warning, maintains backward compatibility
pygmt/tests/test_directional_rose.py	Comprehensive test suite covering default, fancy, and complex usage scenarios
pygmt/tests/test_inset.py	Updates test to use new directional_rose method instead of deprecated basemap rose parameter
pygmt/src/init.py	Registers the new directional_rose function
pygmt/figure.py	Adds directional_rose to the Figure class methods
doc/api/index.rst	Adds directional_rose to API documentation index
pygmt/tests/baseline/*.dvc	Baseline test images for visual regression testing

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.