PlasmaCalcs.tools.xarray_tools.xarray_masks.xarray_mask

PlasmaCalcs.tools.xarray_tools.xarray_masks.xarray_mask(array, mask=None, stackdim='_mask_stack', *, stack=True, create_index=True, skip_arrays_without_mask_dims=True, store_mask=None, promote_dims_if_needed=True)

mask an xarray object; result has non-nan values only where mask=False.

By default, also stack along mask dimensions, and drop points where mask=True.

array: xarray.DataArray or xarray.Dataset: object to be masked.
mask: None or xarray.DataArray: mask to apply to array.

None –> use array[‘_mask’] (and array must be a Dataset)
stackdim: str, default ‘_mask_stack’: result.dims[stackdim] has the mask dimensions stacked.
stack: bool: whether to stack result.

if False, don’t stack, just use array.where(~mask). (~ means negation)
create_index: bool: whether to create a MultiIndex for stackdim in the result, if stack.
skip_arrays_without_mask_dims: bool: whether to apply mask to arrays without mask dims.

if True, only arrays originally containing at least one mask dim will be masked.

if False, all results will have mask dims (or stackdim) via array.where(~mask).
store_mask: None or bool: whether to store full mask as a data_var in result.

None –> True if array is a Dataset, else False

True –> result Dataset will have full mask in data_var ‘_mask’.

If stack, mask dims replaced by ‘_mask_{d}’ for d in mask.dims,

to avoid conflict with original mask dims’ coords in result.

If input DataArray, first convert to Dataset with data_var array.name.

False –> do not store mask in result.
promote_dims_if_needed: bool: whether to promote non-dimension coords to dimensions.

if False, raise DimensionKeyError if any relevant coord is not already a dimension.

crash with DimensionKeyError if any relevant dim (stackdim, ‘_mask’, ‘_mask_{d}’) already exists.