emsarray.operations.depth

These operations function on datasets with a depth axis, such as the output from ocean models.

ocean_floor(dataset, depth_variables, *, non_spatial_variables=None)

Make a new xarray.Dataset reduced along the given depth coordinates to only contain values along the ocean floor.

Parameters:

• dataset – The dataset to reduce.

• depth_variables – The names of depth coordinate variables. For supported conventions, use Convention.get_all_depth_names().

• non_spatial_variables – Optional. A list of the names of any non-spatial coordinate variables, such as time. The ocean floor is assumed to be static across non-spatial dimensions. For supported conventions, use Convention.get_time_name().

Returns:

xarray.Dataset – A new dataset with values taken from the deepest data.

Examples

>>> dataset
<xarray.Dataset>
Dimensions:  (z: 5, y: 5, x: 5)
Coordinates:
    lon      (x) int64 0 -1 -2 -3 -4
    lat      (y) int64 0 1 2 3 4
    depth    (z) float64 4.25 3.25 2.25 1.25 0.25
Dimensions without coordinates: z, y, x
Data variables:
    temp     (z, y, x) float64 0.0 nan nan nan nan nan ... 4.0 4.0 4.0 4.0 4.0
>>> operations.ocean_floor(dataset, ['depth'])
<xarray.Dataset>
Dimensions:  (y: 5, x: 5)
Coordinates:
    lon      (x) int64 0 -1 -2 -3 -4
    lat      (y) int64 0 1 2 3 4
Dimensions without coordinates: y, x
Data variables:
    temp     (y, x) float64 0.0 1.0 2.0 3.0 4.0 1.0 ... 4.0 4.0 4.0 4.0 4.0

This operation is relatively efficient, but still involves masking every variable that includes a depth axis. Where possible, do any time and space slicing before calling this method, and drop any variables you are not interested in.

>>> operations.ocean_floor(
...     big_dataset['temp'].isel(record=0).to_dataset(),
...     depth_variables=big_dataset.ems.get_all_depth_names())
<xarray.Dataset>
Dimensions:  (y: 5, x: 5)
Coordinates:
    lon      (x) int64 0 -1 -2 -3 -4
    lat      (y) int64 0 1 2 3 4
Dimensions without coordinates: y, x
Data variables:
    temp     (y, x) float64 0.0 1.0 2.0 3.0 4.0 1.0 ... 4.0 4.0 4.0 4.0 4.0

See also

Convention.ocean_floor(), Convention.get_all_depth_names(), normalize_depth_variables(), utils.extract_vars()

normalize_depth_variables(dataset, depth_variables, *, positive_down=None, deep_to_shallow=None)

Some datasets represent depth as a positive variable, some as negative. Some datasets sort depth layers from deepest to most shallow, others from shallow to deep. normalize_depth_variables() will return a new dataset with the depth variables normalized.

All depth variables should have a positive: "up" or positive: "down" attribute. If this attribute is missing, a warning is generated and a value is determined by examining the coordinate values.

Parameters:

• dataset (xarray.Dataset) – The dataset to normalize

• depth_variables (list of Hashable) – The names of the depth coordinate variables. This should be the names of the variables, not the dimensions, for datasets where these differ.

• positive_down (bool, optional) – If True, positive values will indicate depth below the surface. If False, negative values indicate depth below the surface. If None, this attribute of the depth coordinate is left unmodified.

• deep_to_shallow (bool, optional) – If True, the layers are ordered such that deeper layers have lower indices. If False, the layers are ordered such that deeper layers have higher indices. If None, this attribute of the depth coordinate is left unmodified.

Returns:

xarray.Dataset – A copy of the dataset with the depth variables normalized.

See also

Convention.normalize_depth_variables(), Convention.get_all_depth_names()