pygmt.Figure.fill_between

Figure.fill_between(x, y, y2=0, x2=None, fill=None, pen=None, label=None, fill2=None, pen2=None, label2=None, legend_pen=False, projection=None, region=None, frame=False, no_clip=False, verbose=False, panel=False, perspective=False, transparency=None)

Fill the area between two horizontal curves.

This method is a high-level wrapper around pygmt.Figure.plot to fill the area between a primary curve y(x) and a secondary curve y2(x). The y2 parameter can be either a single value [Default is 0] or a sequence. It can share the same x coordinates as y or use a separate x2 coordinate sequence.

Parameters:

  • x (Sequence[float]) – X-coordinates of the primary curve.

  • y (Sequence[float]) – Y-coordinates of the primary curve.

  • y2 (float | Sequence[float], default: 0) – Y-coordinates of the secondary curve. It can be a scalar value for a horizontal reference line, or a sequence with the same length as x and y when x2 is not used. Default is 0.

  • x2 (Sequence[float] | None, default: None) – X-coordinates of the secondary curve. Use this parameter only when y2 is a sequence sampled at different x-coordinates from y. In that case, y2 must have the same length as x2.

  • fill (str | None, default: None) – Fill for areas where the primary curve is greater than the secondary curve.

  • fill2 (str | None, default: None) – Fill for areas where the secondary curve is greater than the primary curve.

  • pen (str | None, default: None) – Pen attributes for the primary curve.

  • pen2 (str | None, default: None) – Pen attributes for the secondary curve.

  • label (str | None, default: None) – Label for the primary curve, to be displayed in the legend.

  • label2 (str | None, default: None) – Label for the secondary curve, to be displayed in the legend.

  • legend_pen (bool | str, default: False) –

    Draw legend entries as colored lines instead of filled boxes. By default, legend entries use fill and fill2 for the box fills and pen and pen2 for the box outlines. Set legend_pen=True to switch to colored lines that use the fill colors. Pass a pen thickness to control the legend line thickness.

    Note

    Due to an upstream GMT bug (https://github.com/GenericMappingTools/gmt/pull/9070), GMT <= 6.6.0 always uses a 2.5p pen thickness for these legend lines, regardless of the value passed to legend_pen.

  • no_clip (bool, default: False) – Do not clip curves that fall outside the frame boundaries.

  • projection (str | None, default: None) – projcode[projparams/]width|scale. Select map projection.

  • region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • frame (Frame | Axis | Literal['none'] | str | Sequence[str] | bool, default: False) – Set frame and axes attributes for the plot. It can be a bool, "none", a pygmt.params.Frame or pygmt.params.Axis object. Raw GMT strings or sequences of strings are also supported for backward compatibility. If frame=True, the frame will be drawn with the default attributes. If frame="none", no frame will be drawn. Use a pygmt.params.Frame or pygmt.params.Axis object for more control over the attributes of the frame and axes. A tutorial is available at frame and axes attributes. Full documentation is at https://docs.generic-mapping-tools.org/6.6/gmt.html#b-full.

  • verbose (bool or str) – Select verbosity level [Full usage].

  • panel (int | Sequence[int] | bool, default: False) –

    Select a specific subplot panel. Only allowed when used in Figure.subplot mode.

    • True to advance to the next panel in the selected order.

    • index to specify the index of the desired panel.

    • (row, col) to specify the row and column of the desired panel.

    The panel order is determined by the Figure.subplot method. row, col and index all start at 0.

  • perspective (float | Sequence[float] | str | bool, default: False) –

    Select perspective view and set the azimuth and elevation of the viewpoint.

    Accepts a single value or a sequence of two or three values: azimuth, (azimuth, elevation), or (azimuth, elevation, zlevel).

    • azimuth: Azimuth angle of the viewpoint in degrees [Default is 180, i.e., looking from south to north].

    • elevation: Elevation angle of the viewpoint above the horizon [Default is 90, i.e., looking straight down at nadir].

    • zlevel: Z-level at which 2-D elements (e.g., the plot frame) are drawn. Only applied when used together with zsize or zscale. [Default is at the bottom of the z-axis].

    Alternatively, set perspective=True to reuse the perspective setting from the previous plotting method, or pass a string following the full GMT syntax for finer control (e.g., adding +w or +v modifiers to select an axis location other than the plot origin). See https://docs.generic-mapping-tools.org/6.6/gmt.html#perspective-full for details.

  • transparency (float) – Set transparency level, in [0-100] percent range [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

Examples

>>> import numpy as np
>>> import pygmt
>>> x = np.linspace(0, 2 * np.pi, 200)
>>> fig = pygmt.Figure()
>>> fig.basemap(region=[0, 2 * np.pi, -1.2, 1.2], projection="X10c/4c", frame=True)
>>> fig.fill_between(
...     x=x,
...     y=np.sin(2 * x),
...     y2=np.sin(3 * x),
...     fill="lightblue",
...     pen="1p,blue",
...     fill2="lightred",
...     pen2="1p,red",
... )
>>> fig.show()

Examples using pygmt.Figure.fill_between

Cross-section along a transect

Cross-section along a transect

Fill area between curves

Fill area between curves