emsarray.operations#

Useful functions for analysing or manipulating xarray.Dataset instances. These operations are not specific to ems datasets.

Most operations have aliases on Format, which can be accessed via the dataset.ems accessor.

emsarray.operations.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 formats, use Format.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 formats, use Format.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

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

emsarray.operations.normalize_depth_variables(dataset, depth_variables, *, positive_down=True, deep_to_shallow=True)#

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.

The default behaviour is for positive values to indicate deeper depths (indicated via the variable attribute positive: "down"), and for the layers to be ordered deep to shallow. This behaviour can be modified using the parameters positive_down and deep_to_shallow respectively.

Parameters

  • dataset – The dataset to normalize

  • depth_variables – 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 – When true (the default), positive values will indicate depth below the surface. When false, negative values indicate depth below the surface.

  • deep_to_shallow – When true (the default), the layers are ordered such that deeper layers have lower indices.

See also

Format.normalize_depth_variables(), Format.get_all_depth_names()

emsarray.operations.triangulate_dataset(dataset)#

Triangulate the polygon cells of a dataset

A mesh can be constructed from this triangulation, for example using Holoviews TriMesh or trimesh.Trimesh.

Parameters

dataset – The dataset to triangulate

Returns

tuple of vertices, triangles, and cell indices. – A tuple of three lists is returned, containing vertices, triangles, and cell indices respectively.

Each vertex is a tuple of (x, y) or (lon, lat) coordinates.

Each triangle is a tuple of three integers, indicating which vertices make up the triangle.

The cell indices tie the triangles to the original cell polygon, allowing you to plot data on the triangle mesh.

Examples

Using holoviews. Try this in an IPython notebook for nice visualisations:

import emsarray
import holoviews as hv
from emsarray.operations import triangulate_dataset
from holoviews import opts
hv.extension('bokeh')

# Triangulate the dataset
dataset = emsarray.tuorial.open_dataset("austen")
vertices, triangles, cell_indices = triangulate_dataset(dataset)

# This takes a while to render
mesh = hv.TriMesh((triangles, vertices))
mesh

Using trimesh. This should pop up a new window to display the output:

import emsarray
import numpy as np
import trimesh
from emsarray.operations import triangulate_dataset

dataset = emsarray.tutorial.open_dataset("gbr4")
vertices, triangles, cell_indices = triangulate_dataset(dataset)
# Trimesh expects 3D vertices.
vertices = np.c_[vertices, np.zeros(len(vertices))]
mesh = trimesh.Trimesh(vertices=vertices, faces=triangles)
mesh.invert()  # Trimesh grids expect the opposite winding order

depth = 1 - (dataset.data_vars["Mesh2_depth"].values / -200)
depth_colour = np.c_[depth, depth, depth, np.ones_like(depth)] * 255
mesh.visual.face_colors = depth_colour[cell_indices]
mesh.show()