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

.. py:module:: transforms.spatial

.. autoapi-nested-parse::

   Spatial transformations for earthkit data objects.

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



Functions
---------

.. autoapisummary::

   transforms.spatial.mask
   transforms.spatial.reduce


Package Contents
----------------

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

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


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

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