deltametrics.cube.DataCube

class deltametrics.cube.DataCube(data, read=(), varset=None, stratigraphy_from=None, dimensions=None)

DataCube object.

DataCube contains t-x-y information. It may have any number of attached attributes (grain size, mud frac, elevation).

__init__(data, read=(), varset=None, stratigraphy_from=None, dimensions=None)

Initialize the BaseCube.

Parameters:

• data (str, dict) – If data is type str, the string points to a NetCDF or HDF5 file that can be read. Typically this is used to directly import files output from the pyDeltaRCM model. Alternatively, pass a dict with keys indicating variable names, and values with corresponding t-x-y ndarray of data.

• read (bool, optional) – Which variables to read from dataset into memory. Special option for read=True to read all available variables into memory.

• varset (VariableSet, optional) – Pass a ~deltametrics.plot.VariableSet instance if you wish to style this cube similarly to another cube. If no argument is supplied, a new default VariableSet instance is created.

• stratigraphy_from (str, optional) – Pass a string that matches a variable name in the dataset to compute preservation and stratigraphy using that variable as elevation data. Typically, this is 'eta' in pyDeltaRCM model outputs. Stratigraphy can be computed on an existing data cube with the stratigraphy_from() method.

• dimensions (dict, optional) – A dictionary with names and coordinates for dimensions of the DataCube, if instantiating the cube from data loaded in memory in a dictionary.

Methods

__init__(data[, read, varset, ...])	Initialize the BaseCube.
export_frozen_variable(var[, return_cube])	Export a cube with frozen values.
quick_show(var[, idx, axis])	Convenient and quick way to show a slice of the cube by idx and axis.
read(variables)	Read variable into memory.
register_plan(*args, **kwargs)	wrapper, might not really need this.
register_planform(name, PlanformInstance[, ...])	Register a planform to the planform_set.
register_section(name, SectionInstance[, ...])	Register a section to the section_set.
show_cube(var[, style, ve, ax])	Show the cube in a 3D axis.
show_plan(*args, **kwargs)	Deprecated.
show_planform(name, variable, **kwargs)	Show a registered planform by name and variable.
show_section(name, variable, **kwargs)	Show a registered section by name and variable.
stratigraphy_from([variable, style])	Compute stratigraphy attributes.

Attributes

H	Number of elements, vertical (height) coordinate.
L	Number of elements, length coordinate.
T	Vertical mesh.
W	Number of elements, width coordinate.
Z	Vertical mesh.
coords	List of coordinate names as strings.
data_path	Path connected to for file IO.
dataio	Data I/O handler.
dim0_coords	Coordinates along the first dimension of cube.
dim1_coords	Coordinates along the second dimension of cube.
dim2_coords	Coordinates along the third dimension of cube.
extent	The limits of the dim1 by dim2 plane.
extent_flipud	The extent, reversed up-down for special plotting.
extent_zeros	A dummy variable of zeros with shape of extent.
meta
planform_set	Set of planform instances.
planforms	Set of plan instances.
section_set	Set of section instances.
sections	Set of section instances.
shape	Number of elements in data (HxLxW).
t	time coordinate.
variables	List of variable names as strings.
varset	Variable styling for plotting.
z	Vertical coordinate.

property H

Number of elements, vertical (height) coordinate.

property L

Number of elements, length coordinate.

property T

Vertical mesh.

property W

Number of elements, width coordinate.

property Z

Vertical mesh.

__getitem__(var)

Return the variable.

Overload slicing operations for io to return a CubeVariable instance when slicing.

Parameters:

var (str) – Which variable to slice.

Returns:

CubeVariable – The instantiated CubeVariable.

Return type:

~deltametrics.cube.CubeVariable

property coords

List of coordinate names as strings.

Type:

list

property data_path

Path connected to for file IO.

Returns a string if connected to file, or None if cube initialized from dict.

Type:

str

property dataio

Data I/O handler.

Type:

BaseIO subclass

property dim0_coords

Coordinates along the first dimension of cube.

property dim1_coords

Coordinates along the second dimension of cube.

property dim2_coords

Coordinates along the third dimension of cube.

export_frozen_variable(var, return_cube=False)

Export a cube with frozen values.

Creates a H x L x W ndarray with values from variable var placed into the array. This method is particularly useful for inputs to operation that will repeatedly utilize the underlying data in computations. Access to underlying data is comparatively slow to data loaded in memory, because the Cube utilities are configured to read data off-disk as needed.

property extent

The limits of the dim1 by dim2 plane.

Useful for plotting.

property extent_flipud

The extent, reversed up-down for special plotting.

limits of the dim1 by dim2 plane,

property extent_zeros

A dummy variable of zeros with shape of extent.

Returns an array of zeros with the shape of the cube.

property planform_set

Set of planform instances.

