Figure.histogram: Let parameter 'cumulative' support Pythonic arguments

[seisman]

Migrate the parameter cumulative to the new alias system.

Previously, cumulative can be either True or "r". This PR lets it support more Pythonic argument, i.e., cumulative="reverse".

For comparison, here is matplotlib's hist method (https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html):

cumulativebool or -1, default: False
If True, then a histogram is computed where each bin gives the counts in that bin plus all bins for smaller values. The last bin gives the total number of datapoints.
If density is also True then the histogram is normalized such that the last bin equals 1.
If cumulative is a number less than 0 (e.g., -1), the direction of accumulation is reversed. In this case, if density is also True, then the histogram is normalized such that the first bin equals 1.

So, matplotlib uses cumulative=-1 for reversed cumulative histogram, but I feel it's not as readable as cumulative="reverse".

Preview: https://pygmt-dev--4881.org.readthedocs.build/en/4881/api/generated/pygmt.Figure.histogram.html#pygmt.Figure.histogram

[Copilot]

🟡 Changes recommended

The new parameter insertion can break positional-call compatibility and the updated behavior needs clearer docs and test coverage.

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

Pull request overview

Updates pygmt.Figure.histogram to migrate the cumulative option onto the new AliasSystem, enabling a more Pythonic long-form argument (cumulative="reverse") that maps to GMT’s reverse cumulative flag.

Changes:

• Add an explicit cumulative parameter to Figure.histogram and wire it into AliasSystem via Q=Alias(..., mapping={"reverse": "r"}).
• Update the docstring alias list and cumulative parameter documentation to reflect the new long-form usage.

File summaries

File	Description
pygmt/src/histogram.py	Adds cumulative as an explicit parameter and maps "reverse" to GMT’s -Qr via the alias system; updates docstring alias/docs accordingly.

Review details

Suppressed comments (2)

pygmt/src/histogram.py:118

• The updated cumulative docstring no longer states how to enable cumulative mode (e.g., passing True) and doesn’t mention that the legacy short-form value "r" is still accepted (via the alias mapping). This can confuse users migrating from the previous behavior.

    cumulative
        Draw a cumulative histogram. Set it to ``"reverse"`` to draw the reverse
        cumulative histogram instead.

pygmt/src/histogram.py:178

• The new long-form mapping for cumulative (including "reverse" -> "r") isn’t covered by tests. Consider adding tests that exercise cumulative=True, cumulative="reverse", and (optionally) the legacy cumulative="r" to prevent regressions in the alias conversion.

        G=Alias(fill, name="fill"),
        Q=Alias(cumulative, name="cumulative", mapping={"reverse": "r"}),
        W=Alias(pen, name="pen"),

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