Merge pull request #133 from Open-EO/callback-labels

Added support for labeled arrays
Open-EO · Jan 27, 2020 · f7d466d · f7d466d
2 parents e7fd9a5 + 6ea7049
commit f7d466d
Show file tree

Hide file tree

Showing 17 changed files with 136 additions and 30 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,17 +13,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - `all`
     - `any`
     - `array_apply`
+    - `array_contains`
     - `array_filter`
     - `array_find`
+    - `array_labels`
+    - `dimension_labels`
     - `drop_dimension`
     - `filter_labels`
-    - `labels`
     - `load_uploaded_files`
     - `mask_polygon`
     - `reduce_dimension`
     - `reduce_dimension_binary`
     - `rename_labels`
-- Added further examples
+- Support for labeled arrays. [API#245](https://github.com/Open-EO/openeo-api/issues/245)
+- Added further examples.
 
 ### Changed
 - The JSON Schema keyword `format` has been replaced with the custom keyword `subtype`.
@@ -35,9 +38,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Processes supporting multiple data types in parameters or return values with `anyOf` are now listing the data types directly as array. `anyOf` is discouraged.
 - Comparison processes `eq`, `gt`, `gte`, `lt`, `lte`, `neq` and `between` accept all data types as input for the operands.
 - `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)
+- `aggregate_polygon`, `aggregate_temporal`, `apply_dimension`, `array_element` and `resample_cube_temporal`: Support labeled arrays. [API#245](https://github.com/Open-EO/openeo-api/issues/245)
 - `aggregate_polygon`: The data cube implicitly gets restricted to the bounds of the polygons as if `filter_polygon` would have been used beforehand. [#101](https://github.com/Open-EO/openeo-processes/issues/101)
 - `aggregate_temporal`: Parameter `labels` is optional. [#19](https://github.com/Open-EO/openeo-processes/issues/19)
+- `apply_dimension`: Replaced with a completely new definition. [#73](https://github.com/Open-EO/openeo-processes/issues/73)
 - `apply_kernel`: Only supported 2D kernels on the horizontal spatial dimensions. [#69](https://github.com/Open-EO/openeo-processes/issues/69)
 - `clip`: Works on a single value instead on arrays (replaced parameter `data` with `x`). [#75](https://github.com/Open-EO/openeo-processes/issues/75)
 - `count`: Renamed parameter `expression` to `condition`.
@@ -59,6 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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)
 - `text_begins`, `text_contains`, `text_ends`: `null` values are supported and get passed through.
+- `trim`: Renamed to `trim_cube`.
 
 ### Deprecated
 - `filter_bbox`, `load_collection`, `resample_spatial`: PROJ definitions are deprecated in favor of EPSG codes and WKT2. [#58](https://github.com/Open-EO/openeo-processes/issues/58)

diff --git a/aggregate_polygon.json b/aggregate_polygon.json
@@ -38,9 +38,10 @@
                 "parameters": [
                     {
                         "name": "data",
-                        "description": "An array with elements of any type.",
+                        "description": "A labeled array with values of any type.",
                         "schema": {
                             "type": "array",
+                            "subtype": "labeled-array",
                             "items": {
                                 "description": "Any data type."
                             }

diff --git a/aggregate_temporal.json b/aggregate_temporal.json
@@ -88,9 +88,10 @@
                 "parameters": [
                     {
                         "name": "data",
-                        "description": "An array with elements of any type.",
+                        "description": "A labeled array with elements of any type.",
                         "schema": {
                             "type": "array",
+                            "subtype": "labeled-array",
                             "items": {
                                 "description": "Any data type."
                             }

diff --git a/apply_dimension.json b/apply_dimension.json
@@ -23,9 +23,10 @@
                 "parameters": [
                     {
                         "name": "data",
-                        "description": "An array with elements of any type.",
+                        "description": "A labeled array with elements of any type.",
                         "schema": {
                             "type": "array",
+                            "subtype": "labeled-array",
                             "items": {
                                 "description": "Any data type."
                             }

diff --git a/array_apply.json b/array_apply.json
@@ -36,6 +36,23 @@
                         "schema": {
                             "type": "integer"
                         }
+                    },
+                    {
+                        "name": "label",
+                        "description": "The label of the current element being processed. Only populated for labeled arrays.",
+                        "schema": [
+                            {
+                                "type": "number"
+                            },
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "default": null,
+                        "optional": true
                     }
                 ]
             }

diff --git a/array_contains.json b/array_contains.json
@@ -1,7 +1,7 @@
 {
     "id": "array_contains",
     "summary": "Check whether the array contains a given value",
-    "description": "Checks whether the array specified for `data` contains the value specified in `value`. Returns `true` if there's a match, otherwise `false`.\n\n**Remarks:**\n\n* To get the index of the value found, use ``array_find()``.\n* All definitions for the process ``eq()`` regarding the comparison of values apply here as well. This includes that data types MUST be checked strictly, for example a string with the content *1* is not equal to the number *1*.\n* An integer *1* is equal to a floating point number *1.0* as `integer` is a sub-type of `number`. Still, this process may return unexpectedly `false` when comparing floating point numbers due to floating point inaccuracy in machine-based computation.\n* Temporal strings are treated as normal strings and MUST NOT be interpreted.",
+    "description": "Checks whether the array specified for `data` contains the value specified in `value`. Returns `true` if there's a match, otherwise `false`.\n\n**Remarks:**\n\n* To get the index or the label of the value found, use ``array_find()``.\n* All definitions for the process ``eq()`` regarding the comparison of values apply here as well. This includes that data types MUST be checked strictly, for example a string with the content *1* is not equal to the number *1*.\n* An integer *1* is equal to a floating point number *1.0* as `integer` is a sub-type of `number`. Still, this process may return unexpectedly `false` when comparing floating point numbers due to floating point inaccuracy in machine-based computation.\n* Temporal strings are treated as normal strings and MUST NOT be interpreted.",
     "categories": [
         "arrays",
         "comparison"

diff --git a/array_element.json b/array_element.json
@@ -1,7 +1,7 @@
 {
     "id": "array_element",
     "summary": "Get an element from an array",
-    "description": "Returns the element at the specified zero-based index from the array.",
+    "description": "Returns the element with the specified index or label from the array.\n\nEither the parameter `index` or `label` must be specified, otherwise the `ArrayElementParameterMissing` exception is thrown. If both parameters are set the `ArrayElementParameterConflict` exception is thrown.",
     "categories": [
         "arrays"
     ],
@@ -21,11 +21,25 @@
             "description": "The zero-based index of the element to retrieve.",
             "schema": {
                 "type": "integer"
-            }
+            },
+            "optional": true
+        },
+        {
+            "name": "label",
+            "description": "The label of the element to retrieve.",
+            "schema": [
+                {
+                    "type": "number"
+                },
+                {
+                    "type": "string"
+                }
+            ],
+            "optional": true
         },
         {
             "name": "return_nodata",
-            "description": "By default this process throws an `IndexOutOfBounds` exception if the index is invalid. If you want to return `null` instead, set this flag to `true`.",
+            "description": "By default this process throws an `ArrayElementNotAvailable` exception if the index or label is invalid. If you want to return `null` instead, set this flag to `true`.",
             "schema": {
                 "type": "boolean"
             },
@@ -40,8 +54,14 @@
         }
     },
     "exceptions": {
-        "IndexOutOfBounds": {
-            "message": "The array has no element with the specified index."
+        "ArrayElementNotAvailable": {
+            "message": "The array has no element with the specified index or label."
+        },
+        "ArrayElementParameterMissing": {
+            "message": "The process 'array_element' requires either the 'index' or 'labels' parameter to be set."
+        },
+        "ArrayElementParameterConflict": {
+            "message": "The process 'array_element' only allows that either the 'index' or the 'labels' parameter is set."
         }
     },
     "examples": [

diff --git a/array_filter.json b/array_filter.json
@@ -37,6 +37,23 @@
                         "schema": {
                             "type": "integer"
                         }
+                    },
+                    {
+                        "name": "label",
+                        "description": "The label of the current element being processed. Only populated for labeled arrays.",
+                        "schema": [
+                            {
+                                "type": "number"
+                            },
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "default": null,
+                        "optional": true
                     }
                 ]
             }

diff --git a/array_find.json b/array_find.json
@@ -1,7 +1,7 @@
 {
     "id": "array_find",
     "summary": "Get the index for a value in an array",
-    "description": "Checks whether the array specified for `data` contains the value specified in `value` and returns the zero-based index for the first match. If there's no match, `-1` is returned.\n\n**Remarks:**\n\n* To get a boolean value returned use ``array_contains()``.\n* All definitions for the process ``eq()`` regarding the comparison of values apply here as well. This includes that data types MUST be checked strictly, for example a string with the content *1* is not equal to the number *1*.\n* An integer *1* is equal to a floating point number *1.0* as `integer` is a sub-type of `number`. Still, this process may return unexpectedly `false` when comparing floating point numbers due to floating point inaccuracy in machine-based computation.\n* Temporal strings are treated as normal strings and MUST NOT be interpreted.",
+    "description": "Checks whether the array specified for `data` contains the value specified in `value` and returns the zero-based index for the first match. If there's no match, `null` is returned.\n\n**Remarks:**\n\n* To get a boolean value returned use ``array_contains()``.\n* All definitions for the process ``eq()`` regarding the comparison of values apply here as well. This includes that data types MUST be checked strictly, for example a string with the content *1* is not equal to the number *1*.\n* An integer *1* is equal to a floating point number *1.0* as `integer` is a sub-type of `number`. Still, this process may return unexpectedly `false` when comparing floating point numbers due to floating point inaccuracy in machine-based computation.\n* Temporal strings are treated as normal strings and MUST NOT be interpreted.",
     "categories": [
         "arrays"
     ],
@@ -25,11 +25,16 @@
         }
     ],
     "returns": {
-        "description": "Returns the index of the first element with the specified value. If no element was found, `-1` is returned.",
-        "schema": {
-            "type": "integer",
-            "minimum": -1
-        }
+        "description": "Returns the index of the first element with the specified value. If no element was found, `null` is returned.",
+        "schema": [
+            {
+                "type": "null"
+            },
+            {
+                "type": "integer",
+                "minimum": 0
+            }
+        ]
     },
     "examples": [
         {
@@ -52,7 +57,7 @@
                 ],
                 "value": "b"
             },
-            "returns": -1
+            "returns": null
         },
         {
             "arguments": {
@@ -63,7 +68,7 @@
                 ],
                 "value": "2"
             },
-            "returns": -1
+            "returns": null
         },
         {
             "arguments": {
@@ -94,7 +99,7 @@
                     2
                 ]
             },
-            "returns": -1
+            "returns": null
         },
         {
             "arguments": {
@@ -110,7 +115,7 @@
                 ],
                 "value": 2
             },
-            "returns": -1
+            "returns": null
         },
         {
             "arguments": {
@@ -126,7 +131,7 @@
                     "a": "b"
                 }
             },
-            "returns": -1
+            "returns": null
         }
     ]
 }
diff --git a/array_labels.json b/array_labels.json
@@ -0,0 +1,34 @@
+{
+    "id": "array_labels",
+    "summary": "Get the labels for an array",
+    "description": "Returns all labels for a labeled array in the data cube. The labels have the same order as in the array.",
+    "categories": [
+        "arrays"
+    ],
+    "parameters": [
+        {
+            "name": "data",
+            "description": "An array with labels.",
+            "schema": {
+                "type": "array",
+                "subtype": "labeled-array"
+            }
+        }
+    ],
+    "returns": {
+        "description": "The labels as array.",
+        "schema": {
+            "type": "array",
+            "items": {
+                "anyOf": [
+                    {
+                        "type": "number"
+                    },
+                    {
+                        "type": "string"
+                    }
+                ]
+            }
+        }
+    }
+}
diff --git a/labels.json → dimension_labels.json b/labels.json → dimension_labels.json
@@ -1,5 +1,5 @@
 {
-    "id": "labels",
+    "id": "dimension_labels",
     "summary": "Get the dimension labels",
     "description": "Returns all labels for a dimension in the data cube. The labels have the same order as in the data cube.",
     "categories": [

diff --git a/quantiles.json b/quantiles.json
@@ -1,7 +1,7 @@
 {
     "id": "quantiles",
     "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.",
+    "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 is thrown. If both parameters are set the `QuantilesParameterConflict` exception is thrown.",
     "categories": [
         "math"
     ],

diff --git a/reduce_dimension.json b/reduce_dimension.json
@@ -24,9 +24,10 @@
                 "parameters": [
                     {
                         "name": "data",
-                        "description": "An array with elements of any type.",
+                        "description": "A labeled array with elements of any type.",
                         "schema": {
                             "type": "array",
+                            "subtype": "labeled-array",
                             "items": {
                                 "description": "Any data type."
                             }

diff --git a/resample_cube_temporal.json b/resample_cube_temporal.json
@@ -32,9 +32,10 @@
                 "parameters": [
                     {
                         "name": "data",
-                        "description": "An array with elements of any type.",
+                        "description": "A labeled array with elements of any type.",
                         "schema": {
                             "type": "array",
+                            "subtype": "labeled-array",
                             "items": {
                                 "description": "Any data type."
                             }

diff --git a/tests/.words b/tests/.words
@@ -28,4 +28,5 @@ outputMin
 outputMax
 Sentinel-2
 Sentinel-2A
-Sentinel-2B
+Sentinel-2B
+labeled
diff --git a/tests/processes.test.js b/tests/processes.test.js
@@ -13,7 +13,8 @@ var summaryDotRegexp = /[^\.]$/;
 var files = glob.sync("../*.json", {realpath: true});
 
 var anyOfRequired = [
-  "quantiles"
+  "quantiles",
+  "array_element"
 ];
 
 var subtypes = {
@@ -34,6 +35,7 @@ var subtypes = {
 	'input-format-options': {type: 'object'},
 	'job-id': {type: 'string'},
 	'kernel': {type: 'array'},
+	'labeled-array': {type: 'array'},
 	'output-format': {type: 'string'},
 	'output-format-options': {type: 'object'},
 	'process-graph': {type: 'object'},

diff --git a/trim.json → trim_cube.json b/trim.json → trim_cube.json
@@ -1,5 +1,5 @@
 {
-    "id": "trim",
+    "id": "trim_cube",
     "summary": "Remove slices with no-data values",
     "description": "Removes slices solely containing no-data values. If the dimension is irregular categorical then slices in the middle can be removed.",
     "categories": [