Figure.histogram: Migrate the parameter horizontal to the new alias system

[seisman]

This PR migrates the parameter horizontal (-A) to the new alias system.

In matplotlib, plt.hist provides the orientation parameter, which can be "vertical" and "horizontal" (xref: https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html). I wonder if we should use the same parameter name, but it means we need to deprecate horizontal to orientation.

Edit: Personally I prefer horizontal=True which is simpler.

[Copilot]

🟡 Changes recommended

The new horizontal parameter is inserted mid-signature in a way that can break existing positional-argument calls, and the migrated behavior lacks a targeted regression test.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Migrates Figure.histogram’s horizontal (-A) handling from the legacy @use_alias mapping to the newer AliasSystem mechanism, aligning this option with the newer argument-building pathway used across PyGMT.

Changes:

• Remove A="horizontal" from the @use_alias decorator.
• Add an explicit horizontal parameter to the histogram signature and wire it to -A via AliasSystem.
• Document A = horizontal in the $aliases section.

File summaries

File	Description
pygmt/src/histogram.py	Moves horizontal/-A from legacy alias mapping into AliasSystem and exposes it explicitly in the function signature.

Review details

Suppressed comments (1)

pygmt/src/histogram.py:52

• Adding the new horizontal parameter in the middle of the positional-or-keyword signature changes the positional argument ordering (e.g., existing code passing projection positionally would now bind to horizontal). To avoid an unintended breaking API change, consider moving horizontal to the end of the signature (just before **kwargs) so all existing positional arguments keep their meaning.

    pen: str | None = None,
    fill: str | None = None,
    horizontal: bool = False,
    projection: str | None = None,
    region: Sequence[float | str] | str | None = None,
    frame: Frame | Axis | Literal["none"] | str | Sequence[str] | bool = False,
    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
    | bool = False,

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.