deltametrics.cube.BaseCube¶

class deltametrics.cube.BaseCube(data, read=[], varset=None, dimensions=None)¶

Base cube object.

Cube objects contain t-x-y or z-x-y information.

This base class should not be used directly, but is subclassed below, providing convenient obejcts for maniplating common data types.

Note

Cube does not load any data into memory by default. This means that slicing is handled “behind the scenes” by an I/O file handler. Optionally, you can load files into memory for (sometimes) faster operations. See the read() for more information.

__init__(data, read=[], varset=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.
dimensions (dict, optional) – A dictionary with names and coordinates for dimensions of the cube, if instantiating the cube from data loaded in memory in a dictionary.

Methods

`__init__`(data[, read, varset, dimensions])	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.

Attributes

`H`	Number of elements, vertical (height) coordinate.
`L`	Number of elements, length coordinate.
`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).
`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 W¶: Number of elements, width coordinate.

abstract property Z¶: Vertical mesh.

abstract __getitem__(var)¶

Return the variable.

Overload slicing operations for io to return correct var. Must be implemented by subclasses.

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

>>> golfcube = dm.sample_data.golf()
>>> golfstrat = dm.cube.StratigraphyCube.from_DataCube(
...     golfcube, dz=0.1)
...
>>> fig, ax = plt.subplots(2, 1)
>>> golfcube.quick_show('eta', ax=ax[0])  # a Planform (axis=0)
>>> golfstrat.quick_show('eta', idx=100, axis=2, ax=ax[1])  # a DipSection
>>> plt.show()

(png, hires.png)

../_images/deltametrics-cube-BaseCube-1.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.

>>> golfcube = dm.sample_data.golf()
>>> golfstrat = dm.cube.StratigraphyCube.from_DataCube(
...     golfcube, dz=0.1)
...
>>> fig, ax = plt.subplots()
>>> golfstrat.show_cube('eta', ax=ax)

>>> golfcube = dm.sample_data.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().

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

abstract property z¶: Vertical coordinate.

deltametrics.cube.BaseCube¶

Table of Contents

Previous topic

Next topic

This Page