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,
    log: bool = False,
    cbar: bool = True,
    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. If `None`, a colormap will be chosen automatically, depending on the data_type of the patch.
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`
interpolation	A value fed to matplotlib’s imshow to handle downsampling large arrays, which is relevant for DAS. Usually, “antialiased” works well, but if the data look smeared disabling interpolation with None might help. Other options are available, see matplotlib’s documentation for more details.
interpolation_stage	If ‘data’, interpolation is carried out on the data provided by the user. If ‘rgba’, the interpolation is carried out after the colormapping has been applied (visual interpolation). ‘auto’ (default) selects a suitable interpolation stage automatically. See matplotlib’s imshow documentation for more details.
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	If True, plot the colorbar, else do not. This controls only colorbar display; use `cmap` to control colormap selection.
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.