transforms.aggregate.spatial
============================

.. py:module:: transforms.aggregate.spatial


Attributes
----------

.. autoapisummary::

   transforms.aggregate.spatial.logger


Functions
---------

.. autoapisummary::

   transforms.aggregate.spatial.rasterize
   transforms.aggregate.spatial.mask_contains_points
   transforms.aggregate.spatial.shapes_to_masks
   transforms.aggregate.spatial.shapes_to_mask
   transforms.aggregate.spatial.get_mask_dim_index
   transforms.aggregate.spatial.mask
   transforms.aggregate.spatial.masks
   transforms.aggregate.spatial.reduce


Module Contents
---------------

.. py:data:: logger

.. py:function:: 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.

   :param shape_list (affine.Affine):
   :type shape_list (affine.Affine): :class:`List` of :class:`geometries`
   :param coords (xarray.coords):
   :type coords (xarray.coords): :class:`Coordinates` of :class:`dataarray` to :class:`be masked`
   :param lat_key/lon_key:
   :type lat_key/lon_key: :class:`name` of :class:`the latitude/longitude variables in the coordinates object`
   :param fill:
   :type fill: :class:`value` to :class:`fill points which are not within the shape_list`, *default* :class:`is 0`
   :param dtype:
   :type dtype: :class:`datatype` of :class:`the returned mask`, *default* :class:`is `int``
   :param kwargs:
   :type kwargs: :class:`Any other kwargs accepted by rasterio.features.rasterize`

   :returns: A mask where points not inside the shape_list are set to `fill` value
   :rtype: :class:`xr.DataArray`


.. py:function:: 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.

   :param shape_list (affine.Affine):
   :type shape_list (affine.Affine): :class:`List` of :class:`geometries`
   :param coords (xarray.coords):
   :type coords (xarray.coords): :class:`Coordinates` of :class:`dataarray` to :class:`be masked`
   :param lat_key/lon_key:
   :type lat_key/lon_key: :class:`name` of :class:`the latitude/longitude variables in the coordinates object`
   :param fill:
   :type fill: :class:`value` to :class:`fill points which are not within the shape_list`, *default* :class:`is 0`
   :param dtype:
   :type dtype: :class:`datatype` of :class:`the returned mask`, *default* :class:`is `int``

   :returns: A mask where points not inside the shape_list are set to `fill` value
   :rtype: :class:`xr.DataArray`


.. py:function:: shapes_to_masks(shapes, target, regular=True, **kwargs)

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

   :param shapes (gpd.GeoDataFrame | list[gpd.GeoDataFrame]): containing the polygons for masks
   :type shapes (gpd.GeoDataFrame | list[gpd.GeoDataFrame]): :class:`A geodataframe` or :class:`list` of :class:`geodataframes`
   :param target (xarray.DataArray):
   :type target (xarray.DataArray): :class:`A dataarray` to :class:`to create a mask for`, :class:`only the geospatial coordinates are used`
   :param regular (bool): if False use mask_contains_points
   :type regular (bool): :class:`If True`, :class:`data is on a regular grid so use rasterize method,`
   :param all_touched (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.
   :param kwargs:
   :type kwargs: :class:`kwargs accepted by the masking methods`, :class:`rasterize` or :class:`mask_contains_points`

   :returns: A list of masks where points inside each geometry are 1, and those outside are np.nan
   :rtype: :class:`list[xr.DataArray]`


.. py:function:: 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.

   :param shapes (gpd.GeoDataFrame | list[gpd.GeoDataFrame]): containing the polygons for masks
   :type shapes (gpd.GeoDataFrame | list[gpd.GeoDataFrame]): :class:`A geodataframe` or :class:`list` of :class:`geodataframes`
   :param target (xarray.DataArray):
   :type target (xarray.DataArray): :class:`A dataarray` to :class:`to create a mask for`, :class:`only the geospatial coordinates are used`
   :param regular (bool): if False use mask_contains_points
   :type regular (bool): :class:`If True`, :class:`data is on a regular grid so use rasterize method,`
   :param all_touched (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.
   :param kwargs:
   :type kwargs: :class:`kwargs accepted by the masking methods`, :class:`rasterize` or :class:`mask_contains_points`

   :returns: A mask where points inside any geometry are 1, and those outside are np.nan
   :rtype: :class:`xr.DataArray`


.. py:function:: get_mask_dim_index(mask_dim, geodataframe, default_index_name = 'index')

.. py:function:: 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

   :param dataarray: Xarray data object (must have geospatial coordinates).
   :type dataarray: :class:`xr.Dataset | xr.DataArray`
   :param geodataframe (optional): Geopandas Dataframe containing the polygons for aggregations
   :type geodataframe (optional): :class:`gpd.geodataframe.GeoDataFrame`
   :param lat_key/lon_key (optional): key for latitude/longitude variable, default behaviour is to detect variable keys.
   :type lat_key/lon_key (optional): :class:`str`
   :param all_touched (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.
   :rtype: :class:`xr.Dataset | xr.DataArray`


.. py:function:: 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.

   :param dataarray: Xarray data object (must have geospatial coordinates).
   :param geodataframe: Geopandas Dataframe containing the polygons for aggregations
   :param mask_dim (optional): dimension that will be created to accomodate the masked arrays, default is the index
                               of the geodataframe
   :param all_touched (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.
   :param lat_key/lon_key (optional): key for latitude/longitude variable, default behaviour is to detect variable keys.
   :param chunk: 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.
   :type chunk: :class:`(optional) bool`

   :returns: A masked data array with dimensions [feautre_id] + [data.dims].
             Each slice of layer corresponds to a feature in layer.
   :rtype: :class:`xr.Dataset | xr.DataArray`


.. py:function:: 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.

   :param dataarray: Xarray data object (must have geospatial coordinates).
   :param geodataframe: Geopandas Dataframe containing the polygons for aggregations
   :param how (optional): method used to apply mask. Default='mean', which calls np.nanmean
   :param weights (optional): Provide weights for aggregation, also accepts recognised keys for weights, e.g.
                              'latitude'
   :param lat_key/lon_key (optional): key for latitude/longitude variable, default behaviour is to detect variable keys.
   :param extra_reduce_dims (optional): any additional dimensions to aggregate over when reducing over spatial dimensions
   :param mask_dim (optional): dimension that will be created after the reduction of the spatial dimensions, default is the index
                               of the dataframe
   :param all_touched (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.
   :param mask_kwargs (optional): Any kwargs to pass into the mask method
   :param return_as (optional): what format to return the data object, `pandas` or `xarray`. Work In Progress
   :param how_label (optional): label to append to variable name in returned object, default is not to append
   :param kwargs (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.
   :rtype: :class:`xr.Dataset | xr.DataArray`