Change behavior of apply_dimension and reduce

CHANGELOG.md

@@ -23,11 +23,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Default values are now specified on the parameter-level, not in the JSON schemas.
 - Processes supporting multiple data types in parameters or return values with `anyOf` are now listing the data types directly as array. `anyOf` is discouraged.
 - `add_dimension`: Parameter `value` renamed to `label`.
+- `apply_dimension`: Replaced with a completely new definition. [#73](https://github.com/Open-EO/openeo-processes/issues/73)
 - `clip`: Works on a single value instead on arrays (replaced parameter `data` with `x`). [#75](https://github.com/Open-EO/openeo-processes/issues/75)
 - `debug`: Replaced with a completely new definition. [#82](https://github.com/Open-EO/openeo-processes/issues/71), [API#100](https://github.com/Open-EO/openeo-api/issues/100), [API#214](https://github.com/Open-EO/openeo-api/issues/214)
 - `filter_bands`: Merged parameters `bands` and `common_names`. [#77]( https://github.com/Open-EO/openeo-processes/issues/77)
 - `load_collection`: Parameter `bands` accepts common band names. [#77]( https://github.com/Open-EO/openeo-processes/issues/77)
 - `ndvi` and `normalized_difference`: Rewrite of the processes with a completely new behavior. [#60](https://github.com/Open-EO/openeo-processes/issues/60)
+- `reduce`: Reducers can't return multiple values any longer. Parameter `target_dimension` was therefore removed. [#73](https://github.com/Open-EO/openeo-processes/issues/73)
 - `resample_spatial`: Default value of parameter `align` changed from `lower-left` to `upper-left`. [#61](https://github.com/Open-EO/openeo-processes/issues/61)
 - The following operations work on two values instead on a sequence of values: `and`, `divide`, `multiply`, `or`, `subtract`, `xor`. [#85](https://github.com/Open-EO/openeo-processes/issues/85)
 - `product` works as before, but is not an alias of `multiply` any longer. [#85](https://github.com/Open-EO/openeo-processes/issues/85)

apply.json

@@ -1,7 +1,7 @@
 {
     "id": "apply",
-    "summary": "Applies a unary process to each pixel",
-    "description": "Applies a **unary** process which takes a single value such as `abs` or `sqrt` to each pixel value in the data cube (i.e. a local operation). In contrast, the process ``apply_dimension()`` applies an n-ary process to a particular dimension.",
+    "summary": "Applies a process to each pixel",
+    "description": "Applies a *unary* process to all pixel values in the data cube (i.e. a local operation). A unary process takes a single value and returns a single value, for example ``abs()`` or ``linear_scale_range()``. In contrast, the process ``apply_dimension()`` applies a process to all pixels along a particular dimension.",
     "categories": [
         "cubes"
     ],
@@ -19,7 +19,7 @@
             "required": true
         },
         "process": {
-            "description": "A process to be applied on each value, may consist of multiple sub-processes. The specified process must be unary meaning that it must work on a single value.",
+            "description": "A unary process to be applied on each value, may consist of multiple sub-processes.",
             "schema": {
                 "type": "object",
                 "subtype": "process-graph",

apply_dimension.json

@@ -1,14 +1,15 @@
 {
     "id": "apply_dimension",
-    "summary": "Applies an n-ary process to all pixels",
-    "description": "Applies an **n-ary** process (i.e. takes an array of pixel values instead of a single pixel value) to a raster data cube. In contrast, the process ``apply()`` applies an unary process to all pixel values.\n\nBy default, `apply_dimension` applies the process on all pixel values in the data cube as ``apply()`` does, but the parameter `dimension` can be specified to work only on a particular dimension only. For example, if the temporal dimension is specified the process will work on a time series of pixel values.\n\nThe n-ary process must return as many elements in the returned array as there are in the input array. Otherwise a `CardinalityChanged` error must be returned.",
+    "summary": "Applies a process to pixels along a dimension",
+    "description": "Applies a process to all pixel values along a dimension of a raster data cube. For example, if the temporal dimension is specified the process will work on a time series of pixel values.\n\nBy default, the dimension is replaced with a dimension of the same type. The dimension will result in as many enumerated dimension labels as array elements are available afterwards. Enumerated dimension labels start from zero.\n\nThe process ``reduce()`` also applies a process to pixel values along a dimension, but removes the dimension afterwards. The process ``apply()`` applies a process to all pixel values in the data cube.",
     "categories": [
         "cubes"
     ],
     "parameter_order": [
         "data",
         "process",
-        "dimension"
+        "dimension",
+        "target_dimension"
     ],
     "parameters": {
         "data": {
@@ -20,7 +21,7 @@
             "required": true
         },
         "process": {
-            "description": "Process to be applied on each dimension. The specified process needs to accept an array as parameter and must return as many elements in the returned array as there are in the input array. A process may consist of multiple sub-processes.",
+            "description": "Process to be applied on each dimension. The specified process needs to accept an array as parameter and must return an array with least one element. A process may consist of multiple sub-processes.",
             "schema": {
                 "type": "object",
                 "subtype": "process-graph",
@@ -37,7 +38,14 @@
             "required": true
         },
         "dimension": {
-            "description": "The name of the dimension to apply the process on. By default, applies the process on all pixel values (as ``apply()`` does).",
+            "description": "The name of the dimension to apply the process on. Fails with a `DimensionNotAvailable` error if the specified dimension does not exist.",
+            "schema": {
+                "type": "string"
+            },
+            "required": true
+        },
+        "target_dimension": {
+            "description": "The name of the target dimension or `null` to replace the dimension specified in `dimension` (default).\n\nIf a target dimension is specified, a new dimension with the specified name and the type `other` (see ``add_dimension()``) is created. If a dimension with the specified name exists, the dimension is replaced, but keeps the original type.\n\nThe resulting target dimension has as many dimension labels as the array returned by the process has values. For example, a process returning an array with four elements results in a dimension with four labels.",
             "schema": {
                 "type": [
                     "string",
@@ -55,9 +63,6 @@
         }
     },
     "exceptions": {
-        "CardinalityChanged": {
-            "message": "The process specified for parameter 'process' returned less or more elements than it received."
-        },
         "DimensionNotAvailable": {
             "message": "A dimension with the specified name does not exist."
         }

extrema.json

@@ -3,8 +3,7 @@
     "summary": "Minimum and maximum values",
     "description": "Two element array containing the minimum and the maximum values of `data`.\n\nThis process is basically an alias for calling both ``min()`` and ``max()``, but may be implemented more performant by back-ends as it only needs to iterate over the data once instead of twice.",
     "categories": [
-        "math",
-        "reducer"
+        "math"
     ],
     "parameter_order": [
         "data",

quantiles.json

@@ -3,8 +3,7 @@
     "summary": "Quantiles",
     "description": "Calculates quantiles, which are cut points dividing the range of a probability distribution into either\n\n* intervals corresponding to the given `probabilities` or\n* (nearly) equal-sized intervals (q-quantiles based on the parameter `q`).\n\nEither the parameter `probabilites` or `q` must be specified, otherwise the `QuantilesParameterMissing` exception must be thrown. If both parameters are set the `QuantilesParameterConflict` exception must be thrown.",
     "categories": [
-        "math",
-        "reducer"
+        "math"
     ],
     "parameter_order": [
         "data",

reduce.json

@@ -1,7 +1,7 @@
 {
     "id": "reduce",
     "summary": "Reduce dimensions",
-    "description": "Applies a reducer to a data cube dimension by collapsing all the input values along the specified dimension into an output value computed by the reducer.\n\nBy default the dimension is dropped, but this behaviour can be influenced with the parameter `target_dimension` The parameter must be specified, if a reducer such as ``extrema()`` returns multiple values.\n\nBy default, a reducer must accept an array as input. The process can also work on two values by setting the parameter `binary` to `true`. The reducer doesn't get executed on a single value.",
+    "description": "Applies a reducer to a data cube dimension by collapsing all the pixel values along the specified dimension into an output value computed by the reducer. The dimension is dropped. To avoid dropping the dimension, use ``apply_dimension()`` instead.\n\nA reducer is a single process or a set of processes, which computes a single value for a list of values, see the category 'reducer' for such processes.\n\nThe process can also work on two values by setting the parameter `binary` to `true`. In this case, the reducer doesn't get executed on a single value.",
     "categories": [
         "cubes",
         "reducer"
@@ -10,7 +10,6 @@
         "data",
         "reducer",
         "dimension",
-        "target_dimension",
         "binary"
     ],
     "parameters": {
@@ -23,7 +22,7 @@
             "required": true
         },
         "reducer": {
-            "description": "A reducer to apply on the specified dimension.\n\nThe reducer may be a single process such as ``mean()`` or consist of multiple sub-processes. By default, a reducer must accept an array as input, but the reducer can also work on two values by setting the parameter `binary` to `true`.\n\nThe reducer must compute either a single value or multiple return values. Multiple values returned by a reducer must be wrapped in an array and will result in as many enumerated dimension labels as array elements are available. Enumerated dimension labels start from zero.",
+            "description": "A reducer to apply on the specified dimension.\n\nThe reducer may be a single process such as ``mean()`` or consist of multiple sub-processes. By default, a reducer must accept an array as input, but the reducer can also work on two values by setting the parameter `binary` to `true`.\n\nThe reducer must compute a single value.",
             "required": true,
             "schema": [
                 {
@@ -64,16 +63,6 @@
             },
             "required": true
         },
-        "target_dimension": {
-            "description": "The name of the target dimension or `null` to drop the dimension (default).\n\nIf a target dimension is specified, a new dimension with the specified name and the type `other` (see ``add_dimension()``) is created and the old dimension is dropped. If a dimension with the specified name exists, the dimension is replaced, but keeps the original type.\n\nThe resulting target dimension has as many dimension labels as the reducer returned values. For example, a reducer returning a single scalar results in a dimension with a single label, a reducer returning an array with four elements results in a dimension with four labels.\n\nIf a reducer returns multiple values, this parameter is required to be a string. Otherwise the process produces the error `TargetDimensionMissing`.",
-            "schema": {
-                "type": [
-                    "string",
-                    "null"
-                ]
-            },
-            "default": null
-        },
         "binary": {
             "description": "Specifies whether the process should pass two values to the reducer (binary mode) or a list of values (default).\n\nIf the process passes two values to the reducer, the reducer must be both associative and commutative as the execution may be executed in parallel and therefore the order of execution is arbitrary.\n\nThis parameter is especially useful for UDFs passed as reducers. Back-ends may still optimize and parallelize processes that work on list of values.",
             "schema": {
@@ -83,7 +72,7 @@
         }
     },
     "returns": {
-        "description": "A data cube with the newly computed values. The number of dimensions is reduced by one, except if a target dimension is specified. The resolution and cardinality are the same as for the original data cube.",
+        "description": "A data cube with the newly computed values. The number of dimensions is reduced by one. The resolution and cardinality are the same as for the original data cube.",
         "schema": {
             "type": "object",
             "subtype": "raster-cube"
@@ -92,9 +81,6 @@
     "exceptions": {
         "DimensionNotAvailable": {
             "message": "A dimension with the specified name does not exist."
-        },
-        "TargetDimensionMissing": {
-            "message": "The reducer returned multiple values. A target dimension must be specified."
         }
     },
     "links": [