Skip to content

Figure.histogram: Migrate parameter 'stairs' to the new alias system - #4884

Merged
seisman merged 2 commits into
mainfrom
histogram/stairs
Sep 14, 2026
Merged

seisman merged 2 commits into
mainfrom
histogram/stairs

Conversation

@seisman

@seisman seisman commented Sep 8, 2026

Copy link
Copy Markdown
Member

This PR migrates the stairs parameter (option -S) to the new alias system.

Over the past few days, I considered whether we should adopt Matplotlib's design (https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html), which exposes a histtype parameter accepting values "bars", "stepfilled", "step", and "barstacked" (but we already alias histtype to -Z). Matplotlib also provides an example demonstrating these histogram styles at https://matplotlib.org/stable/gallery/statistics/histogram_histtypes.html.

It turns out GMT is more flexible: it can reproduce Matplotlib’s various histogram types via different combinations of pen, fill, and stairs, as illustrated below. Thus, this PR is simply a routine parameter migration.

import numpy as np
import pygmt
from pygmt.params import Axis, Frame

# Generate random elevation data from a normal distribution
rng = np.random.default_rng(seed=100)
mean = 100  # mean of distribution
stddev = 25  # standard deviation of distribution
data = rng.normal(loc=mean, scale=stddev, size=521)

fig = pygmt.Figure()
fig.histogram(data=data, frame=Frame(axes="WSen", title="bars"), series=5, fill="green")
fig.shift_origin(xshift="w+1")
fig.histogram(data=data, frame=Frame(axes="WSen", title="bars"), series=5, fill="green", pen="1p")

fig.shift_origin(xshift="w+1")
fig.histogram(data=data, frame=Frame(axes="WSen", title="step"), series=5, stairs=True, pen="1p")

fig.shift_origin(xshift="w+1")
fig.histogram(data=data, frame=Frame(axes="WSen", title="stepfilled"), series=5, stairs=True, pen="2p", fill="green")

fig.show()
histogram

Related: I feel we should add this image showing different types of histograms that GMT can provide. We already have a tutorial at https://www.pygmt.org/dev/tutorials/advanced/cartesian_histograms.html, which shows several histograms, but only one is shown in the API page (https://www.pygmt.org/dev/api/generated/pygmt.Figure.histogram.html#pygmt.Figure.histogram). Maybe we should add a separate gallery example instead?

@seisman seisman added this to the 0.20.0 milestone Sep 8, 2026
@seisman seisman added maintenance Boring but important stuff for the core devs skip-changelog Skip adding Pull Request to changelog needs review This PR has higher priority and needs review. labels Sep 8, 2026
@seisman seisman added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Sep 13, 2026
@seisman
seisman requested a review from a team September 13, 2026 08:16
@seisman
seisman merged commit 19e882c into main Sep 14, 2026
23 of 25 checks passed
@seisman
seisman deleted the histogram/stairs branch September 14, 2026 02:58
@seisman seisman removed the final review call This PR requires final review and approval from a second reviewer label Sep 14, 2026

@yvonnefroehlich yvonnefroehlich left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

maintenance Boring but important stuff for the core devs skip-changelog Skip adding Pull Request to changelog

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants