emsarray.operations.depth

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

ocean_floor(dataset, depth_coordinates, *, 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 (xarray.Dataset) – The dataset to reduce.

• depth_coordinates (iterable of data array or name) – The depth coordinate variables. For supported conventions, use Convention.depth_coordinates().

• non_spatial_variables (iterable of data array or name) – A list 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.time_coordinate().

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_coordinates=big_dataset.ems.depth_coordinates))
<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.depth_coordinates(), normalize_depth_variables(), utils.extract_vars()

normalize_depth_variables(dataset, depth_coordinates, *, 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_coordinates (iterable of data array or name) – The depth coordinate variables.

• 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 indexes. If False, the layers are ordered such that deeper layers have higher indexes. 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.depth_coordinates()