mask

earthkit.transforms.spatial.mask(dataarray: Dataset | DataArray, geodataframe: GeoDataFrame | None = None, mask_dim: str | None = None, lat_key: str | None = None, lon_key: str | None = None, chunk: bool = True, union_geometries: bool = False, area: dict | None = None, **mask_kwargs) → Dataset | DataArray[source]

Apply multiple shape masks to some gridded data.

Each feature in shape is treated as an individual mask to apply to data. The data provided is returned with an additional dimension equal in length to the number of features in the shape object, this can result in very large files which will slow down your script. It may be better to loop over individual features, or directly apply the mask with the shapes.reduce.

Parameters:

  • dataarray – Xarray data object (must have geospatial coordinates).

  • geodataframe – Geopandas Dataframe containing the polygons for aggregations. Either geodataframe or area must be provided, but not both.

  • area (dict, optional) – Dictionary with keys "north", "south", "east", "west" defining a bounding box. Converted to a single-polygon GeoDataFrame internally. Areas that cross the anti-meridian (west > east) are not currently supported.

  • mask_dim – dimension that will be created to accommodate the masked arrays, default is the index of the geodataframe

  • all_touched – If True, all pixels touched by geometries will be considered in, if False, only pixels whose center is within. Default is False. Only valid for regular data.

  • lat_key – key for latitude variable, default behaviour is to detect variable keys.

  • lon_key – key for longitude variable, default behaviour is to detect variable keys.

  • chunk (bool) – Boolean to indicate whether to use chunking, default = True. This is advised as spatial.masks can create large results. If you are working with small arrays, or you have implemented you own chunking rules you may wish to disable it.

  • union_geometries (bool) – Boolean to indicate whether to union all geometries before masking. Default is False, which will apply each geometry in the geodataframe as a separate mask.

  • mask_kwargs – Any kwargs to pass into the mask method

Returns:

A masked data array with dimensions [feature_id] + [data.dims]. Each slice of layer corresponds to a feature in layer.

Return type:

xarray.Dataset | xarray.DataArray