Type:

dict

property planforms

Set of plan instances.

Alias to plan_set().

Type:

dict

quick_show(var, idx=-1, axis=0, **kwargs)

Convenient and quick way to show a slice of the cube by idx and axis.

Hint

If neither idx or axis is specified, a planform view of the last index is shown.

Parameters:

• var (str) – Which variable to show from the underlying dataset.

• idx (int, optional) – Which index along the axis to slice data from. Default value is -1, the last index along axis.

• axis (int, optional) – Which axis of the underlying cube idx is specified for. Default value is 0, the first axis of the cube.

• **kwargs – Keyword arguments are passed to show() if axis is 0, otherwise passed to show().

Examples

(Source code, png, hires.png)

read(variables)

Read variable into memory.

Parameters:

variables (list of str, str) – Which variables to read into memory.

register_plan(*args, **kwargs)

wrapper, might not really need this.

register_planform(name, PlanformInstance, return_planform=False)

Register a planform to the planform_set.

Connect a planform to the cube.

Parameters:

• name (str) – The name to register the Planform.

• PlanformInstance (BasePlanform subclass instance) – The planform instance that will be registered.

• return_planform (bool) – Whether to return the planform object.

register_section(name, SectionInstance, return_section=False)

Register a section to the section_set.

Connect a section to the cube.

Parameters:

• name (str) – The name to register the section.

• SectionInstance (BaseSection subclass instance) – The section instance that will be registered.

• return_section (bool) – Whether to return the section object.

Notes

When the API for instantiation of the different section types is settled, we should enable the ability to pass section kwargs to this method, and then instantiate the section internally. This avoids the user having to specify dm.section.StrikeSection(distance=2000) in the register_section() call, and instead can do something like golf.register_section('trial', trace='strike', distance=2000).

property section_set

Set of section instances.

Type:

dict

property sections

Set of section instances.

Alias to section_set().

Type:

dict

property shape

Number of elements in data (HxLxW).

show_cube(var, style='mesh', ve=200, ax=None)

Show the cube in a 3D axis.

Important

requires pyvista package for 3d visualization.

Parameters:

• var (str) – Which variable to show from the underlying dataset.

• style (str, optional) – Style to show cube. Default is ‘mesh’, which gives a 3D volumetric view. Other supported option is ‘fence’, which gives a fence diagram with one slice in each cube dimension.

• ve (float) – Vertical exaggeration. Default is 200.

• ax (Axes object, optional) – A matplotlib Axes object to plot the section. Optional; if not provided, a call is made to plt.gca() to get the current (or create a new) Axes object.

Examples

Note

The following code snippets are not set up to actually make the plots in the documentation.

>>> import matplotlib.pyplot as plt
>>> from deltametrics.cube import StratigraphyCube
>>> from deltametrics.sample_data.sample_data import golf

>>> golfcube = golf()
>>> golfstrat = StratigraphyCube.from_DataCube(golfcube, dz=0.1)
>>> fig, ax = plt.subplots()
>>> golfstrat.show_cube("eta", ax=ax)  

>>> golfcube = golf()
>>> fig, ax = plt.subplots()
>>> golfcube.show_cube("velocity", style="fence", ax=ax)  

show_plan(*args, **kwargs)

Deprecated. Use quick_show or show_planform.

Warning

Provides a legacy option to quickly show a planform, from before the Planform object was properly implemented. Will be removed in a future release.

show_planform(name, variable, **kwargs)

Show a registered planform by name and variable.

Call a registered planform by name and variable.

Parameters:

• name (str) – The name of the registered planform.

• variable (str) – The varaible name to show.

• **kwargs – Keyword arguments passed to show().

show_section(name, variable, **kwargs)

Show a registered section by name and variable.

Call a registered section by name and variable.

Parameters:

• name (str) – The name of the registered section.

• variable (str) – The varaible name to show.

• **kwargs – Keyword arguments passed to show().

stratigraphy_from(variable='eta', style='mesh', **kwargs)

Compute stratigraphy attributes.

Parameters:

• variable (str, optional) – Which variable to use as elevation data for computing preservation. If no value is given for this parameter, we try to find a variable eta and use that for elevation data if it exists.

• style (str, optional) – Which style of stratigraphy to compute, options are 'mesh' or 'boxy'. Additional keyword arguments are passed to stratigraphy attribute initializers.

• **kwargs – Keyword arguments passed to stratigraphy initialization. Can include specification for vertical resolution in Boxy case, see :obj:_determine_strat_coordinates`.

property t

time coordinate.

property variables

List of variable names as strings.

Type:

list

property varset

Variable styling for plotting.

Can be set with cube.varset = VariableSetInstance where VariableSetInstance is a valid instance of VariableSet.

Type:

VariableSet

property z

Vertical coordinate.