apply_mask

echopype.mask.apply_mask(source_ds: Union[Dataset, str, Path], mask: Union[DataArray, str, Path, List[Union[DataArray, str, Path]]], var_name: str = 'Sv', fill_value: Union[int, float, DataArray] = nan, storage_options_ds: dict = {}, storage_options_mask: Union[dict, List[dict]] = {}) → Dataset

Applies the provided mask(s) to the Sv variable var_name in the provided Dataset source_ds.

The code allows for these 3 cases of source_ds and mask dimensions:

1) No channel in both source_ds and mask, but they have matching ping_time and depth (or range_sample) dimensions. 2) source_ds and mask both have matching channel, ping_time, and depth (or range_sample) dimensions. 3) source_ds has the channel dimension and mask doesn’t, but they have matching ping_time and depth (or range_sample) dimensions.

If a user only wants to apply masks to a subset of the channels in source_ds, they could put 1s to allow all data entries in the other channels.

Parameters

source_ds: xr.Dataset, str, or pathlib.Path

Points to a Dataset that contains the variable the mask should be applied to

mask: xr.DataArray, str, pathlib.Path, or a list of these datatypes

The mask(s) to be applied. Can be a individual input or a list that corresponds to a DataArray or a path. Each individual input or entry in the list must contain dimensions ('ping_time', 'range_sample') or dimensions ('ping_time', 'depth'). The mask can also contain the dimension channel. If a path is provided this should point to a zarr or netcdf file with only one data variable in it. If the input mask is a list, a logical AND will be used to produce the final mask that will be applied to var_name.

var_name: str, default=”Sv”

The Sv variable name in source_ds that the mask should be applied to. This variable needs to have coordinates ('ping_time', 'range_sample') or coordinates ('ping_time', 'depth'), and can optionally also have coordinate channel. In the case of a multi-channel Sv data variable, the mask will be broadcast to all channels.

fill_value: int, float, or xr.DataArray, default=np.nan

Value(s) at masked indices. If fill_value is of type xr.DataArray it must have the same shape as each entry of mask.

storage_options_ds: dict, default={}

Any additional parameters for the storage backend, corresponding to the path provided for source_ds

storage_options_mask: dict or list of dict, default={}

Any additional parameters for the storage backend, corresponding to the path provided for mask. If mask is a list, then this input should either be a list of dictionaries or a single dictionary with storage options that correspond to all elements in mask that are paths.

Returns

xr.Dataset

A Dataset with the same format of source_ds with the mask(s) applied to var_name