Skip to content

Documents · Verb reference

plot

Plot a cube, semantic Dataset, or EventResult using dimensional dispatch.

Callable type: Grammar verb / pipe stage · Browse: Visualization

Usage

from cubedynamics import verbs as v
v.plot(da=None, *, variable=None, title=None, cmap='viridis', size_px=None, thin_time_factor=4, time_dim=None, clim=None, camera=None, axis_rig=True, fig_id=None, fig_title=None, fig_text=None)

Arguments

Argument Meaning Default
da Input semantic object. Three-dimensional time-space fields use the interactive cube viewer, 2-D spatial fields use a static map, and 1-D temporal fields use a static line plot. EventResult selects its event_active field. If None, a verb is returned. None
variable Dataset variable to render. When omitted, state then event_active is preferred, or the sole data variable is used. Ambiguous Datasets require an explicit selection. None
title Override the viewer title. Defaults to time × y × x cube. None
cmap Colormap used for the fill scale. 'viridis'
size_px Pixel size for each facet tile. If omitted, the viewer uses responsive sizing. None
thin_time_factor Decimation factor for time frames to keep the viewer responsive. 4
time_dim Name of the temporal dimension. Inferred when not provided. None
clim Color limits for the continuous scale. None
camera Plotly-style camera configuration used to set the initial cube view. When omitted, a front-right, zoomed-out default is applied. None
axis_rig See implementation docstring below; no parameter-specific description supplied. True
fig_id Caption metadata used by the viewer export helpers. None
fig_title Caption metadata used by the viewer export helpers. None
fig_text Caption metadata used by the viewer export helpers. None

Accepts

A renderable DataArray, Dataset, VirtualCube, or EventResult. Dataset selection prefers state, then event_active, then a sole variable; otherwise pass variable= explicitly.

Returns

A CubePlot for 3-D time-space cubes, or a notebook-ready StaticPlot for 2-D spatial maps and 1-D temporal lines. Dataset selection preserves laziness and combines Dataset-level semantic metadata with selected-variable metadata.

Order / grammar behavior

Plot the semantic product you intend to inspect. Plotting does not alter or certify the underlying analysis.

Minimal example

Run from the repository root after python -m pip install -e '.[vignettes]'. Uses the checked observational PRISM fixture; no network is required.

from pathlib import Path
import xarray as xr
import matplotlib.pyplot as plt
from cubedynamics import pipe, verbs as v

# Frozen, reviewed PRISM observations; run from the repository root.
path = Path("tests/fixtures/real_data/prism_boulder_january_2024.nc")
with xr.open_dataset(path, engine="scipy") as observed:
    cube = observed["tmax"].load()
assert cube.attrs["units"] == "degC"

condition = (pipe(cube) | v.threshold_state(threshold=0, direction="below")).unwrap()
result = pipe(condition) | v.plot(variable="state", title="Observed freezing condition")
# In Jupyter, display the pipe to interact with its attached HTML viewer.
from IPython.display import display
display(result)

Works with

A renderable DataArray, Dataset, VirtualCube, or EventResult. Dataset selection prefers state, then event_active, then a sole variable; otherwise pass variable= explicitly.

See also

Implementation notes

Selecting a Dataset variable preserves dask backing and merges Dataset semantic attrs with variable attrs on the shallow viewer input. The viewer only samples minimal data for thumbnails, keeping streaming behavior intact. If a vase is attached in da.attrs['vase'] a thin outline overlay is attempted. The original cube is not mutated; the pipe's wrapped result is the viewer.

Implementation source. Signatures and descriptions on this page are generated from this checkout, not hand-maintained copies.