Source code for openeo.udf.udf_signatures

"""
This module defines a number of function signatures that can be implemented by UDF's.
Both the name of the function and the argument types are/can be used by the backend to validate if the provided UDF
is compatible with the calling context of the process graph in which it is used.

"""
# Note: this module was initially developed under the ``openeo-udf`` project (https://github.com/Open-EO/openeo-udf)

from pandas import Series

from openeo.metadata import CollectionMetadata
from openeo.udf.udf_data import UdfData
from openeo.udf.xarraydatacube import XarrayDataCube




def apply_timeseries(series: Series, context: dict) -> Series:
    """
    Process a timeseries of values, without changing the time instants.

    This can for instance be used for smoothing or gap-filling.

    :param series: A Pandas Series object with a date-time index.
    :param context: A dictionary containing user context.
    :return: A Pandas Series object with the same datetime index.
    """
    # TODO: do we need geospatial coordinates for the series?
    return series





def apply_datacube(cube: XarrayDataCube, context: dict) -> XarrayDataCube:
    """
    Map a :py:class:`XarrayDataCube` to another :py:class:`XarrayDataCube`.

    Depending on the context in which this function is used, the :py:class:`XarrayDataCube` dimensions
    have to be retained or can be chained.
    For instance, in the context of a reducing operation along a dimension,
    that dimension will have to be reduced to a single value.
    In the context of a 1 to 1 mapping operation, all dimensions have to be retained.

    :param cube: input data cube
    :param context: A dictionary containing user context.
    :return: output data cube
    """
    return cube





def apply_udf_data(data: UdfData):
    """
    Generic UDF function that directly manipulates a :py:class:`UdfData` object

    :param data: :py:class:`UdfData` object to manipulate in-place
    """
    pass





def apply_metadata(metadata: CollectionMetadata, context: dict) -> CollectionMetadata:
    """
    .. warning::
        This signature is not yet fully standardized and subject to change.

    Returns the expected cube metadata, after applying this UDF, based on input metadata.
    The provided metadata represents the whole raster or vector cube. This function does not need to be called for every data chunk.

    When this function is not implemented by the UDF, the backend may still be able to infer correct metadata by running the
    UDF, but this can result in reduced performance or errors.

    This function does not need to be provided when using the UDF in combination with processes that by design have a clear
    effect on cube metadata, such as :py:meth:`~openeo.rest.datacube.DataCube.reduce_dimension()`

    :param metadata: the collection metadata of the input data cube
    :param context: A dictionary containing user context.

    :return: output metadata: the expected metadata of the cube, after applying the udf

    Examples
    --------

    An example for a UDF that is applied on the 'bands' dimension, and returns a new set of bands with different labels.

    >>> def apply_metadata(metadata: CollectionMetadata, context: dict) -> CollectionMetadata:
    ...     return metadata.rename_labels(
    ...         dimension="bands",
    ...         target=["computed_band_1", "computed_band_2"]
    ...     )

    """
    pass