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!

[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.