apply_dimension.json

{
    "id": "apply_dimension",
    "summary": "Apply a process to all values along a dimension",
    "description": "Applies a process to all values along a dimension of a data cube. For example, if the temporal dimension is specified the process will work on the values of a time series.\n\nThe process ``reduce_dimension()`` also applies a process to values along a dimension, but drops the dimension afterwards. The process ``apply()`` applies a process to each value in the data cube.\n\nThe target dimension is the source dimension if not specified otherwise in the `target_dimension` parameter. The values in the target dimension get replaced by the computed values. The name, type and reference system are preserved.\n\nThe dimension labels are preserved when the target dimension is the source dimension and the number of values in the source dimension is equal to the number of values computed by the process. Otherwise, the dimension labels will be incrementing integers starting from zero, which can be changed using ``rename_labels()`` afterwards. The number of labels will be equal to the number of values computed by the process.",
    "categories": [
        "cubes"
    ],
    "parameters": [
        {
            "name": "data",
            "description": "A data cube.",
            "schema": {
                "type": "object",
                "subtype": "datacube"
            }
        },
        {
            "name": "process",
            "description": "Process to be applied on all values along the given dimension. The specified process needs to accept an array and must return an array with at least one element. A process may consist of multiple sub-processes.",
            "schema": {
                "type": "object",
                "subtype": "process-graph",
                "parameters": [
                    {
                        "name": "data",
                        "description": "A labeled array with elements of any type.",
                        "schema": {
                            "type": "array",
                            "subtype": "labeled-array",
                            "items": {
                                "description": "Any data type."
                            }
                        }
                    },
                    {
                        "name": "context",
                        "description": "Additional data passed by the user.",
                        "schema": {
                            "description": "Any data type."
                        },
                        "optional": true,
                        "default": null
                    }
                ],
                "returns": {
                    "description": "The value to be set in the new data cube.",
                    "schema": {
                        "type": "array",
                        "items": {
                            "description": "Any data type."
                        }
                    }
                }
            }
        },
        {
            "name": "dimension",
            "description": "The name of the source dimension to apply the process on. Fails with a `DimensionNotAvailable` exception if the specified dimension does not exist.",
            "schema": {
                "type": "string"
            }
        },
        {
            "name": "target_dimension",
            "description": "The name of the target dimension or `null` (the default) to use the source dimension specified in the parameter `dimension`.\n\nBy specifying a target dimension, the source dimension is removed. The target dimension with the specified name and the type `other` (see ``add_dimension()``) is created, if it doesn't exist yet.",
            "schema": {
                "type": [
                    "string",
                    "null"
                ]
            },
            "default": null,
            "optional": true
        },
        {
            "name": "context",
            "description": "Additional data to be passed to the process.",
            "schema": {
                "description": "Any data type."
            },
            "optional": true,
            "default": null
        }
    ],
    "returns": {
        "description": "A data cube with the newly computed values.\n\nAll dimensions stay the same, except for the dimensions specified in corresponding parameters. There are three cases how the dimensions can change:\n\n1. The source dimension is the target dimension:\n   - The (number of) dimensions remain unchanged as the source dimension is the target dimension.\n   - The source dimension properties name and type remain unchanged.\n   - The dimension labels, the reference system and the resolution are preserved only if the number of values in the source dimension is equal to the number of values computed by the process. Otherwise, all other dimension properties change as defined in the list below.\n2. The source dimension is not the target dimension. The target dimension exists with a single label only:\n   - The number of dimensions decreases by one as the source dimension is 'dropped' and the target dimension is filled with the processed data that originates from the source dimension.\n   - The target dimension properties name and type remain unchanged. All other dimension properties change as defined in the list below.\n3. The source dimension is not the target dimension and the latter does not exist:\n   - The number of dimensions remain unchanged, but the source dimension is replaced with the target dimension.\n   - The target dimension has the specified name and the type other. All other dimension properties are set as defined in the list below.\n\nUnless otherwise stated above, for the given (target) dimension the following applies:\n\n- the number of dimension labels is equal to the number of values computed by the process,\n- the dimension labels are incrementing integers starting from zero,\n- the resolution changes, and\n- the reference system is undefined.",
        "schema": {
            "type": "object",
            "subtype": "datacube"
        }
    },
    "exceptions": {
        "DimensionNotAvailable": {
            "message": "A dimension with the specified name does not exist."
        }
    },
    "links": [
        {
            "href": "https://openeo.org/documentation/1.0/datacubes.html#apply",
            "rel": "about",
            "title": "Apply explained in the openEO documentation"
        }
    ]
}