transforms.aggregate.spatial

Attributes

logger

Functions

rasterize(shape_list, coords[, lat_key, lon_key, dtype])	Rasterize a list of geometries onto the given xarray coordinates.
mask_contains_points(shape_list, coords[, lat_key, ...])	Return a mask array for the spatial points of data that lie within shapes in shape_list.
shapes_to_masks(shapes, target[, regular])	Method which creates a list of masked dataarrays, if possible use the shape_mask_iterator.
shapes_to_mask(shapes, target[, regular])	Method which creates a single masked dataarray based on all features in shapes,
get_mask_dim_index(mask_dim, geodataframe[, ...])
mask(dataarray, geodataframe[, lat_key, lon_key])	Apply shape mask to some gridded data.
masks(dataarray, geodataframe[, mask_dim, lat_key, ...])	Apply multiple shape masks to some gridded data.
reduce(dataarray[, geodataframe])	Apply a shape object to an xarray.DataArray object using the specified 'how' method.

Module Contents

transforms.aggregate.spatial.logger

transforms.aggregate.spatial.rasterize(shape_list, coords, lat_key='latitude', lon_key='longitude', dtype=int, **kwargs)

Rasterize a list of geometries onto the given xarray coordinates. This only works for regular and contiguous latitude and longitude grids.

Parameters:

• (affine.Affine) (shape_list)

• (xarray.coords) (coords)

• lat_key/lon_key (name of the latitude/longitude variables in the coordinates object)

• fill (value to fill points which are not within the shape_list, default is 0)

• dtype (datatype of the returned mask, default is `int`)

• kwargs (Any other kwargs accepted by rasterio.features.rasterize)

Returns:

A mask where points not inside the shape_list are set to fill value

Return type:

xr.DataArray

transforms.aggregate.spatial.mask_contains_points(shape_list, coords, lat_key='lat', lon_key='lon', **kwargs)

Return a mask array for the spatial points of data that lie within shapes in shape_list. Function uses matplotlib.Path so can accept a list of points, this is much faster than shapely. It was initially included for use with irregular data but has been constructed to also accept regular data and return in the same format as the rasterize function.

Parameters:

• (affine.Affine) (shape_list)

• (xarray.coords) (coords)

• lat_key/lon_key (name of the latitude/longitude variables in the coordinates object)

• fill (value to fill points which are not within the shape_list, default is 0)

• dtype (datatype of the returned mask, default is `int`)

Returns:

A mask where points not inside the shape_list are set to fill value

Return type:

xr.DataArray

transforms.aggregate.spatial.shapes_to_masks(shapes, target, regular=True, **kwargs)

Method which creates a list of masked dataarrays, if possible use the shape_mask_iterator.

Parameters:

• list[gpd.GeoDataFrame]) (shapes (gpd.GeoDataFrame |) – containing the polygons for masks

• (xarray.DataArray) (target)

• (bool) (regular) – if False use mask_contains_points

• (optional) (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.

• kwargs (kwargs accepted by the masking methods, rasterize or mask_contains_points)

Returns:

A list of masks where points inside each geometry are 1, and those outside are np.nan

Return type:

list[xr.DataArray]

transforms.aggregate.spatial.shapes_to_mask(shapes, target, regular=True, **kwargs)

Method which creates a single masked dataarray based on all features in shapes,

if possible use the shape_mask_iterator.

Parameters:

• list[gpd.GeoDataFrame]) (shapes (gpd.GeoDataFrame |) – containing the polygons for masks

• (xarray.DataArray) (target)

• (bool) (regular) – if False use mask_contains_points

• (optional) (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.

• kwargs (kwargs accepted by the masking methods, rasterize or mask_contains_points)

Returns:

A mask where points inside any geometry are 1, and those outside are np.nan

Return type:

xr.DataArray

transforms.aggregate.spatial.get_mask_dim_index(mask_dim, geodataframe, default_index_name='index')

transforms.aggregate.spatial.mask(dataarray, geodataframe, lat_key=None, lon_key=None, **mask_kwargs)

Apply shape mask to some gridded data.

The geodataframe object is treated as a single mask, any points that lie outside of any of the features are masked

Parameters:

• dataarray (xr.Dataset | xr.DataArray) – Xarray data object (must have geospatial coordinates).

• (optional) (all_touched) – Geopandas Dataframe containing the polygons for aggregations

• (optional) – key for latitude/longitude variable, default behaviour is to detect variable keys.

• (optional) – 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.

Returns:

A masked data array/dataset with same dimensions as the input dataarray/dataset. Any point that does not lie in any of the features of geodataframe is masked.

Return type:

xr.Dataset | xr.DataArray

transforms.aggregate.spatial.masks(dataarray, geodataframe, mask_dim=None, lat_key=None, lon_key=None, chunk=True, **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

• (optional) (lat_key/lon_key) – dimension that will be created to accomodate the masked arrays, default is the index of the geodataframe

• (optional) – 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.

• (optional) – key for latitude/longitude variable, default behaviour is to detect variable keys.

• chunk ((optional) 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.

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.aggregate.spatial.reduce(dataarray, geodataframe=None, *args, **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

• (optional) (kwargs) – method used to apply mask. Default=’mean’, which calls np.nanmean

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

• (optional) – key for latitude/longitude variable, default behaviour is to detect variable keys.

• (optional) – any additional dimensions to aggregate over when reducing over spatial dimensions

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

• (optional) – 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.

• (optional) – Any kwargs to pass into the mask method

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

• (optional) – label to append to variable name in returned object, default is not to append

• (optional) – 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