waterfall

waterfall(
    patch: Patch ,
    ax: matplotlib.axes._axes.Axes | None[Axes, None] = None,
    cmap = bwr,
    scale: float | collections.abc.Sequence[float, collections.abc.Sequence[float], None] = None,
    scale_type: Literal[‘relative’, ‘absolute’] = relative,
    log: bool = False,
    show: bool = False,
)-> ‘plt.Axes’

Create a waterfall plot of the Patch data.

Parameters

Parameter	Description
patch	The Patch object.
ax	A matplotlib object, if None create one.
cmap	A matplotlib colormap string or instance. Set to None to not plot the colorbar.
scale	If not None, controls the saturation level of the colorbar. Values can either be a float, to set upper and lower limit to the same value centered around the mean of the data, a length 2 tuple specifying upper and lower limits, or None, which will automatically determine limits based on a quartile fence. (uses q1 - 1.5 * (q3 - q1) and q3 + 1.5 * (q3 - q1)).
scale_type	Controls the type of scaling specified by `scale` parameter. Options are: relative - scale based on half the dynamic range in patch absolute - scale based on absolute values provided to `scale`
log	If True, visualize the common logarithm of the absolute values of patch data.
show	If True, show the plot, else just return axis.

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()

# Use relative scaling with a tuple to show a specific fraction
# of data range. Scale values of (0.1, 0.9) map to 10% and 90%
# of the data's [min, max] range
_ = patch.viz.waterfall(scale=0.1, scale_type="relative")
# Likewise, percent units can be used for additional clarity
_ = patch.viz.waterfall(scale=10*percent, scale_type="absolute")

# Use relative scaling with a tuple to show the middle 80% of data range
# Scale values of (0.1, 0.9) map to 10% and 90% of [data_min, data_max]
_ = patch.viz.waterfall(scale=(0.1, 0.9), scale_type="relative")

# Use absolute scaling to set specific colorbar limits
# This directly sets the colorbar limits to [-0.5, 0.5]
_ = patch.viz.waterfall(scale=(-0.5, 0.5), scale_type="absolute")

# Visualize data on a logarithmic scale
# Useful for data spanning multiple orders of magnitude
_ = patch.viz.waterfall(log=True)

# Compare scale types: relative vs absolute
import matplotlib.pyplot as plt
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))
# Relative: 0.5 means ±50% of dynamic range around mean
_ = patch.viz.waterfall(scale=0.5, scale_type="relative", ax=ax1)
_ = ax1.set_title("Relative scaling (scale=0.5)")
# Absolute: 0.5 means colorbar limits are [-0.5, 0.5]
_ = patch.viz.waterfall(scale=0.5, scale_type="absolute", ax=ax2)
_ = ax2.set_title("Absolute scaling (scale=0.5)")

# Undo Y axis inversion which occurs when time is on the Y
ax = patch.viz.waterfall()
ax.invert_yaxis()

Note

The Y axis is automatically inverted if it is “time-like”. This is to be consistent with standard seismic plotting convention. If you don’t want this, simply invert the y axis of the returned axis object as shown in the example section.
Changes to default scale behavior: Until DASCore version 0.1.13, the default behavior when scale=None was to scale along the entire range of the data. However, very often in real data a few anomalously large or small values would obscure most of the patch details. In version 0.1.13 the default behavior is to now use a statistical fence to avoid the problem. To get the old behavior, simply set scale=1.0.