Merge branch 'draft' into is-nan

Author: m-mohr

CHANGELOG.md

@@ -9,36 +9,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Implementation guide for implementing OGC API - Processes in openEO
-- `export_collection`
-- `export_workspace`
-- `run_ogcapi`
-- `run_ogcapi_externally`
-- `stac_modify`
+- `date_difference`: Allow `week` as a unit [#506](https://github.com/Open-EO/openeo-processes/issues/506)
+- `export_collection`: New process
+- `export_workspace`: New process
+- `run_ogcapi`: New process
+- `run_ogcapi_externally`: New process
+- `stac_modify`: New process
+- `text_find`: New process
 
 ### Changed
 
+- Processes that have been marked as stable: `apply_polygon`, `date_between`, `date_shift`, `filter_labels`, `inspect`
+- Clarified for various mathematical functions the defined input and output ranges.
+  Mention that `NaN` is returned outside of the defined input range where possible.
+- Clarified for several comparison processes how `NaN` values have to be handled. 
+- Clarified for various processes the handling of no-data values and `null`, see also the [implementation guide](meta/implementation.md#no-data-value).  [#480](https://github.com/Open-EO/openeo-processes/issues/480)
+- Added a [section about character encodings to the implementation guide](meta/implementation.md#character-encoding).
+  Removed any character encoding related wording from the process specifications itself.
+- Added a uniqueness contraint to various array-typed parameters (e.g. lists of dimension names or labels)
 - `apply_polygon`: Renamed `polygons` parameter to `geometries` for better alignment with other geometry handling processes. [#511](https://github.com/Open-EO/openeo-processes/issues/511)
-- `is_nan`: Return `false` instead of `true` for non-numerical data types. [#486](https://github.com/Open-EO/openeo-processes/issues/486)
 - `clip`: Throw an exception if min > max [#472](https://github.com/Open-EO/openeo-processes/issues/472)
+- `is_nan`: Return `false` instead of `true` for non-numerical data types. [#486](https://github.com/Open-EO/openeo-processes/issues/486)
 - `save_results`: Returns the STAC resource instead of boolean `true` [API#376](https://github.com/Open-EO/openeo-api/issues/376)
-- Added a uniqueness contraint to various array-typed parameters (e.g. lists of dimension names or labels)
 
 ### Fixed
 
 - Clarified for various mathematical functions the defined input and output ranges. Mention that `NaN` is returned outside of the defined input range where possible.
+- Clarified for various processes the handling of no-data values and null, see also the [implementation guide](meta/implementation.md).  [#480](https://github.com/Open-EO/openeo-processes/issues/480)
+- `add_dimension`: Clearly define behaviour for adding spatial dimensions
 - `apply_polygon`: Replaced outdated usage of `raster-cube` subtype with `datacube` and dimensions. [#524](https://github.com/Open-EO/openeo-processes/issues/524)
 - `aggregate_spatial` and `load_geojson`: Dimensions must by of type `geometry`, not `geometries`
+- `aggregate_spatial`: Clarified that the output geometries are unchanged compared to the input geometries. [#499](https://github.com/Open-EO/openeo-processes/issues/499)
 - `aggregate_temporal` and `aggregate_temporal_period`: Clarified that the process throws a `DimensionNotAvailable` exception when no temporal dimension exists.
-- `aggregate_temporal_period`: Removed unused exception `DistinctDimensionLabelsRequired`
-- `aggregate_temporal_period`: Clarified that the definition of weeks follows ISO 8601
+- `aggregate_temporal_period`: Removed unused exception `DistinctDimensionLabelsRequired`.
+- `aggregate_temporal_period`: Clarified that the definition of weeks follows ISO 8601.
+- `apply_polygon`: Replaced outdated usage of `raster-cube` subtype with `datacube` and dimensions. [#524](https://github.com/Open-EO/openeo-processes/issues/524)
+- `array_interpolate_linear`: Apply interpolation to NaN and no-data values.
 - `cummax`, `cummin`, `cumproduct`, `cumsum`: Clarified the descriptions around the `ignore_nodata` parameter.
 - `divide`: Clarified behavior for division by 0
 - `between`: Clarify that `null` is passed through.
 - `eq` and `neq`: Explicitly set the minimum value for the `delta` parameter.
 - `filter_bbox`, `load_collection`, `load_stac`: Clarified that the bounding box is reprojected to the CRS of the spatial data cube dimensions if required.
 - `filter_spatial`: Clarified that masking is applied using the given geometries. [#469](https://github.com/Open-EO/openeo-processes/issues/469)
-- `load_collection` and `load_stac`: Clarified that scale and offset are not applied automatically when loading the data. [#503](https://github.com/Open-EO/openeo-processes/issues/503)
+- `load_collection` and `load_stac`:
+    - Clarified that scale and offset are not applied automatically when loading the data. [#503](https://github.com/Open-EO/openeo-processes/issues/503)
+    - Clarify the dimension naming and the order of dimension labels for nominal labels. [#488](https://github.com/Open-EO/openeo-processes/issues/488), [#489](https://github.com/Open-EO/openeo-processes/issues/489)
+- `load_stac`: Clarify handling of the `properties` parameter in the context of STAC APIs and static catalogs. [#536](https://github.com/Open-EO/openeo-processes/issues/536)
+- `load_uploaded_files` and `run_udf`: Clarify handling of file paths and added `FileNotFound` exception. [#461](https://github.com/Open-EO/openeo-processes/issues/461)
+- `mask`: Add missing exception `IncompatibleDataCubes` [#538](https://github.com/Open-EO/openeo-processes/issues/538)
 - `mod`: Clarified behavior for y = 0
+- `run_udf`: Simplified and clarified the schema for `data` - no functional change.
 - `sqrt`: Clarified that NaN is returned for negative numbers.
 - Clarify allowed `FeatureCollection` geometries in `load_collection`, `mask_polygon`, `apply_polygon`, and `load_stac` [#527](https://github.com/Open-EO/openeo-processes/issues/527)
 

README.md

@@ -40,7 +40,7 @@ This repository contains a set of files formally describing the openEO Processes
 ## Process
 
 * All new processes must be added to the [`proposals`](proposals/) folder.
-* Processes will only be moved from proposals to the stable process specifications once there are at least two implementations and an example process in the [`openEO community examples`](https://github.com/Open-EO/openeo-community-examples/) showing it in a use case. This doesn't require a PSC vote individually as it's not a breaking change, just an addition.
+* Processes will only be moved from proposals to the stable process specifications once there are at least two implementations and an example process in the [`openEO community examples`](https://github.com/Open-EO/openeo-community-examples/) showing it in a use case. Ideally, there are also no open issues. The move doesn't require a PSC vote individually as it's not a breaking change, just an addition.
 * The [`proposals`](proposals/) folder allows breaking changes without a PSC vote and without increasing the major version number (i.e. a breaking change in the proposals doesn't require us to make the next version number 2.0.0).
 * The proposals are released as experimental processes with the other processes.
 * Each release and all breaking changes in the stable process specifications must go through PSC vote.

absolute.json

@@ -1,7 +1,7 @@
 {
     "id": "absolute",
     "summary": "Absolute value",
-    "description": "Computes the absolute value of a real number `x`, which is the \"unsigned\" portion of `x` and often denoted as *|x|*.\n\nThe no-data value `null` is passed through and therefore gets propagated.",
+    "description": "Computes the absolute value of a real number `x`, which is the \"unsigned\" portion of `x` and often denoted as *|x|*.\n\nNo-data values are passed through.",
     "categories": [
         "math"
     ],

add.json

@@ -1,7 +1,7 @@
 {
     "id": "add",
     "summary": "Addition of two numbers",
-    "description": "Sums up the two numbers `x` and `y` (*`x + y`*) and returns the computed sum.\n\nNo-data values are taken into account so that `null` is returned if any element is such a value.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it.",
+    "description": "Sums up the two numbers `x` and `y` (*`x + y`*) and returns the computed sum.\n\nNo-data values are taken into account so that the no-data value is returned if any element is such a value.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it.",
     "categories": [
         "math"
     ],
@@ -88,4 +88,4 @@
             "result": true
         }
     }
-}
+}

add_dimension.json

@@ -35,7 +35,7 @@
         },
         {
             "name": "type",
-            "description": "The type of dimension, defaults to `other`.",
+            "description": "The type of dimension, defaults to `other`.\n\nIf the type is `spatial`, the axis is the first option that does not exist yet from `x`, `y`, and `z`. This refers to the axis of the dimension, not the name of the dimension. Throws a `DimensionExists` exception if dimensions for all axes exist.",
             "schema": {
                 "type": "string",
                 "enum": [

aggregate_spatial.json

@@ -105,7 +105,7 @@
         }
     ],
     "returns": {
-        "description": "A vector data cube with the computed results. Empty geometries still exist but without any aggregated values (i.e. no-data). The spatial dimensions are replaced by a dimension of type 'geometry' and if `target_dimension` is not `null`, a new dimension is added.",
+        "description": "A vector data cube with the computed results. Empty geometries still exist but without any aggregated values (i.e. no-data). The spatial dimensions are replaced by a dimension of type 'geometry' and if `target_dimension` is not `null`, a new dimension is added. The dimension of type `geometry` is unchanged compared to the geometries provided through the parameter `geometries`, especially with regards to its labels (geometries) and reference system.",
         "schema": {
             "type": "object",
             "subtype": "datacube",

aggregate_temporal.json

@@ -89,7 +89,7 @@
         },
         {
             "name": "reducer",
-            "description": "A reducer to be applied for the values contained in each interval. A reducer is a single process such as ``mean()`` or a set of processes, which computes a single value for a list of values, see the category 'reducer' for such processes. Intervals may not contain any values, which for most reducers leads to no-data (`null`) values by default.",
+            "description": "A reducer to be applied for the values contained in each interval. A reducer is a single process such as ``mean()`` or a set of processes, which computes a single value for a list of values, see the category 'reducer' for such processes. Intervals may not contain any values, which leads to a no-data value for most reducers by default.",
             "schema": {
                 "type": "object",
                 "subtype": "process-graph",

aggregate_temporal_period.json

@@ -42,7 +42,7 @@
         },
         {
             "name": "reducer",
-            "description": "A reducer to be applied for the values contained in each period. A reducer is a single process such as ``mean()`` or a set of processes, which computes a single value for a list of values, see the category 'reducer' for such processes. Periods may not contain any values, which for most reducers leads to no-data (`null`) values by default.",
+            "description": "A reducer to be applied for the values contained in each period. A reducer is a single process such as ``mean()`` or a set of processes, which computes a single value for a list of values, see the category 'reducer' for such processes. Periods may not contain any values, which leads to a no-data value for most reducers by default.",
             "schema": {
                 "type": "object",
                 "subtype": "process-graph",

all.json

@@ -1,7 +1,7 @@
 {
     "id": "all",
     "summary": "Are all of the values true?",
-    "description": "Checks if **all** of the values in `data` are true. If no value is given (i.e. the array is empty) the process returns `null`.\n\nBy default all no-data values are ignored so that the process returns `null` if all values are no-data, `true` if all values are true and `false` otherwise. Setting the `ignore_nodata` flag to `false` takes no-data values into account and the array values are reduced pairwise according to the following truth table:\n\n```\n      || null  | false | true\n----- || ----- | ----- | -----\nnull  || null  | false | null\nfalse || false | false | false\ntrue  || null  | false | true\n```\n\n**Remark:** The process evaluates all values from the first to the last element and stops once the outcome is unambiguous. A result is ambiguous unless a value is `false` or all values have been taken into account.",
+    "description": "Checks if **all** of the values in `data` are true. If no value is given (i.e. the array is empty) the process returns  the no-data value (or `null`).\n\nBy default all no-data values are ignored so that the process returns the no-data value (or `null`) if all values are no-data, `true` if all values are true and `false` otherwise. Setting the `ignore_nodata` flag to `false` takes no-data values into account and the array values are reduced pairwise according to the following truth table:\n\n```\n        || no-data | false | true\n------- || ------- | ----- | -------\nno-data || no-data | false | no-data\nfalse   || false   | false | false\ntrue    || no-data | false | true\n```\n\n**Remark:** The process evaluates all values from the first to the last element and stops once the outcome is unambiguous. A result is ambiguous unless a value is `false` or all values have been taken into account.",
     "categories": [
         "logic",
         "reducer"
@@ -22,7 +22,7 @@
         },
         {
             "name": "ignore_nodata",
-            "description": "Indicates whether no-data values are ignored or not and ignores them by default.",
+            "description": "Indicates whether no-data values are ignored or not. Ignores them by default.",
             "schema": {
                 "type": "boolean"
             },
@@ -131,4 +131,4 @@
             "returns": null
         }
     ]
-}
+}

and.json

@@ -1,7 +1,7 @@
 {
     "id": "and",
     "summary": "Logical AND",
-    "description": "Checks if **both** values are true.\n\nEvaluates parameter `x` before `y` and stops once the outcome is unambiguous. If any argument is `null`, the result will be `null` if the outcome is ambiguous.\n\n**Truth table:**\n\n```\nx \\ y || null  | false | true\n----- || ----- | ----- | -----\nnull  || null  | false | null\nfalse || false | false | false\ntrue  || null  | false | true\n```",
+    "description": "Checks if **both** values are true.\n\nEvaluates parameter `x` before `y` and stops once the outcome is unambiguous. If any argument is a no-data value, the result will be the no-data value whenever the outcome is ambiguous.\n\n**Truth table:**\n\n```\nx \\ y   || no-data | false | true\n------- || ------- | ----- | -------\nno-data || no-data | false | no-data\nfalse   || false   | false | false\ntrue    || no-data | false | true\n```",
     "categories": [
         "logic"
     ],