Figure.histogram: Improved syntax for filling bars by position/value

[seisman]

In histogram, bars can be filled by a constant color/pattern, or by the bin position or value (count, frequency). This is achieved by the -C option, with a syntax like -C<cmap>+b.

This PR implements a Pythonic syntax for such features by extending the existing parameter fill (alias of -G). In addition to color or pattern, now fill can accept two special values: "position" and "value".

GMT CLI and PyGMT comparison

Here is a comparison:

GMT CLI	PyGMT	Notes
-Gred	fill="red"	Fill by a constant color
-Gp5	fill=Pattern(5)	Fill by a pattern
-C	fill="position"	Fill based on the current CPT and the mid-coordinate of each bar
-Ctest.cpt	fill="position", cmap="test.cpt"	Same as above but use test.cpt
-C+b	fill="value"	Fill based on the current CPT and the bin value (count or frequency, i.e., the bin height)
-Ctest.cpt+b	fill="value", cmap="test.cpt"	Same as above but use test.cpt

Examples

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

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="Fill by color"), series=10, fill="green")

fig.shift_origin(xshift="w+1")
fig.histogram(data=data, frame=Frame(axes="WSen", title="Fill by pattern"), series=10, fill=Pattern(10, dpi=50))

fig.shift_origin(xshift="w+1")
pygmt.makecpt(cmap="turbo", series=(0, 200, 25))
fig.histogram(data=data, frame=Frame(axes="WSen", title="Fill by position"), series=10, pen="1p", fill="position")
fig.colorbar()

fig.shift_origin(xshift="w+4")
pygmt.makecpt(cmap="turbo", series=(0, 100, 25))
fig.histogram(data=data, frame=Frame(axes="WSen", title="Fill by value"), series=10, pen="1p", fill="value")
fig.colorbar()

fig.show()

Alternative implementation

An alternative implementation is to keep fill unchanged, but alias -C to two separate parameters, cmap and fill_by_value (or any other names). The cons are:

• User may be confused by the two similar parameters fill and fill_by_value
• -G can't be used with -C, so we need to deal with conflicts between fill and cmap/fill_by_value carefully

Address #4251

[Copilot]

🟡 Changes recommended

The updated fill docstring currently contradicts the implemented/tested behavior for CPT-based fills and should be corrected before approval.

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

Pull request overview

This PR updates Figure.histogram to support a more Pythonic way to request CPT-based bar filling by extending the existing fill parameter to accept special values ("position" and "value"), while keeping the legacy cmap (-C) syntax working.

Changes:

• Extend histogram(fill=...) to accept "position"/"value" and translate them into the appropriate -C / -C+b CLI behavior.
• Add image-based regression tests for the new fill syntax and the legacy cmap syntax.
• Add a new baseline image for the histogram fill behavior.

File summaries

File	Description
pygmt/src/histogram.py	Implements the new fill="position"/fill="value" syntax and maps it onto -C / -C+b.
pygmt/tests/test_histogram.py	Adds pytest-mpl image tests covering both new and legacy CPT fill syntaxes, plus an error case.
pygmt/tests/baseline/test_histogram_fill.png	Adds the new baseline image used by the pytest-mpl tests.

Review details

• Files reviewed: 3/3 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.

[yvonnefroehlich]

Here we write "bin", but the GMT says "bar", please see https://docs.generic-mapping-tools.org/dev/histogram.html#c:

Give a CPT. The mid-coordinate for each bar is used to look up the bar color.

I agree that "bin" makes more sense. The x-position of the bars can be changed, e.g., via bar_offset.

[seisman]

I think "bar" represents the visual element, while "bin" represents the actual data range of a bar.