uxarray.UxDataset.sel

Contents

uxarray.UxDataset.sel#

UxDataset.sel(indexers=None, method=None, tolerance=None, drop=False, **indexers_kwargs)#

Returns a new dataset with each array indexed by labels, instead of indices, along the specified dimension(s).

Grid dimensions (‘n_node’, ‘n_edge’, ‘n_face’) are treated specially. 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.

By default, grid dims do not have coordinates assigned. But, if they have been assigned, .sel() respects them in the intuitive way. For example, using .sel(n_face=30) for data with n_face coordinates [0,10,20,30,40] would be equivalent to using .isel(n_face=3). Meanwhile, if the data does not contain the specified grid dim (as in the n_edge=7 example above), it also cannot contain coordinates along that grid dim, so in that case .sel() performs index-based selection just like .isel().

Under the hood, this method is powered by using pandas’s powerful Index objects. This makes label based indexing essentially just as fast as using integer indexing.

It also means this method uses pandas’s (well documented) logic for indexing. This means you can use string shortcuts for datetime indexes (e.g., ‘2000-01’ to select all values in January 2000). It also means that slices are treated as inclusive of both the start and stop values, unlike normal Python indexing, for any dimensions with coordinate labels. (Dimensions without coordinates treat slices normally.)

Parameters:

  • indexers (dict, optional) – A dict with keys matching dimensions and values given by scalars, slices or arrays of tick labels. For dimensions with multi-index, the indexer may also be a dict-like object with keys matching index level names. If DataArrays are passed as indexers, xarray-style indexing will be carried out (see Indexing and selecting data for the details), with one exception: grid dimensions will never be renamed. One of indexers or indexers_kwargs must be provided.

  • method ({None, "nearest", "pad", "ffill", "backfill", "bfill"}, optional) –

    Method to use for inexact matches:

    • None (default): only exact matches

    • pad / ffill: propagate last valid index value forward

    • backfill / bfill: propagate next valid index value backward

    • nearest: use nearest valid index value

    Can only provide method if all indexed dims actually have coords, else raises ValueError (consistent with xarray sel() behavior).

  • tolerance (optional) – Maximum distance between original and new labels for inexact matches. The values of the index at the matching locations must satisfy the equation abs(index[indexer] - target) <= tolerance. Can only provide tolerance if all indexed dims actually have coords, else raises ValueError (consistent with xarray sel() behavior).

  • drop (bool, optional) – If drop=True, drop coordinates variables in indexers instead of making them scalar.

  • **indexers_kwargs ({dim: indexer, ...}, optional) – The keyword arguments form of indexers. One of indexers or indexers_kwargs must be provided.

Returns:

obj – A new UxDataset with the same contents as this dataset, except each variable and dimension is indexed by the appropriate indexers, and the uxgrid indexed appropriately as well, if indexing any grid dim. 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. In general, each array’s data will be a view of the array’s data in this dataset, unless indexing along a grid dimension or otherwise triggering vectorized indexing by using an array indexer, in which case the data will be a copy.

Return type:

UxDataset

Contents