transforms.spatial

Spatial transformations for earthkit data objects.

Typically this is done with an xarray representation of data and a geopandas representation of geometries.

Functions

mask(dataarray, geodataframe[, mask_dim, lat_key, ...])	Apply multiple shape masks to some gridded data.
reduce(dataarray[, geodataframe, mask_arrays])	Apply a shape object to an xarray.DataArray object using the specified 'how' method.

Package Contents

transforms.spatial.mask(dataarray, geodataframe, mask_dim=None, lat_key=None, lon_key=None, chunk=True, union_geometries=False, **mask_kwargs)

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

• mask_dim – dimension that will be created to accomodate 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 [feautre_id] + [data.dims]. Each slice of layer corresponds to a feature in layer.

Return type:

xr.Dataset | xr.DataArray

transforms.spatial.reduce(dataarray, geodataframe=None, mask_arrays=None, **kwargs)

Apply a shape object to an xarray.DataArray object using the specified ‘how’ method.

Geospatial coordinates are reduced to a dimension representing the list of features in the shape object.

Parameters:

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

• geodataframe – Geopandas Dataframe containing the polygons for aggregations

• mask_arrays – precomputed mask array[s], if provided this will be used instead of creating a new mask. They must be on the same spatial grid as the dataarray.

• how – method used to apply mask. Default=’mean’, which calls xp.nanmean

• weights – Provide weights for aggregation, also accepts recognised keys for weights, e.g. ‘latitude’

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

• extra_reduce_dims – any additional dimensions to aggregate over when reducing over spatial dimensions

• mask_dim – dimension that will be created after the reduction of the spatial dimensions, default is the index of the dataframe

• 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.

• mask_kwargs – Any kwargs to pass into the mask method

• mask_arrays – precomputed mask array[s], if provided this will be used instead of creating a new mask. They must be on the same spatial grid as the dataarray.

• return_as – what format to return the data object, pandas or xarray. Work In Progress

• compact – If True, return a compact pandas.DataFrame with the reduced data as a new column. If False, return a fully expanded pandas.DataFrame. Only valid if return_as is pandas

• how_label – label to append to variable name in returned object, default is not to append

• kwargs – kwargs recognised by the how function

Returns:

A data array with dimensions features + data.dims not in ‘lat’,’lon’. Each slice of layer corresponds to a feature in layer.

Return type:

xr.Dataset | xr.DataArray