Documents · API reference

Objects

Reference objects used by the public grammar. Signatures and methods below come from Python docstrings. Not every object is a raster cube.

Pipe

Wraps a value and records the written operation sequence.

Bases: Generic[T]

Lightweight wrapper enabling | composition for cube operations.

Grammar contract

Pipe infrastructure. Pipe itself is not a verb but carries values through verb stages and supports direct calls to verbs or plain callables. It is both direct-call (Pipe(value)) and pipe-ready via the | operator.

Parameters:

Name	Type	Description	Default
value	T	Object to wrap, typically an :class:xarray.DataArray, :class:xarray.Dataset, or streaming :class:cubedynamics.streaming.VirtualCube.	required

Returns:

Type	Description
Pipe	A pipe-ready wrapper exposing | and unwrap.

Notes

Pipe preserves streaming objects such as :class:~cubedynamics.streaming.VirtualCube and does not trigger computation. Viewer attachments are stored on the wrapped value when verbs mark themselves as pass-through, allowing notebook HTML reprs to show inline.

See Also

cubedynamics.piping.Verb, cubedynamics.piping.pipe

semantic_state property

Semantic description of the current value; no data are computed.

semantic_trace property

Immutable record of stages executed through this pipe.

unwrap()

Return the wrapped value, ending the pipe chain.

explain()

Explain the analysis in plain language without changing it.

suggest()

Suggest a short list of compatible, currently implemented verbs.

validate()

Run metadata-only semantic and ordering checks.

VirtualCube

Defers source reads and materialization. See streaming for source and tile contracts.

Representation of a lazily tiled cube.

Parameters:

Name	Type	Description	Default
dims	tuple of str	Expected dimension order of the cube, e.g., ("time", "y", "x").	required
coords_metadata	dict	Lightweight metadata used to reconstruct coordinates when needed; individual tiles supply authoritative coordinate values.	required
loader	callable	Function that returns a concrete xarray.DataArray for a tile.	required
loader_kwargs	dict	Base keyword arguments forwarded to loader for every tile request.	required
time_tiler	callable	Functions that accept loader_kwargs and yield dictionaries of tile keyword arguments along the time or spatial axes.	required
spatial_tiler	callable	Functions that accept loader_kwargs and yield dictionaries of tile keyword arguments along the time or spatial axes.	required

Notes

• A VirtualCube keeps all data lazy until materialize is called.
• iter_tiles combines time and spatial tilers deterministically so callers can stream through subsets without holding the whole cube.
• Returned tiles should be compatible for xarray.combine_by_coords.

materialize()

Materialize the virtual cube as a single :class:xarray.DataArray.

State and event results

Conditions are xarray Datasets with a Boolean state variable. Threshold and quantile constructors additionally expose scientifically defined magnitude and threshold variables; logical overlap contains only state and operand metadata. detect_events turns a temporal condition into an event result with a dataset and catalog. See the state/event analysis. Its event_scope states whether one row is a local-cell instance or consolidated regional episode; catalog length is not scientifically interpretable without that scope. consolidate_events and event_metrics preserve it.

Event data plus a catalog whose row scope is scientifically explicit.

event_scope = 'local_cell' class-attribute instance-attribute

spatial_identity_fields = ('y_index', 'x_index') class-attribute instance-attribute

unwrap()

Return the cube-form event Dataset.

explain()

Return a concise scope-aware explanation without expanding the catalog.

Runtime identity

version_info() distinguishes an installed artifact from a VCS installation or development checkout even when both intentionally retain the same semantic version.

Inspect which CubeDynamics code the current Python process imported.

development property

Whether the import comes from development/VCS source metadata.

as_dict()

Return a stable JSON-serializable record.

Fire geometry

FireEventDaily and FireHull are the canonical event/geometry model. TimeHull is a compatibility name. A VaseDefinition describes a time-varying polygon volume; it is not itself a provider dataset.

Collection of vase sections with interpolation rules.

The sections describe how a 2-D polygon cross-section should evolve through time, creating a 3-D "vase volume" once lofted across the cube. interp controls whether polygons are snapped to the nearest timestamp or interpolated vertex-by-vertex (when shapes share the same vertex layout).

sorted_sections()

Return a new VaseDefinition with sections sorted by time.

See also

Fire architecture · Semantic grammar · Source revision objects · Public API stability