waterfall

waterfall(
    patch: Patch ,
    ax: matplotlib.axes._axes.Axes | None[Axes, None] = None,
    cmap: str | None[str, None] = None,
    scale: float | collections.abc.Sequence[float, collections.abc.Sequence[float], None] = None,
    scale_type: Literal[‘relative’, ‘absolute’] = relative,
    interpolation: str | None[str, None] = antialiased,
    interpolation_stage: str = auto,
    gap_color: str | collections.abc.Sequence[str, collections.abc.Sequence[float], None] = None,
    gap_factor: float = 1.5,
    log: bool = False,
    cbar: bool = True,
    show: bool = False,
    label_coord: str | None[str, None] = None,
)-> ‘plt.Axes’

Create a waterfall plot of the Patch data.

Evenly sampled coordinates use imshow. Finite, monotonic irregular coordinates use pcolormesh so cells follow their coordinate values; incomplete coordinates fall back to imshow. Explicit cell bounds take precedence; cells that cannot form uniform image pixels are drawn individually, including overlapping cells and gaps. Nonmonotonic coordinates raise ParameterError.

Parameters

Parameter	Description
patch	The Patch object.
ax	A matplotlib object, if None create one.
cmap	Matplotlib colormap. None selects one from the patch `data_type`.
scale	Color limits. A scalar produces symmetric limits: a fraction of half the data range around its mean when relative, or `±abs(scale)` when absolute. A relative pair maps fractions from 0 to 1 onto the data minimum and maximum; an absolute pair gives the limits directly. Percent quantities are converted to fractions.
scale_type	Interpret `scale` as `"relative"` fractions or `"absolute"` values.
interpolation	Passed to matplotlib `imshow`. `"antialiased"` handles large arrays well; None can help if they look smeared. Ignored by `pcolormesh`.
interpolation_stage	`imshow` interpolation stage: `"data"`, `"rgba"`, or `"auto"`. Ignored by `pcolormesh`.
gap_color	Color for gaps in irregular coordinates. A color inserts masked cells at detected gaps; None bridges them with adjacent cells. Existing NaN or masked data use the same color. Applies only to `pcolormesh`.
gap_factor	Intervals larger than this many steps are gaps, measured against the coordinate’s declared step when it has one and its median spacing otherwise (the rule `Spool.chunk` applies with `tolerance`). Must exceed 1, even when `gap_color` is None and it has no visual effect. Mixed sampling rates may classify coarser regions as gaps; increase this value or plot or resample those regions separately.
log	If True, visualize the common logarithm of the absolute values of patch data. To avoid log(0), the abs(array) is cast to float64 and a small value added.
cbar	Whether to draw a colorbar.
show	Whether to show the plot.
label_coord	Coordinate whose values label stretches along one plotted dimension, drawn on its spines without tinting the data. Its legend is outside a figure created here, or in the upper-right of a supplied `ax`. String and numeric values are categories; a boolean coordinate marks only True stretches. Empty strings, NaN, and False are omitted. A coordinate that is a dimension, spans both dimensions, has no labels, exceeds 20 labels, or changes more than 200 times raises `ParameterError` before drawing.

Examples

# Plot with default scaling (uses 1.5*IQR fence to exclude outliers)
import dascore as dc
from dascore.units import percent
patch = dc.get_example_patch("example_event_1").normalize("time")
_ = patch.viz.waterfall()

_ = patch.viz.waterfall(scale=(0.1, 0.9), scale_type="relative")
_ = patch.viz.waterfall(scale=10 * percent)
_ = patch.viz.waterfall(scale=(-0.5, 0.5), scale_type="absolute")
_ = patch.viz.waterfall(log=True)

from dascore.examples import inventory_patch_pair
zoned, inventory = inventory_patch_pair()
_ = zoned.enrich(inventory).viz.waterfall(label_coord="zone")

ax = patch.viz.waterfall()
ax.invert_yaxis()

Note

Empty dimensions raise ParameterError. Time-like Y axes are inverted by seismic convention; call ax.invert_yaxis() to undo this. Since version 0.1.13, scale=None uses a statistical fence to limit outliers; use scale=1.0 for the full data range.