PlasmaCalcs.tools.xarray_tools.xarray_masks.xarray_unmask

PlasmaCalcs.tools.xarray_tools.xarray_masks.xarray_unmask(array, mask=None, stackdim='_mask_stack', *, store_mask=False, as_array=None, reindex=True, _upcast_bool=True)

unmask (i.e., unstack) a masked (and stacked) xarray object.

array.pc.unmask(mask) is equivalent to mask.pc.demask(array).

See also: xarray_unmask_var, to get a single unmasked var from a Dataset.

array: xarray.DataArray or xarray.Dataset

object to unmask.

mask: None or xarray.DataArray

the (unstacked) mask. If None, use mask stored in array[‘_mask’] (and array must be a Dataset).

stackdim: str, default ‘_mask_stack’

dimension along which the mask stacking occurred.

store_mask: None or bool

whether to store full mask as a data_var in result.

None –> True if result would otherwise be a Dataset, else False

True –> result will be a Dataset with full mask in data_var ‘_mask’.

False –> do not store mask in result.

as_array: None or bool

whether to ensure result is a DataArray.

None –> True if result would be a Dataset with a single data_var, else False.

True –> result will be a DataArray; crash if not possible

(e.g. crash if output would have multiple vars, or if store_mask=True).

False –> result will be a Dataset, unless input was a DataArray and store_mask=False.

reindex: bool

whether to result.reindex_like(mask). Highly recommended, but not required…

_upcast_bool: bool

whether to upcast dtype=bool array or data_vars to int8 before unstacking.

when False, unstacking produces a dtype=object array due to the nans for missing values.

(when True, unstacking makes dtype=float32, using 0 for False, 1 for True, nan for nan.)

In the simplest case (mask not None; array=non-boolean DataArray with MultiIndex in stackdim),

this method behaves just like array.unstack(stackdim).reindex_like(mask).

All the other stuff here helps to handle more complicated cases,

e.g. Dataset containing mask, possibly without MultiIndex along stackdim.