pygmt.grdfilter: Add parameters filter/width/highpass to set the filter [Part 1]

[seisman]

This PR is a subset of PR #4378, aiming to implement a Pythonic interface for the -F option of the grdfilter module.

The full syntax of the -F option is (https://docs.generic-mapping-tools.org/dev/grdfilter.html#f):

-Fxwidth[/width2][+c|+h|+l|+qquantile|+u]

GMT supports 12 different types of filters, which can be specified by x. For most filters, the syntax is very simple (e.g., -Fg600). Some filters can accept more modifiers. For example, histogram filter accepts +c/+l/+u; median filter accepts +q; Maximum likelihood probability filter accepts +l/+u; and all filters accept +h (for highpass). For custom and operator filters, width is actually a weight file. As a result, this option is complicated to implement.

PR #4378 tries to alias the -F option to multiple parameters filter_type/filter_width/highpass/hist_bin_width/median_quantile/hist_center_bins/mode_extreme. As you can see, that PR is already very big and there are still many edge cases to be covered. I feel that PR will take a very long time to finish and will definitely delay the submission of the paper. Instead, I'm opening this PR to implement a subset of the -F option, which should cover most (80%, I guess) use cases of the -Foption. A more feature-complete version can be added after the paper submission.

Previously, the -F option is aliased to a single parameter filter. In this PR, three new parameters are added:

• filter_type: specify the filter type
• filter_width: specify the filter width
• highpass: for the +h modifier

Then, in our paper, filter="g600" would be filter_type="gaussian", filter_width=600.

We still need to discuss the parameter names:

• filter is a built-in function in Python, so the old alias filter is not a good name.
• filter_type/filter_width are good, but the prefix filter_ is not necessary as the method name is grdfilter (and da.gmt.filter in the GMT accessor). But type is also a built-in function in Python.

I feel we have some choices:

1. filter_type/filter_width
2. filter_type/width
3. filter/width
4. type/width

I'm a little inclined to filter/width. What do you think @GenericMappingTools/pygmt-maintainers?

Edit: I've renamed the parameters to filter/width.

Preview: https://pygmt-dev--4401.org.readthedocs.build/en/4401/api/generated/pygmt.grdfilter.html

[seisman]

These long names come from https://github.com/GenericMappingTools/gmt/blob/a1d6cdfca838326e324b809a8e5ace6a61e7f8c6/src/longopt/grdfilter_inc.h#L29-L32.

[Copilot]

Pull request overview

This PR updates pygmt.grdfilter to provide a more Pythonic interface for GMT’s -F option by splitting the filter specification into separate parameters (filter, width, and highpass), while updating tests and documentation accordingly.

Changes:

• Add _alias_option_F helper and new grdfilter parameters filter, width, and highpass to build the -F argument.
• Update grdfilter docstring to describe the new parameterization and show updated examples.
• Update test_grdfilter.py to use filter="gaussian", width=600, and add new required/compatibility checks.

Reviewed changes

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

File	Description
pygmt/src/grdfilter.py	Introduces filter/width/highpass interface and -F alias-building helper; updates docs/examples.
pygmt/tests/test_grdfilter.py	Migrates tests to the new interface and adds validation tests for required args and mixed syntax.

---

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