uxarray.UxDataset.isel

Contents

uxarray.UxDataset.isel#

UxDataset.isel(indexers=None, drop=False, missing_dims='raise', ignore_grid=False, inverse_indices=False, **indexers_kwargs)#

Return a new UxDataset with arrays indexed along the specified dimension(s). Each data array is indexed appropriately, along with the underlying grid when applicable.

Grid dimensions (‘n_node’, ‘n_edge’, ‘n_face’) are treated specially when ignore_grid=False (this is the default). Any one of them can be indexed, regardless of data location, and the result will be sliced to form the minimal grid of faces containing all the nodes, edges, or faces specified. For example, using n_edge=7 selects just the two faces touching edge 7. For data on ‘n_face’, the result would have ‘n_face’ with just those two faces. For data on ‘n_edge’, the result would have ‘n_edge’ with all edges located on either of those two faces.

Grid dimension indexers cannot have more than 1 dimension (such as a 2D DataArray). Grid dimensions are never renamed (even if indexed by 1D DataArray with different dim name). Grid dimension indexer cannot have a non-grid dimension which exists in the original UxDataset.

Parameters:

  • indexers (dict, optional) – A dict with keys matching dimensions and values given by integers, slice objects or arrays. indexer can be a integer, slice, array-like or DataArray. If DataArrays are passed as indexers, xarray-style indexing will be carried out. See Indexing and selecting data for the details. One of indexers or indexers_kwargs must be provided.

  • drop (bool, default: False) – If drop=True, drop coordinates variables indexed by integers instead of making them scalar.

  • missing_dims ({"raise", "warn", "ignore"}, default: "raise") – What to do if dimensions that should be selected from are not present in the UxDataset: - “raise”: raise an exception - “warn”: raise a warning, and ignore the missing dimensions - “ignore”: ignore the missing dimensions

  • ignore_grid (bool, default=False) – If False (default), slice the underlying UXarray grid appropriately too, ensuring the resulting data actually lies on the result’s underlying grid. If True, slice the data only; attach self.uxgrid to the result, unchanged. CAUTION: using ignore_grid=True will cause the result’s data to be inconsistent with its underlying grid, if any grid dimensions were sliced.

  • inverse_indices (bool, default=False) – For grid-based slicing, pass this flag to Grid.isel to invert indices when selecting (useful for staggering or reversing order).

  • **indexers_kwargs (dimension=indexer pairs, optional) – The keyword arguments form of indexers.

Returns:

A new UxDataset indexed according to indexers and updated grid if applicable. If indexer DataArrays have coordinates that do not conflict with this object, then these coordinates will be attached, except that 1D coordinates of indexers applied along a grid dimension will only be included if it is ‘n_face’ and the data also has ‘n_face’ dimension.

Return type:

UxDataset

Raises:

  • DimensionError (subclass of ValueError) – If more than one grid dimension is selected and ignore_grid=False.

  • ValueError – If parameters are invalid for xarray’s .isel(), such as if slicing by a nonexistent dimension, or using invalid indexers.

Contents