From a3710ad96bf16934259da87f1d92be93930cf235 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 3 Jan 2024 14:01:54 +0100 Subject: [PATCH 1/3] Clarify no-data value / null for most processes #480 --- CHANGELOG.md | 14 ++++++----- absolute.json | 2 +- add.json | 4 ++-- aggregate_temporal.json | 2 +- aggregate_temporal_period.json | 2 +- all.json | 6 ++--- and.json | 2 +- any.json | 6 ++--- apply_neighborhood.json | 2 +- arccos.json | 2 +- arcosh.json | 2 +- arcsin.json | 2 +- arctan.json | 2 +- arctan2.json | 4 ++-- array_contains.json | 4 ++-- array_element.json | 4 ++-- array_find.json | 16 ++----------- array_interpolate_linear.json | 6 ++--- arsinh.json | 2 +- artanh.json | 2 +- between.json | 4 ++-- ceil.json | 4 ++-- clip.json | 2 +- cos.json | 2 +- cosh.json | 2 +- divide.json | 2 +- eq.json | 18 ++------------- exp.json | 2 +- extrema.json | 16 +++---------- filter_spatial.json | 2 +- first.json | 13 +++-------- floor.json | 4 ++-- gt.json | 11 ++------- gte.json | 11 ++------- if.json | 4 ++-- int.json | 4 ++-- is_nodata.json | 2 +- last.json | 13 +++-------- linear_scale_range.json | 2 +- ln.json | 2 +- load_collection.json | 4 ++-- log.json | 2 +- lt.json | 11 ++------- lte.json | 11 ++------- mask.json | 4 ++-- mask_polygon.json | 4 ++-- max.json | 13 +++-------- mean.json | 23 +++---------------- median.json | 23 +++---------------- merge_cubes.json | 2 +- meta/implementation.md | 22 ++++++++++++++++++ min.json | 6 ++--- mod.json | 2 +- multiply.json | 4 ++-- neq.json | 11 ++------- not.json | 4 ++-- or.json | 2 +- order.json | 2 +- power.json | 4 ++-- product.json | 6 ++--- proposals/aggregate_spatial_window.json | 2 +- proposals/apply_polygon.json | 2 +- .../ard_normalized_radar_backscatter.json | 4 ++-- proposals/ard_surface_reflectance.json | 4 ++-- proposals/atmospheric_correction.json | 2 +- proposals/cummax.json | 6 ++--- proposals/cummin.json | 6 ++--- proposals/cumproduct.json | 6 ++--- proposals/cumsum.json | 6 ++--- proposals/fit_curve.json | 2 +- proposals/load_geojson.json | 2 +- proposals/load_stac.json | 4 ++-- proposals/predict_curve.json | 2 +- proposals/sar_backscatter.json | 4 ++-- proposals/vector_to_random_points.json | 2 +- quantiles.json | 2 +- resample_cube_temporal.json | 4 ++-- resample_spatial.json | 2 +- round.json | 2 +- sd.json | 13 +++-------- sgn.json | 2 +- sin.json | 2 +- sinh.json | 2 +- sort.json | 2 +- sqrt.json | 2 +- subtract.json | 4 ++-- sum.json | 6 ++--- tan.json | 2 +- tanh.json | 2 +- text_begins.json | 2 +- text_contains.json | 2 +- text_ends.json | 2 +- variance.json | 13 +++-------- xor.json | 2 +- 94 files changed, 186 insertions(+), 302 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a301787..f4811eee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,21 +8,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed -- `clip`: Throw an exception if min > max [#472](https://github.com/Open-EO/openeo-processes/issues/472) +- 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) - Added a uniqueness contraint to various array-typed parameters (e.g. lists of dimension names or labels) +- `array_interpolate_linear`: Apply interpolation to NaN and no-data values. +- `clip`: Throw an exception if min > max. [#472](https://github.com/Open-EO/openeo-processes/issues/472) ### 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. - `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 -- `divide`: Clarified behavior for division by 0 +- `aggregate_temporal_period`: Removed unused exception `DistinctDimensionLabelsRequired`. +- `aggregate_temporal_period`: Clarified that the definition of weeks follows ISO 8601. +- `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) -- `mod`: Clarified behavior for y = 0 +- `mod`: Clarified behavior for y = 0. - `sqrt`: Clarified that NaN is returned for negative numbers. ## [2.0.0-rc.1] - 2023-05-25 diff --git a/absolute.json b/absolute.json index c6a3713d..fa5d003f 100644 --- a/absolute.json +++ b/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 and therefore get propagated.", "categories": [ "math" ], diff --git a/add.json b/add.json index ac65541c..434e6ba5 100644 --- a/add.json +++ b/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 } } -} \ No newline at end of file +} diff --git a/aggregate_temporal.json b/aggregate_temporal.json index 2c66e0f2..5576a7e4 100644 --- a/aggregate_temporal.json +++ b/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", diff --git a/aggregate_temporal_period.json b/aggregate_temporal_period.json index 446afa8d..cc0c4161 100644 --- a/aggregate_temporal_period.json +++ b/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", diff --git a/all.json b/all.json index b12059de..2e8bec38 100644 --- a/all.json +++ b/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 `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 } ] -} \ No newline at end of file +} diff --git a/and.json b/and.json index 3b28c8ef..87c21f01 100644 --- a/and.json +++ b/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" ], diff --git a/any.json b/any.json index 545c1669..f54c9cf4 100644 --- a/any.json +++ b/any.json @@ -1,7 +1,7 @@ { "id": "any", "summary": "Is at least one value true?", - "description": "Checks if **any** (i.e. at least one) value in `data` is `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 at least one value is 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 | null | true\nfalse || null | false | true\ntrue || true | true | 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 `true`.", + "description": "Checks if **any** (i.e. at least one) value in `data` is `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 the no-data value (or `null`) if all values are no-data, `true` if at least one value is 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 | no-data | true\nfalse || no-data | false | true\ntrue || true | true | 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 `true`.", "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 } ] -} \ No newline at end of file +} diff --git a/apply_neighborhood.json b/apply_neighborhood.json index 87f2b1dd..dd7a89d9 100644 --- a/apply_neighborhood.json +++ b/apply_neighborhood.json @@ -1,7 +1,7 @@ { "id": "apply_neighborhood", "summary": "Apply a process to pixels in a n-dimensional neighborhood", - "description": "Applies a focal process to a data cube.\n\nA focal process is a process that works on a 'neighborhood' of pixels. The neighborhood can extend into multiple dimensions, this extent is specified by the `size` argument. It is not only (part of) the size of the input window, but also the size of the output for a given position of the sliding window. The sliding window moves with multiples of `size`.\n\nAn overlap can be specified so that neighborhoods can have overlapping boundaries. This allows for continuity of the output. The overlap region must be included in the data cube or array returned by `process`, but any changed values will be ignored. The missing overlap at the borders of the original data cube is made available as no-data (`null`) in the sub-data cubes.\n\nThe neighborhood size should be kept small enough, to avoid running beyond computational resources, but a too-small size will result in a larger number of process invocations, which may slow down processing. Window sizes for spatial dimensions typically range from 64 to 512 pixels, while overlaps of 8 to 32 pixels are common.\n\nFor the special case of 2D convolution, it is recommended to use ``apply_kernel()``.", + "description": "Applies a focal process to a data cube.\n\nA focal process is a process that works on a 'neighborhood' of pixels. The neighborhood can extend into multiple dimensions, this extent is specified by the `size` argument. It is not only (part of) the size of the input window, but also the size of the output for a given position of the sliding window. The sliding window moves with multiples of `size`.\n\nAn overlap can be specified so that neighborhoods can have overlapping boundaries. This allows for continuity of the output. The overlap region must be included in the data cube or array returned by `process`, but any changed values will be ignored. The missing overlap at the borders of the original data cube is made available as no-data values in the sub-data cubes.\n\nThe neighborhood size should be kept small enough, to avoid running beyond computational resources, but a too-small size will result in a larger number of process invocations, which may slow down processing. Window sizes for spatial dimensions typically range from 64 to 512 pixels, while overlaps of 8 to 32 pixels are common.\n\nFor the special case of 2D convolution, it is recommended to use ``apply_kernel()``.", "categories": [ "cubes" ], diff --git a/arccos.json b/arccos.json index 4cd498a7..87378a40 100644 --- a/arccos.json +++ b/arccos.json @@ -1,7 +1,7 @@ { "id": "arccos", "summary": "Inverse cosine", - "description": "Computes the arc cosine of `x`. The arc cosine is the inverse function of the cosine so that *`arccos(cos(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated. `NaN` is returned for values outside of the allowed range.", + "description": "Computes the arc cosine of `x`. The arc cosine is the inverse function of the cosine so that *`arccos(cos(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated. `NaN` is returned for values outside of the allowed range.", "categories": [ "math > trigonometric" ], diff --git a/arcosh.json b/arcosh.json index 820b8cd4..800ad449 100644 --- a/arcosh.json +++ b/arcosh.json @@ -1,7 +1,7 @@ { "id": "arcosh", "summary": "Inverse hyperbolic cosine", - "description": "Computes the inverse hyperbolic cosine of `x`. It is the inverse function of the hyperbolic cosine so that *`arcosh(cosh(x)) = x`*.\n\nThe no-data value `null` is passed through and therefore gets propagated. `NaN` is returned for values outside of the allowed range.", + "description": "Computes the inverse hyperbolic cosine of `x`. It is the inverse function of the hyperbolic cosine so that *`arcosh(cosh(x)) = x`*.\n\nNo-data values are passed through and therefore get propagated. `NaN` is returned for values outside of the allowed range.", "categories": [ "math > trigonometric" ], diff --git a/arcsin.json b/arcsin.json index 2c772a00..9f6c72ee 100644 --- a/arcsin.json +++ b/arcsin.json @@ -1,7 +1,7 @@ { "id": "arcsin", "summary": "Inverse sine", - "description": "Computes the arc sine of `x`. The arc sine is the inverse function of the sine so that *`arcsin(sin(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated. `NaN` is returned for values < -1 and > 1.", + "description": "Computes the arc sine of `x`. The arc sine is the inverse function of the sine so that *`arcsin(sin(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated. `NaN` is returned for values < -1 and > 1.", "categories": [ "math > trigonometric" ], diff --git a/arctan.json b/arctan.json index 9461eba3..08c7eb5c 100644 --- a/arctan.json +++ b/arctan.json @@ -1,7 +1,7 @@ { "id": "arctan", "summary": "Inverse tangent", - "description": "Computes the arc tangent of `x`. The arc tangent is the inverse function of the tangent so that *`arctan(tan(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the arc tangent of `x`. The arc tangent is the inverse function of the tangent so that *`arctan(tan(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > trigonometric" ], diff --git a/arctan2.json b/arctan2.json index ca7d507f..17bd38e6 100644 --- a/arctan2.json +++ b/arctan2.json @@ -1,7 +1,7 @@ { "id": "arctan2", "summary": "Inverse tangent of two numbers", - "description": "Computes the arc tangent of two numbers `x` and `y`. It is similar to calculating the arc tangent of *`y / x`*, except that the signs of both arguments are used to determine the quadrant of the result.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated if any of the arguments is `null`.", + "description": "Computes the arc tangent of two numbers `x` and `y`. It is similar to calculating the arc tangent of *`y / x`*, except that the signs of both arguments are used to determine the quadrant of the result.\n\nWorks on radians only.\nIf any argument is a no-data value, the result will be the no-data value (or `null`).", "categories": [ "math > trigonometric" ], @@ -59,4 +59,4 @@ "title": "Two-argument inverse tangent explained by Wikipedia" } ] -} \ No newline at end of file +} diff --git a/array_contains.json b/array_contains.json index 37ced980..cd1586ac 100644 --- 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 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. A `null` return value from ``eq()`` is handled exactly as `false` (no match).\n* 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. A no-data return value from ``eq()`` is handled as `false` (no match).\n* 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.\n\nSee the examples to check for no-data values.", "categories": [ "arrays", "comparison", @@ -20,7 +20,7 @@ }, { "name": "value", - "description": "Value to find in `data`. If the value is `null`, this process returns always `false`.", + "description": "Value to find in `data`. If the value is no-data value (or `null`), this process returns always `false`.", "schema": { "type": [ "number", diff --git a/array_element.json b/array_element.json index 8b70a2e5..f0763793 100644 --- a/array_element.json +++ b/array_element.json @@ -41,7 +41,7 @@ }, { "name": "return_nodata", - "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`.", + "description": "By default this process throws an `ArrayElementNotAvailable` exception if the index or label is invalid. If you want to return the no-data value (or `null`) instead, set this flag to `true`.", "schema": { "type": "boolean" }, @@ -103,4 +103,4 @@ "returns": null } ] -} \ No newline at end of file +} diff --git a/array_find.json b/array_find.json index 7b0e6317..6344d223 100644 --- 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": "Returns the zero-based index of the first (or last) occurrence of the value specified by `value` in the array specified by `data` or `null` if there is no match. Use the parameter `reverse` to switch from the first to the last match.\n\n**Remarks:**\n\n* Use ``array_contains()`` to check if an array contains a value regardless of the position.\n* Use ``array_find_label()`` to find the index for a label.\n* All definitions for the process ``eq()`` regarding the comparison of values apply here as well. A `null` return value from ``eq()`` is handled exactly as `false` (no match).\n* 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.\n* If the specified value is an array, object or null, the process always returns `null`. See the examples for one to find `null` values.", + "description": "Returns the zero-based index of the first (or last) occurrence of the value specified by `value` in the array specified by `data` or `null` if there is no match. Use the parameter `reverse` to switch from the first to the last match.\n\n**Remarks:**\n\n* Use ``array_contains()`` to check if an array contains a value regardless of the position.\n* Use ``array_find_label()`` to find the index for a label.\n* All definitions for the process ``eq()`` regarding the comparison of values apply here as well. A no-data return value from ``eq()`` is handled as `false` (no match).\n* 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.\n* If the specified value is an array, object or null, the process always returns `null`. See the examples to find no-data values.", "categories": [ "arrays", "reducer" @@ -19,7 +19,7 @@ }, { "name": "value", - "description": "Value to find in `data`. If the value is `null`, this process returns always `null`.", + "description": "Value to find in `data`. If the value is a no-data value (or `null`), this process returns the no-data value (or `null`).", "schema": { "description": "Any data type is allowed." } @@ -96,18 +96,6 @@ }, "returns": null }, - { - "arguments": { - "data": [ - 1, - null, - 2, - null - ], - "value": null - }, - "returns": null - }, { "arguments": { "data": [ diff --git a/array_interpolate_linear.json b/array_interpolate_linear.json index 021522b0..57188e8f 100644 --- a/array_interpolate_linear.json +++ b/array_interpolate_linear.json @@ -1,7 +1,7 @@ { "id": "array_interpolate_linear", "summary": "One-dimensional linear interpolation for arrays", - "description": "Performs a linear interpolation for each of the no-data values (`null`) in the array given, except for leading and trailing no-data values.\n\nThe linear interpolants are defined by the array indices or labels (x) and the values in the array (y).", + "description": "Performs a linear interpolation for each of the NaN and no-data values in the array given, except for leading and trailing NaN and no-data values.\n\nThe linear interpolants are defined by the array indices or labels (x axis) and the values in the array (y axis).", "categories": [ "arrays", "math", @@ -10,7 +10,7 @@ "parameters": [ { "name": "data", - "description": "An array of numbers and no-data values.\n\nIf the given array is a labeled array, the labels must have a natural/inherent label order and the process expects the labels to be sorted accordingly. This is the default behavior in openEO for spatial and temporal dimensions.", + "description": "An array of numbers, which may include NaN, ±infinity, and no-data values.\n\nIf the given array is a labeled array, the labels must have a natural/inherent label order and the process expects the labels to be sorted accordingly. This is the default behavior in openEO for spatial and temporal dimensions.", "schema": { "type": "array", "items": { @@ -23,7 +23,7 @@ } ], "returns": { - "description": "An array with no-data values being replaced with interpolated values. If not at least 2 numerical values are available in the array, the array stays the same.", + "description": "An array with NaN and no-data values being replaced with interpolated values. If not at least 2 numerical values are available in the array, the array stays the same.", "schema": { "type": "array", "items": { diff --git a/arsinh.json b/arsinh.json index 2b7942dd..405ab410 100644 --- a/arsinh.json +++ b/arsinh.json @@ -1,7 +1,7 @@ { "id": "arsinh", "summary": "Inverse hyperbolic sine", - "description": "Computes the inverse hyperbolic sine of `x`. It is the inverse function of the hyperbolic sine so that *`arsinh(sinh(x)) = x`*.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the inverse hyperbolic sine of `x`. It is the inverse function of the hyperbolic sine so that *`arsinh(sinh(x)) = x`*.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > trigonometric" ], diff --git a/artanh.json b/artanh.json index 6308290d..c7d4778d 100644 --- a/artanh.json +++ b/artanh.json @@ -1,7 +1,7 @@ { "id": "artanh", "summary": "Inverse hyperbolic tangent", - "description": "Computes the inverse hyperbolic tangent of `x`. It is the inverse function of the hyperbolic tangent so that *`artanh(tanh(x)) = x`*.\n\nThe no-data value `null` is passed through and therefore gets propagated. `NaN` is returned for values outside of the allowed range. The computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, `x` = 1 results in +infinity and `x` = 0 results in -infinity. Otherwise, an exception is thrown.", + "description": "Computes the inverse hyperbolic tangent of `x`. It is the inverse function of the hyperbolic tangent so that *`artanh(tanh(x)) = x`*.\n\nNo-data values are passed through and therefore get propagated. `NaN` is returned for values outside of the allowed range. The computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, `x` = 1 results in +infinity and `x` = 0 results in -infinity. Otherwise, an exception is thrown.", "categories": [ "math > trigonometric" ], diff --git a/between.json b/between.json index 12e37693..b09d09fb 100644 --- a/between.json +++ b/between.json @@ -8,7 +8,7 @@ "parameters": [ { "name": "x", - "description": "The value to check.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "The value to check.\n\nNo-data values are passed through and therefore get propagated.", "schema": { "description": "Any data type is allowed." } @@ -38,7 +38,7 @@ } ], "returns": { - "description": "`true` if `x` is between the specified bounds, `null` if `x` is a no-data value, `false` otherwise.", + "description": "`true` if `x` is between the specified bounds, the no-data value (or `null`) if `x` is a no-data value, `false` otherwise.", "schema": { "type": [ "boolean", diff --git a/ceil.json b/ceil.json index 7c01cf45..9f237bf1 100644 --- a/ceil.json +++ b/ceil.json @@ -1,7 +1,7 @@ { "id": "ceil", "summary": "Round fractions up", - "description": "The least integer greater than or equal to the number `x`.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "The least integer greater than or equal to the number `x`.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > rounding" ], @@ -59,4 +59,4 @@ "title": "Ceiling explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/clip.json b/clip.json index de2a4d1a..04c2d7b4 100644 --- a/clip.json +++ b/clip.json @@ -1,7 +1,7 @@ { "id": "clip", "summary": "Clip a value between a minimum and a maximum", - "description": "Clips a number between specified minimum and maximum values. A value larger than the maximum value is set to the maximum value, a value lower than the minimum value is set to the minimum value. If the maximum value is smaller than the minimum number, the process throws a `MinMaxSwapped` exception.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Clips a number between specified minimum and maximum values. A value larger than the maximum value is set to the maximum value, a value lower than the minimum value is set to the minimum value. If the maximum value is smaller than the minimum number, the process throws a `MinMaxSwapped` exception.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math" ], diff --git a/cos.json b/cos.json index 0d6229a8..ac312c20 100644 --- a/cos.json +++ b/cos.json @@ -1,7 +1,7 @@ { "id": "cos", "summary": "Cosine", - "description": "Computes the cosine of `x`.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the cosine of `x`.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > trigonometric" ], diff --git a/cosh.json b/cosh.json index 8b56a222..572a6161 100644 --- a/cosh.json +++ b/cosh.json @@ -1,7 +1,7 @@ { "id": "cosh", "summary": "Hyperbolic cosine", - "description": "Computes the hyperbolic cosine of `x`.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the hyperbolic cosine of `x`.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > trigonometric" ], diff --git a/divide.json b/divide.json index 0c6c254a..2c41bd3d 100644 --- a/divide.json +++ b/divide.json @@ -1,7 +1,7 @@ { "id": "divide", "summary": "Division of two numbers", - "description": "Divides argument `x` by the argument `y` (*`x / y`*) and returns the computed result.\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. A division by zero results in:\n\n- +infinity for `x` > 0,\n- -infinity for `x` < 0,\n- `NaN` for `x` = 0,\n- or otherwise, throws a `DivisionByZero` exception if the other options are not supported by the processing environment.", + "description": "Divides argument `x` by the argument `y` (*`x / y`*) and returns the computed result.\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. A division by zero results in:\n\n- +infinity for `x` > 0,\n- -infinity for `x` < 0,\n- `NaN` for `x` = 0,\n- or otherwise, throws a `DivisionByZero` exception if the other options are not supported by the processing environment.", "categories": [ "math" ], diff --git a/eq.json b/eq.json index 0c62b42c..b1b23385 100644 --- a/eq.json +++ b/eq.json @@ -1,7 +1,7 @@ { "id": "eq", "summary": "Equal to comparison", - "description": "Compares whether `x` is strictly equal to `y`.\n\n**Remarks:**\n\n* Data types MUST be checked strictly. For example, a string with the content *1* is not equal to the number *1*. Nevertheless, an integer *1* is equal to a floating-point number *1.0* as `integer` is a sub-type of `number`.\n* If any operand is `null`, the return value is `null`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is strictly equal to `y`.\n\n**Remarks:**\n\n* Data types MUST be checked strictly. For example, a string with the content *1* is not equal to the number *1*. Nevertheless, an integer *1* is equal to a floating-point number *1.0* as `integer` is a sub-type of `number`.\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "texts", "comparison" @@ -55,7 +55,7 @@ } ], "returns": { - "description": "`true` if `x` is equal to `y`, `null` if any operand is `null`, otherwise `false`.", + "description": "`true` if `x` is equal to `y`, the no-data value (or `null`) if any operand is a no-data value, otherwise `false`.", "schema": { "type": [ "boolean", @@ -71,13 +71,6 @@ }, "returns": null }, - { - "arguments": { - "x": null, - "y": null - }, - "returns": null - }, { "arguments": { "x": 1, @@ -152,13 +145,6 @@ "y": "2018-01-01T00:00:00+00:00" }, "returns": false - }, - { - "arguments": { - "x": null, - "y": null - }, - "returns": null } ] } diff --git a/exp.json b/exp.json index 2d551390..bceeef2c 100644 --- a/exp.json +++ b/exp.json @@ -1,7 +1,7 @@ { "id": "exp", "summary": "Exponentiation to the base e", - "description": "Exponential function to the base *e* raised to the power of `p`.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Exponential function to the base *e* raised to the power of `p`.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > exponential & logarithmic" ], diff --git a/extrema.json b/extrema.json index 6f6075de..7028a420 100644 --- a/extrema.json +++ b/extrema.json @@ -21,7 +21,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that an array with two `null` values is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in an array with two no-data (or `null`) values.", "schema": { "type": "boolean" }, @@ -30,7 +30,7 @@ } ], "returns": { - "description": "An array containing the minimum and maximum values for the specified numbers. The first element is the minimum, the second element is the maximum. If the input array is empty both elements are set to `null`.", + "description": "An array containing the minimum and maximum values for the specified numbers. The first element is the minimum, the second element is the maximum. If the input array is empty both elements are set to the no-data value (or `null`).", "schema": [ { "type": "array", @@ -94,16 +94,6 @@ null, null ] - }, - { - "description": "The input array is empty: return two `null` values.", - "arguments": { - "data": [] - }, - "returns": [ - null, - null - ] } ] -} \ No newline at end of file +} diff --git a/filter_spatial.json b/filter_spatial.json index ed4f7c3f..f1b5f8b8 100644 --- a/filter_spatial.json +++ b/filter_spatial.json @@ -1,7 +1,7 @@ { "id": "filter_spatial", "summary": "Spatial filter raster data cubes using geometries", - "description": "Limits the raster data cube over the spatial dimensions to the specified geometries.\n\n- For **polygons**, the filter retains a pixel in the data cube if the point at the pixel center intersects with at least one of the polygons (as defined in the Simple Features standard by the OGC).\n- For **points**, the process considers the closest pixel center.\n- For **lines** (line strings), the process considers all the pixels whose centers are closest to at least one point on the line.\n\nMore specifically, pixels outside of the bounding box of the given geometries will not be available after filtering. All pixels inside the bounding box that are not retained will be set to `null` (no data).\n\n Alternatively, use ``filter_bbox()`` to filter with a bounding box or ``filter_vector()`` to filter a vector data cube based on geometries. Use ``mask_polygon()`` to mask without changing the spatial extent of your data cube.", + "description": "Limits the raster data cube over the spatial dimensions to the specified geometries.\n\n- For **polygons**, the filter retains a pixel in the data cube if the point at the pixel center intersects with at least one of the polygons (as defined in the Simple Features standard by the OGC).\n- For **points**, the process considers the closest pixel center.\n- For **lines** (line strings), the process considers all the pixels whose centers are closest to at least one point on the line.\n\nMore specifically, pixels outside of the bounding box of the given geometries will not be available after filtering. All pixels inside the bounding box that are not retained will be set to no-data values.\n\n Alternatively, use ``filter_bbox()`` to filter with a bounding box or ``filter_vector()`` to filter a vector data cube based on geometries. Use ``mask_polygon()`` to mask without changing the spatial extent of your data cube.", "categories": [ "cubes", "filter" diff --git a/first.json b/first.json index 1afa9624..59fe4f77 100644 --- a/first.json +++ b/first.json @@ -1,7 +1,7 @@ { "id": "first", "summary": "First element", - "description": "Gives the first element of an array.\n\nAn array without non-`null` elements resolves always with `null`.", + "description": "Gives the first element of an array.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "arrays", "reducer" @@ -19,7 +19,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if the first value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, the first value of the array is returned regardless of whether it is a no-data value or not. For the default value `true`, the first non-no-data value is returned.", "schema": { "type": "boolean" }, @@ -65,13 +65,6 @@ "ignore_nodata": false }, "returns": null - }, - { - "description": "The input array is empty: return `null`.", - "arguments": { - "data": [] - }, - "returns": null } ] -} \ No newline at end of file +} diff --git a/floor.json b/floor.json index d0eb5a94..63c1c48d 100644 --- a/floor.json +++ b/floor.json @@ -1,7 +1,7 @@ { "id": "floor", "summary": "Round fractions down", - "description": "The greatest integer less than or equal to the number `x`.\n\nThis process is *not* an alias for the ``int()`` process as defined by some mathematicians, see the examples for negative numbers in both processes for differences.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "The greatest integer less than or equal to the number `x`.\n\nThis process is *not* an alias for the ``int()`` process as defined by some mathematicians, see the examples for negative numbers in both processes for differences.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > rounding" ], @@ -59,4 +59,4 @@ "title": "Floor explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/gt.json b/gt.json index ae2cf151..542f618c 100644 --- a/gt.json +++ b/gt.json @@ -1,7 +1,7 @@ { "id": "gt", "summary": "Greater than comparison", - "description": "Compares whether `x` is strictly greater than `y`.\n\n**Remarks:**\n\n* If any operand is `null`, the return value is `null`.\n* If any operand is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is strictly greater than `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* If any operand is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "comparison" ], @@ -32,7 +32,7 @@ } ], "returns": { - "description": "`true` if `x` is strictly greater than `y` or `null` if any operand is `null`, otherwise `false`.", + "description": "`true` if `x` is strictly greater than `y`, the no-data value (or `null`) if any operand is a no-data value, otherwise `false`.", "schema": { "type": [ "boolean", @@ -89,13 +89,6 @@ "y": false }, "returns": false - }, - { - "arguments": { - "x": null, - "y": null - }, - "returns": null } ] } diff --git a/gte.json b/gte.json index a32816c4..712b6b9c 100644 --- a/gte.json +++ b/gte.json @@ -1,7 +1,7 @@ { "id": "gte", "summary": "Greater than or equal to comparison", - "description": "Compares whether `x` is greater than or equal to `y`.\n\n**Remarks:**\n\n* If any operand is `null`, the return value is `null`.\n* If the operands are not equal (see process ``eq()``) and any of them is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is greater than or equal to `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* If the operands are not equal (see process ``eq()``) and any of them is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "comparison" ], @@ -32,7 +32,7 @@ } ], "returns": { - "description": "`true` if `x` is greater than or equal to `y`, `null` if any operand is `null`, otherwise `false`.", + "description": "`true` if `x` is greater than or equal to `y`, the no-data value (or `null`) if any operand is a no-data value, otherwise `false`.", "schema": { "type": [ "boolean", @@ -82,13 +82,6 @@ "y": false }, "returns": false - }, - { - "arguments": { - "x": null, - "y": null - }, - "returns": null } ], "process_graph": { diff --git a/if.json b/if.json index 43e6fcdc..aae6db8e 100644 --- a/if.json +++ b/if.json @@ -27,7 +27,7 @@ }, { "name": "reject", - "description": "A value that is returned if the boolean value is **not** `true`. Defaults to `null`.", + "description": "A value that is returned if the boolean value is **not** `true`. Defaults to the no-data value (or `null`).", "schema": { "description": "Any data type is allowed." }, @@ -93,4 +93,4 @@ "returns": null } ] -} \ No newline at end of file +} diff --git a/int.json b/int.json index 8fca1655..32d1424a 100644 --- a/int.json +++ b/int.json @@ -1,7 +1,7 @@ { "id": "int", "summary": "Integer part of a number", - "description": "The integer part of the real number `x`.\n\nThis process is *not* an alias for the ``floor()`` process as defined by some mathematicians, see the examples for negative numbers in both processes for differences.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "The integer part of the real number `x`.\n\nThis process is *not* an alias for the ``floor()`` process as defined by some mathematicians, see the examples for negative numbers in both processes for differences.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math", "math > rounding" @@ -60,4 +60,4 @@ "title": "Integer Part explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/is_nodata.json b/is_nodata.json index a1b7c08b..f7d696b9 100644 --- a/is_nodata.json +++ b/is_nodata.json @@ -1,7 +1,7 @@ { "id": "is_nodata", "summary": "Value is a no-data value", - "description": "Checks whether the specified data is missing data, i.e. equals to `null` or any of the no-data values specified in the metadata.\n\nThe special numerical value `NaN` (not a number) as defined by the [IEEE Standard 754](https://ieeexplore.ieee.org/document/4610935) is only considered as no-data value if specified as no-data value in the metadata.", + "description": "Checks whether the specified data is no-data value, i.e. equals to any of the no-data values of the data cube (or `null`). The specific no-data values are usually provided through the collection or STAC metadata.\n\nThe special numerical value `NaN` (not a number) as defined by the [IEEE Standard 754](https://ieeexplore.ieee.org/document/4610935) is only considered as no-data value if explicitly specified as no-data value for the data cube.", "categories": [ "comparison" ], diff --git a/last.json b/last.json index 1a35e6ac..f523c488 100644 --- a/last.json +++ b/last.json @@ -1,7 +1,7 @@ { "id": "last", "summary": "Last element", - "description": "Gives the last element of an array.\n\nAn array without non-`null` elements resolves always with `null`.", + "description": "Gives the last element of an array.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "arrays", "reducer" @@ -19,7 +19,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if the last value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, the last value of the array is returned regardless of whether it is a no-data value or not. For the default value `true`, the last non-no-data value is returned.", "schema": { "type": "boolean" }, @@ -65,13 +65,6 @@ "ignore_nodata": false }, "returns": null - }, - { - "description": "The input array is empty: return `null`.", - "arguments": { - "data": [] - }, - "returns": null } ] -} \ No newline at end of file +} diff --git a/linear_scale_range.json b/linear_scale_range.json index 01f09857..c3de1096 100644 --- a/linear_scale_range.json +++ b/linear_scale_range.json @@ -1,7 +1,7 @@ { "id": "linear_scale_range", "summary": "Linear transformation between two ranges", - "description": "Performs a linear transformation between the input and output range.\n\nThe given number in `x` is clipped to the bounds specified in `inputMin` and `inputMax` so that the underlying formula *`((x - inputMin) / (inputMax - inputMin)) * (outputMax - outputMin) + outputMin`* never returns a value outside of the range defined by `outputMin` and `outputMax`.\n\nPotential use case include\n\n* scaling values to the 8-bit range (0 - 255) often used for numeric representation of values in one of the channels of the [RGB colour model](https://en.wikipedia.org/wiki/RGB_color_model#Numeric_representations) or\n* calculating percentages (0 - 100).\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Performs a linear transformation between the input and output range.\n\nThe given number in `x` is clipped to the bounds specified in `inputMin` and `inputMax` so that the underlying formula *`((x - inputMin) / (inputMax - inputMin)) * (outputMax - outputMin) + outputMin`* never returns a value outside of the range defined by `outputMin` and `outputMax`.\n\nPotential use case include\n\n* scaling values to the 8-bit range (0 - 255) often used for numeric representation of values in one of the channels of the [RGB colour model](https://en.wikipedia.org/wiki/RGB_color_model#Numeric_representations) or\n* calculating percentages (0 - 100).\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math" ], diff --git a/ln.json b/ln.json index 1663771b..6b9b5022 100644 --- a/ln.json +++ b/ln.json @@ -1,7 +1,7 @@ { "id": "ln", "summary": "Natural logarithm", - "description": "The natural logarithm is the logarithm to the base *e* of the number `x`, which equals to using the *log* process with the base set to *e*. The natural logarithm is the inverse function of taking *e* to the power x.\n\nThe no-data value `null` is passed through.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`ln(0)`* results in -infinity if the processing environment supports it or otherwise an exception is thrown. `NaN` is returned for values outside of the allowed range.", + "description": "The natural logarithm is the logarithm to the base *e* of the number `x`, which equals to using the *log* process with the base set to *e*. The natural logarithm is the inverse function of taking *e* to the power x.\n\nNo-data values are passed through and therefore get propagated.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`ln(0)`* results in -infinity if the processing environment supports it or otherwise an exception is thrown. `NaN` is returned for values outside of the allowed range.", "categories": [ "math > exponential & logarithmic" ], diff --git a/load_collection.json b/load_collection.json index a6701cc3..aeb9269e 100644 --- a/load_collection.json +++ b/load_collection.json @@ -87,14 +87,14 @@ }, { "title": "GeoJSON", - "description": "Deprecated in favor of ``load_geojson()``. Limits the data cube to the bounding box of the given geometries. For raster data, all pixels inside the bounding box that do not intersect with any of the polygons will be set to no data (`null`).\n\nThe GeoJSON type `GeometryCollection` is not supported. Empty geometries are ignored.", + "description": "Deprecated in favor of ``load_geojson()``. Limits the data cube to the bounding box of the given geometries. For raster data, all pixels inside the bounding box that do not intersect with any of the polygons will be set to the no-data value of the data cube.\n\nThe GeoJSON type `GeometryCollection` is not supported. Empty geometries are ignored.", "type": "object", "subtype": "geojson", "deprecated": true }, { "title": "Vector data cube", - "description": "Limits the data cube to the bounding box of the given geometries in the vector data cube. For raster data, all pixels inside the bounding box that do not intersect with any of the polygons will be set to no data (`null`). Empty geometries are ignored.", + "description": "Limits the data cube to the bounding box of the given geometries in the vector data cube. For raster data, all pixels inside the bounding box that do not intersect with any of the polygons will be set to the no-data value of the data cube. Empty geometries are ignored.", "type": "object", "subtype": "datacube", "dimensions": [ diff --git a/log.json b/log.json index 67a19ba2..9b8866ca 100644 --- a/log.json +++ b/log.json @@ -1,7 +1,7 @@ { "id": "log", "summary": "Logarithm to a base", - "description": "Logarithm to the base `base` of the number `x` is defined to be the inverse function of taking b to the power of x.\n\nThe no-data value `null` is passed through and therefore gets propagated if any of the arguments is `null`.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, having `x` set to `0` with any base results in -infinity if the processing environment supports it or otherwise an exception is thrown. `NaN` is returned for values outside of the allowed range.", + "description": "Logarithm to the base `base` of the number `x` is defined to be the inverse function of taking b to the power of x.\n\nIf any argument is a no-data value, the result will be the no-data value (or `null`).\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, having `x` set to `0` with any base results in -infinity if the processing environment supports it or otherwise an exception is thrown. `NaN` is returned for values outside of the allowed range.", "categories": [ "math > exponential & logarithmic" ], diff --git a/lt.json b/lt.json index 0cc45f87..b7e35bf4 100644 --- a/lt.json +++ b/lt.json @@ -1,7 +1,7 @@ { "id": "lt", "summary": "Less than comparison", - "description": "Compares whether `x` is strictly less than `y`.\n\n**Remarks:**\n\n* If any operand is `null`, the return value is `null`.\n* If any operand is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is strictly less than `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* If any operand is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "comparison" ], @@ -32,7 +32,7 @@ } ], "returns": { - "description": "`true` if `x` is strictly less than `y`, `null` if any operand is `null`, otherwise `false`.", + "description": "`true` if `x` is strictly less than `y`, the no-data value (or `null`) if any operand is a no-data value, otherwise `false`.", "schema": { "type": [ "boolean", @@ -89,13 +89,6 @@ "y": true }, "returns": false - }, - { - "arguments": { - "x": null, - "y": null - }, - "returns": null } ] } diff --git a/lte.json b/lte.json index 9f936915..5ab05126 100644 --- a/lte.json +++ b/lte.json @@ -1,7 +1,7 @@ { "id": "lte", "summary": "Less than or equal to comparison", - "description": "Compares whether `x` is less than or equal to `y`.\n\n**Remarks:**\n\n* If any operand is `null`, the return value is `null`.\n* If the operands are not equal (see process ``eq()``) and any of them is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is less than or equal to `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* If the operands are not equal (see process ``eq()``) and any of them is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "comparison" ], @@ -32,7 +32,7 @@ } ], "returns": { - "description": "`true` if `x` is less than or equal to `y`, `null` if any operand is `null`, otherwise `false`.", + "description": "`true` if `x` is less than or equal to `y`, the no-data value (or `null`) if any operand is a no-data value, otherwise `false`.", "schema": { "type": [ "boolean", @@ -82,13 +82,6 @@ "y": true }, "returns": false - }, - { - "arguments": { - "x": null, - "y": null - }, - "returns": null } ], "process_graph": { diff --git a/mask.json b/mask.json index 0381d220..02b394bc 100644 --- a/mask.json +++ b/mask.json @@ -1,7 +1,7 @@ { "id": "mask", "summary": "Apply a raster mask", - "description": "Applies a mask to a raster data cube. To apply a polygon as a mask, use ``mask_polygon()``.\n\nA mask is a raster data cube for which corresponding pixels among `data` and `mask` are compared and those pixels in `data` are replaced whose pixels in `mask` are non-zero (for numbers) or `true` (for boolean values). The pixel values are replaced with the value specified for `replacement`, which defaults to `null` (no data).\n\nThe data cubes have to be compatible except that the horizontal spatial dimensions (axes `x` and `y`) will be aligned implicitly by ``resample_cube_spatial()``. `data` is the target data cube for resampling and the default parameters of ``resample_cube_spatial()`` apply. All other dimensions in the mask must also be available in the raster data cube with the same name, type, reference system, resolution and labels. Dimensions can be missing in the mask with the result that the mask is applied to each label of the dimension in `data` that is missing in the data cube of the mask. The process fails if there's an incompatibility found between the raster data cube and the mask.", + "description": "Applies a mask to a raster data cube. To apply a polygon as a mask, use ``mask_polygon()``.\n\nA mask is a raster data cube for which corresponding pixels among `data` and `mask` are compared and those pixels in `data` are replaced whose pixels in `mask` are non-zero (for numbers) or `true` (for boolean values). The pixel values are replaced with the value specified for `replacement`, which defaults to the no-data value of the raster data cube.\n\nThe data cubes have to be compatible except that the horizontal spatial dimensions (axes `x` and `y`) will be aligned implicitly by ``resample_cube_spatial()``. `data` is the target data cube for resampling and the default parameters of ``resample_cube_spatial()`` apply. All other dimensions in the mask must also be available in the raster data cube with the same name, type, reference system, resolution and labels. Dimensions can be missing in the mask with the result that the mask is applied to each label of the dimension in `data` that is missing in the data cube of the mask. The process fails if there's an incompatibility found between the raster data cube and the mask.", "categories": [ "cubes", "masks" @@ -43,7 +43,7 @@ }, { "name": "replacement", - "description": "The value used to replace masked values with.", + "description": "The value used to replace masked values with. `null` refers to the no-data value of the data cube provided for `data`.", "schema": { "type": [ "number", diff --git a/mask_polygon.json b/mask_polygon.json index f04d3750..acf2ee6a 100644 --- a/mask_polygon.json +++ b/mask_polygon.json @@ -1,7 +1,7 @@ { "id": "mask_polygon", "summary": "Apply a polygon mask", - "description": "Applies a (multi) polygon mask to a raster data cube. To apply a raster mask use ``mask()``.\n\nAll pixels for which the point at the pixel center **does not** intersect with any polygon (as defined in the Simple Features standard by the OGC) are replaced. This behavior can be inverted by setting the parameter `inside` to `true`. The pixel values are replaced with the value specified for `replacement`, which defaults to `null` (no data). No data values in `data` will be left untouched by the masking operation.", + "description": "Applies a (multi) polygon mask to a raster data cube. To apply a raster mask use ``mask()``.\n\nAll pixels for which the point at the pixel center **does not** intersect with any polygon (as defined in the Simple Features standard by the OGC) are replaced. This behavior can be inverted by setting the parameter `inside` to `true`. The pixel values are replaced with the value specified for `replacement`, which defaults to the no-data value of the raster data cube. No data values in `data` will be left untouched by the masking operation.", "categories": [ "cubes", "masks" @@ -53,7 +53,7 @@ }, { "name": "replacement", - "description": "The value used to replace masked values with.", + "description": "The value used to replace masked values with. `null` refers to the no-data value of the data cube provided for `data`.", "schema": [ { "type": "number" diff --git a/max.json b/max.json index d8903df0..6a931780 100644 --- a/max.json +++ b/max.json @@ -1,7 +1,7 @@ { "id": "max", "summary": "Maximum value", - "description": "Computes the largest value of an array of numbers, which is equal to the first element of a sorted (i.e., ordered) version of the array.\n\nAn array without non-`null` elements resolves always with `null`.", + "description": "Computes the largest value of an array of numbers, which is equal to the first element of a sorted (i.e., ordered) version of the array.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "math", "math > statistics", @@ -23,7 +23,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in a no-data value (or `null`).", "schema": { "type": "boolean" }, @@ -75,13 +75,6 @@ "ignore_nodata": false }, "returns": null - }, - { - "description": "The input array is empty: return `null`.", - "arguments": { - "data": [] - }, - "returns": null } ], "links": [ @@ -91,4 +84,4 @@ "title": "Maximum explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/mean.json b/mean.json index cb45faa4..31f1c9ec 100644 --- a/mean.json +++ b/mean.json @@ -1,7 +1,7 @@ { "id": "mean", "summary": "Arithmetic mean (average)", - "description": "The arithmetic mean of an array of numbers is the quantity commonly called the average. It is defined as the sum of all elements divided by the number of elements.\n\nAn array without non-`null` elements resolves always with `null`.", + "description": "The arithmetic mean of an array of numbers is the quantity commonly called the average. It is defined as the sum of all elements divided by the number of elements.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "math > statistics", "reducer" @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in a no-data value (or `null`).", "schema": { "type": "boolean" }, @@ -71,23 +71,6 @@ "ignore_nodata": false }, "returns": null - }, - { - "description": "The input array is empty: return `null`.", - "arguments": { - "data": [] - }, - "returns": null - }, - { - "description": "The input array has only `null` elements: return `null`.", - "arguments": { - "data": [ - null, - null - ] - }, - "returns": null } ], "links": [ @@ -163,4 +146,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/median.json b/median.json index e54deb84..fb1f31c1 100644 --- a/median.json +++ b/median.json @@ -1,7 +1,7 @@ { "id": "median", "summary": "Statistical median", - "description": "The statistical median of an array of numbers is the value separating the higher half from the lower half of the data.\n\nAn array without non-`null` elements resolves always with `null`.\n\n**Remarks:**\n\n* For symmetric arrays, the result is equal to the ``mean()``.\n* The median can also be calculated by computing the ``quantiles()`` with a probability of *0.5*.", + "description": "The statistical median of an array of numbers is the value separating the higher half from the lower half of the data.\n\nAn array with solely no-data values returns the no-data value (or `null`).\n\n**Remarks:**\n\n* For symmetric arrays, the result is equal to the ``mean()``.\n* The median can also be calculated by computing the ``quantiles()`` with a probability of *0.5*.", "categories": [ "math > statistics", "reducer" @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in a no-data value (or `null`).", "schema": { "type": "boolean" }, @@ -91,23 +91,6 @@ "ignore_nodata": false }, "returns": null - }, - { - "description": "The input array is empty: return `null`.", - "arguments": { - "data": [] - }, - "returns": null - }, - { - "description": "The input array has only `null` elements: return `null`.", - "arguments": { - "data": [ - null, - null - ] - }, - "returns": null } ], "links": [ @@ -144,4 +127,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/merge_cubes.json b/merge_cubes.json index c22421c2..8b3595b7 100644 --- a/merge_cubes.json +++ b/merge_cubes.json @@ -24,7 +24,7 @@ }, { "name": "overlap_resolver", - "description": "A reduction operator that resolves the conflict if the data overlaps. The reducer must return a value of the same data type as the input values are. The reduction operator may be a single process such as ``multiply()`` or consist of multiple sub-processes. `null` (the default) can be specified if no overlap resolver is required.", + "description": "A reduction operator that resolves the conflict if the data overlaps. The reducer must return a value of the same data type as the input values are. The reduction operator may be a single process such as ``multiply()`` or consist of multiple sub-processes. The default value `null` can be specified if no overlap resolver is required.", "schema": { "type": "object", "subtype": "process-graph", diff --git a/meta/implementation.md b/meta/implementation.md index 65a24430..fafe6ea0 100644 --- a/meta/implementation.md +++ b/meta/implementation.md @@ -2,6 +2,28 @@ This file is meant to provide some additional implementation details for back-ends. +## No-data value + +A data cube shall always keep reference of the applicable no-data values. +The no-data value can be chosen by the back-end implementation, e.g. depending on the data type of the data. +No-data values should be exposed for each pre-defined Collection in its metadata. +For all data generated through openEO (e.g. through synchronous or batch jobs), the metadata and/or data +shall expose the no-data values. + +The openEO process specifications generally use `null` as a generic value to express no-data values. +This is primarily meant for the JSON encoding, this means: +1. in the process specification (data type `null` in the schema), and +2. in the process graph (if the no-data value exposed through the metadata can't be used in JSON). + +Back-ends may or may not use `null` as a no-data value internally. + +**NaN**: If `NaN` is the no-data value for floating-point numbers, be aware that the behavior of +no-data values in openEO and `NaN` (IEEE 754) sometimes differs. + +**Array processes:** Some array processes (e.g. `array_find` or `any`) use `null` as a return value. +In the context of data cube operations (e.g. in `reduce_dimension`), `null` values returned +by the array processes shall be replaced with the no-data value of the data cube. + ## Optimizations for conditions (e.g. `if`) None of the openEO processes per se is "special" and thus all are treated the same way by default. diff --git a/min.json b/min.json index 26c60882..b59336ba 100644 --- a/min.json +++ b/min.json @@ -1,7 +1,7 @@ { "id": "min", "summary": "Minimum value", - "description": "Computes the smallest value of an array of numbers, which is equal to the last element of a sorted (i.e., ordered) version of the array.\n\nAn array without non-`null` elements resolves always with `null`.", + "description": "Computes the smallest value of an array of numbers, which is equal to the last element of a sorted (i.e., ordered) version of the array.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "math", "math > statistics", @@ -23,7 +23,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in a no-data value (or `null`).", "schema": { "type": "boolean" }, @@ -90,4 +90,4 @@ "title": "Minimum explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/mod.json b/mod.json index 0c8a6ea9..9a2a648c 100644 --- a/mod.json +++ b/mod.json @@ -1,7 +1,7 @@ { "id": "mod", "summary": "Modulo", - "description": "Remainder after a division of `x` by `y` for both integers and floating-point numbers.\n\nThe result of a modulo operation has the sign of the divisor. The handling regarding the sign of the result [differs between programming languages](https://en.wikipedia.org/wiki/Modulo_operation#In_programming_languages) and needs careful consideration to avoid unexpected results.\n\nThe no-data value `null` is passed through and therefore gets propagated if any of the arguments is `null`. If `y` is set to 0 this results in:\n\n- +infinity for `x` > 0,\n- -infinity for `x` < 0,\n- `NaN` for `x` = 0,\n- or otherwise, throws a `DivisionByZero` exception if the other options are not supported by the processing environment.", + "description": "Remainder after a division of `x` by `y` for both integers and floating-point numbers.\n\nThe result of a modulo operation has the sign of the divisor. The handling regarding the sign of the result [differs between programming languages](https://en.wikipedia.org/wiki/Modulo_operation#In_programming_languages) and needs careful consideration to avoid unexpected results.\n\nIf any argument is a no-data value, the result will be the no-data value (or `null`). If `y` is set to 0 this results in:\n\n- +infinity for `x` > 0,\n- -infinity for `x` < 0,\n- `NaN` for `x` = 0,\n- or otherwise, throws a `DivisionByZero` exception if the other options are not supported by the processing environment.", "categories": [ "math" ], diff --git a/multiply.json b/multiply.json index afa88daa..5ad94da3 100644 --- a/multiply.json +++ b/multiply.json @@ -1,7 +1,7 @@ { "id": "multiply", "summary": "Multiplication of two numbers", - "description": "Multiplies the two numbers `x` and `y` (*`x * y`*) and returns the computed product.\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": "Multiplies the two numbers `x` and `y` (*`x * y`*) and returns the computed product.\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" ], @@ -93,4 +93,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/neq.json b/neq.json index 0e22b347..1b115b3b 100644 --- a/neq.json +++ b/neq.json @@ -1,7 +1,7 @@ { "id": "neq", "summary": "Not equal to comparison", - "description": "Compares whether `x` is **not** strictly equal to `y`.\n\n**Remarks:**\n\n* Data types MUST be checked strictly. For example, a string with the content *1* is not equal to the number *1*. Nevertheless, an integer *1* is equal to a floating-point number *1.0* as `integer` is a sub-type of `number`.\n* If any operand is `null`, the return value is `null`.\n* Strings are expected to be encoded in UTF-8 by default.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is **not** strictly equal to `y`.\n\n**Remarks:**\n\n* Data types MUST be checked strictly. For example, a string with the content *1* is not equal to the number *1*. Nevertheless, an integer *1* is equal to a floating-point number *1.0* as `integer` is a sub-type of `number`.\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* Strings are expected to be encoded in UTF-8 by default.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "texts", "comparison" @@ -55,7 +55,7 @@ } ], "returns": { - "description": "`true` if `x` is *not* equal to `y`, `null` if any operand is `null`, otherwise `false`.", + "description": "`true` if `x` is *not* equal to `y`, the no-data value (or `null`) if any operand is a no-data value, otherwise `false`.", "schema": { "type": [ "boolean", @@ -145,13 +145,6 @@ "y": "2018-01-01T00:00:00+00:00" }, "returns": true - }, - { - "arguments": { - "x": null, - "y": null - }, - "returns": null } ], "process_graph": { diff --git a/not.json b/not.json index 523cb4a0..5879a767 100644 --- a/not.json +++ b/not.json @@ -1,7 +1,7 @@ { "id": "not", "summary": "Inverting a boolean", - "description": "Inverts a single boolean so that `true` gets `false` and `false` gets `true`.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Inverts a single boolean so that `true` gets `false` and `false` gets `true`.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "logic" ], @@ -46,4 +46,4 @@ "returns": false } ] -} \ No newline at end of file +} diff --git a/or.json b/or.json index 4a83a63e..c2ce931a 100644 --- a/or.json +++ b/or.json @@ -1,7 +1,7 @@ { "id": "or", "summary": "Logical OR", - "description": "Checks if **at least one** of the values is true. Evaluates parameter `x` before `y` and stops once the outcome is unambiguous. If a component 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 | null | true\nfalse || null | false | true\ntrue || true | true | true\n```", + "description": "Checks if **at least one** of the values is true. Evaluates 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 | no-data | true\nfalse || no-data | false | true\ntrue || true | true | true\n```", "categories": [ "logic" ], diff --git a/order.json b/order.json index 9b67f52d..6480fc44 100644 --- a/order.json +++ b/order.json @@ -45,7 +45,7 @@ }, { "name": "nodata", - "description": "Controls the handling of no-data values (`null`). By default, they are removed. If set to `true`, missing values in the data are put last; if set to `false`, they are put first.", + "description": "Controls the handling of no-data values. For the default value `null`, all no-data values get removed. If set to `true`, no-data values in the data are moved to the end of the array. If set to `false`, they are moved to the start of the array.", "schema": { "type": [ "boolean", diff --git a/power.json b/power.json index d01912a0..94cf7106 100644 --- a/power.json +++ b/power.json @@ -1,7 +1,7 @@ { "id": "power", "summary": "Exponentiation", - "description": "Computes the exponentiation for the base `base` raised to the power of `p`.\n\nThe no-data value `null` is passed through and therefore gets propagated if any of the arguments is `null`.", + "description": "Computes the exponentiation for the base `base` raised to the power of `p`.\n\nIf any argument is a no-data value, the result will be the no-data value (or `null`).", "categories": [ "math", "math > exponential & logarithmic" @@ -95,4 +95,4 @@ "title": "Power explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/product.json b/product.json index 6bb8428d..8e5a64b9 100644 --- a/product.json +++ b/product.json @@ -1,7 +1,7 @@ { "id": "product", "summary": "Compute the product by multiplying numbers", - "description": "Multiplies all elements in a sequential array of numbers and returns the computed product.\n\nBy default no-data values are ignored. Setting `ignore_nodata` to `false` considers no-data values 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": "Multiplies all elements in a sequential array of numbers and returns the computed product.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "math", "reducer" @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in a no-data value (or `null`).", "schema": { "type": "boolean" }, @@ -105,4 +105,4 @@ "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic" } ] -} \ No newline at end of file +} diff --git a/proposals/aggregate_spatial_window.json b/proposals/aggregate_spatial_window.json index 9e5dce4a..7b0d198f 100644 --- a/proposals/aggregate_spatial_window.json +++ b/proposals/aggregate_spatial_window.json @@ -75,7 +75,7 @@ }, { "name": "boundary", - "description": "Behavior to apply if the number of values for the axes `x` and `y` is not a multiple of the corresponding value in the `size` parameter. Options are:\n\n- `pad` (default): pad the data cube with the no-data value `null` to fit the required window size.\n\n- `trim`: trim the data cube to fit the required window size.\n\nUse the parameter `align` to align the data to the desired corner.", + "description": "Behavior to apply if the number of values for the axes `x` and `y` is not a multiple of the corresponding value in the `size` parameter. Options are:\n\n- `pad` (default): pad the data cube with the no-data value to fit the required window size.\n\n- `trim`: trim the data cube to fit the required window size.\n\nUse the parameter `align` to align the data to the desired corner.", "schema": { "type": "string", "enum": [ diff --git a/proposals/apply_polygon.json b/proposals/apply_polygon.json index 735226a1..fe48ab5f 100644 --- a/proposals/apply_polygon.json +++ b/proposals/apply_polygon.json @@ -71,7 +71,7 @@ }, { "name": "mask_value", - "description": "All pixels for which the point at the pixel center **does not** intersect with the polygon are replaced with the given value, which defaults to `null` (no data).\n\nIt can provide a distinction between no data values within the polygon and masked pixels outside of it.", + "description": "All pixels for which the point at the pixel center **does not** intersect with the polygon are replaced with the given value. The default value is `null`, which uses the no-data value of the data cube.\n\nThis parameter can provide a distinction between no-data values within the polygon and masked pixels outside of it.", "schema": [ { "type": "number" diff --git a/proposals/ard_normalized_radar_backscatter.json b/proposals/ard_normalized_radar_backscatter.json index ec60de44..7a9204ec 100644 --- a/proposals/ard_normalized_radar_backscatter.json +++ b/proposals/ard_normalized_radar_backscatter.json @@ -31,7 +31,7 @@ }, { "name": "elevation_model", - "description": "The digital elevation model to use. Set to `null` (the default) to allow the back-end to choose, which will improve portability, but reduce reproducibility.", + "description": "The digital elevation model to use. The default value `null` allows the back-end to choose, which will improve portability, but reduce reproducibility.", "optional": true, "default": null, "schema": [ @@ -83,7 +83,7 @@ } ], "returns": { - "description": "Backscatter values expressed as gamma0 in linear scale.\n\nIn addition to the bands `contributing_area` and `ellipsoid_incidence_angle` that can optionally be added with corresponding parameters, the following bands are always added to the data cube:\n\n- `mask`: A data mask that indicates which values are valid (1), invalid (0) or contain no-data (null).\n- `local_incidence_angle`: A band with DEM-based local incidence angles in degrees.\n\nThe data returned is CARD4L compliant with corresponding metadata.", + "description": "Backscatter values expressed as gamma0 in linear scale.\n\nIn addition to the bands `contributing_area` and `ellipsoid_incidence_angle` that can optionally be added with corresponding parameters, the following bands are always added to the data cube:\n\n- `mask`: A data mask that indicates which values are valid (1), invalid (0), or contain a no-data value.\n- `local_incidence_angle`: A band with DEM-based local incidence angles in degrees.\n\nThe data returned is CARD4L compliant with corresponding metadata.", "schema": { "type": "object", "subtype": "datacube", diff --git a/proposals/ard_surface_reflectance.json b/proposals/ard_surface_reflectance.json index 01328f10..74f3347f 100644 --- a/proposals/ard_surface_reflectance.json +++ b/proposals/ard_surface_reflectance.json @@ -57,7 +57,7 @@ } }, { - "description": "The digital elevation model to use. Set to `null` (the default) to allow the back-end to choose, which will improve portability, but reduce reproducibility.", + "description": "The digital elevation model to use. The default value `null` allows the back-end to choose, which will improve portability, but reduce reproducibility.", "name": "elevation_model", "optional": true, "default": null, @@ -93,7 +93,7 @@ } ], "returns": { - "description": "Data cube containing bottom of atmosphere reflectances for each spectral band in the source data cube, with atmospheric disturbances like clouds and cloud shadows removed. No-data values (null) are directly set in the bands. Depending on the methods used, several additional bands will be added to the data cube:\n\nData cube containing bottom of atmosphere reflectances for each spectral band in the source data cube, with atmospheric disturbances like clouds and cloud shadows removed. Depending on the methods used, several additional bands will be added to the data cube:\n\n- `date` (optional): Specifies per-pixel acquisition timestamps.\n- `incomplete-testing` (required): Identifies pixels with a value of 1 for which the per-pixel tests (at least saturation, cloud and cloud shadows, see CARD4L specification for details) have not all been successfully completed. Otherwise, the value is 0.\n- `saturation` (required) / `saturation_{band}` (optional): Indicates where pixels in the input spectral bands are saturated (1) or not (0). If the saturation is given per band, the band names are `saturation_{band}` with `{band}` being the band name from the source data cube.\n- `cloud`, `shadow` (both required),`aerosol`, `haze`, `ozone`, `water_vapor` (all optional): Indicates the probability of pixels being an atmospheric disturbance such as clouds. All bands have values between 0 (clear) and 1, which describes the probability that it is an atmospheric disturbance.\n- `snow-ice` (optional): Points to a file that indicates whether a pixel is assessed as being snow/ice (1) or not (0). All values describe the probability and must be between 0 and 1.\n- `land-water` (optional): Indicates whether a pixel is assessed as being land (1) or water (0). All values describe the probability and must be between 0 and 1.\n- `incidence-angle` (optional): Specifies per-pixel incidence angles in degrees.\n- `azimuth` (optional): Specifies per-pixel azimuth angles in degrees.\n- `sun-azimuth:` (optional): Specifies per-pixel sun azimuth angles in degrees.\n- `sun-elevation` (optional): Specifies per-pixel sun elevation angles in degrees.\n- `terrain-shadow` (optional): Indicates with a value of 1 whether a pixel is not directly illuminated due to terrain shadowing. Otherwise, the value is 0.\n- `terrain-occlusion` (optional): Indicates with a value of 1 whether a pixel is not visible to the sensor due to terrain occlusion during off-nadir viewing. Otherwise, the value is 0.\n- `terrain-illumination` (optional): Contains coefficients used for terrain illumination correction are provided for each pixel.\n\nThe data returned is CARD4L compliant with corresponding metadata.", + "description": "Data cube containing bottom of atmosphere reflectances for each spectral band in the source data cube, with atmospheric disturbances like clouds and cloud shadows removed. No-data values are directly set in the bands. Depending on the methods used, several additional bands will be added to the data cube:\n\nData cube containing bottom of atmosphere reflectances for each spectral band in the source data cube, with atmospheric disturbances like clouds and cloud shadows removed. Depending on the methods used, several additional bands will be added to the data cube:\n\n- `date` (optional): Specifies per-pixel acquisition timestamps.\n- `incomplete-testing` (required): Identifies pixels with a value of 1 for which the per-pixel tests (at least saturation, cloud and cloud shadows, see CARD4L specification for details) have not all been successfully completed. Otherwise, the value is 0.\n- `saturation` (required) / `saturation_{band}` (optional): Indicates where pixels in the input spectral bands are saturated (1) or not (0). If the saturation is given per band, the band names are `saturation_{band}` with `{band}` being the band name from the source data cube.\n- `cloud`, `shadow` (both required),`aerosol`, `haze`, `ozone`, `water_vapor` (all optional): Indicates the probability of pixels being an atmospheric disturbance such as clouds. All bands have values between 0 (clear) and 1, which describes the probability that it is an atmospheric disturbance.\n- `snow-ice` (optional): Points to a file that indicates whether a pixel is assessed as being snow/ice (1) or not (0). All values describe the probability and must be between 0 and 1.\n- `land-water` (optional): Indicates whether a pixel is assessed as being land (1) or water (0). All values describe the probability and must be between 0 and 1.\n- `incidence-angle` (optional): Specifies per-pixel incidence angles in degrees.\n- `azimuth` (optional): Specifies per-pixel azimuth angles in degrees.\n- `sun-azimuth:` (optional): Specifies per-pixel sun azimuth angles in degrees.\n- `sun-elevation` (optional): Specifies per-pixel sun elevation angles in degrees.\n- `terrain-shadow` (optional): Indicates with a value of 1 whether a pixel is not directly illuminated due to terrain shadowing. Otherwise, the value is 0.\n- `terrain-occlusion` (optional): Indicates with a value of 1 whether a pixel is not visible to the sensor due to terrain occlusion during off-nadir viewing. Otherwise, the value is 0.\n- `terrain-illumination` (optional): Contains coefficients used for terrain illumination correction are provided for each pixel.\n\nThe data returned is CARD4L compliant with corresponding metadata.", "schema": { "type": "object", "subtype": "datacube", diff --git a/proposals/atmospheric_correction.json b/proposals/atmospheric_correction.json index d366f1ed..57575f78 100644 --- a/proposals/atmospheric_correction.json +++ b/proposals/atmospheric_correction.json @@ -47,7 +47,7 @@ ] }, { - "description": "The digital elevation model to use. Set to `null` (the default) to allow the back-end to choose, which will improve portability, but reduce reproducibility.", + "description": "The digital elevation model to use. The default value `null` allows the back-end to choose, which will improve portability, but reduce reproducibility.", "name": "elevation_model", "optional": true, "default": null, diff --git a/proposals/cummax.json b/proposals/cummax.json index 69580459..95532334 100644 --- a/proposals/cummax.json +++ b/proposals/cummax.json @@ -1,7 +1,7 @@ { "id": "cummax", "summary": "Cumulative maxima", - "description": "Finds cumulative maxima of an array of numbers. Every computed element is equal to the bigger one between the current element and the previously computed element. The returned array and the input array have always the same length.\n\nBy default, no-data values are skipped, but stay in the result. Setting the `ignore_nodata` flag to `true` makes that once a no-data value (`null`) is reached all following elements are set to `null` in the result.", + "description": "Finds cumulative maxima of an array of numbers. Every computed element is equal to the bigger one between the current element and the previously computed element. The returned array and the input array have always the same length.\n\nBy default, no-data values are skipped, but stay in the result. Setting the `ignore_nodata` flag to `true` makes that once a no-data value is reached all following elements are set to the no-data value in the result.", "categories": [ "math > cumulative" ], @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not and ignores them by default. Setting this flag to `false` considers no-data values so that `null` is set for all the following elements.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, the first no-data value makes all following values also no-data values.", "schema": { "type": "boolean" }, @@ -99,4 +99,4 @@ ] } ] -} \ No newline at end of file +} diff --git a/proposals/cummin.json b/proposals/cummin.json index d84612e3..50cd3b00 100644 --- a/proposals/cummin.json +++ b/proposals/cummin.json @@ -1,7 +1,7 @@ { "id": "cummin", "summary": "Cumulative minima", - "description": "Finds cumulative minima of an array of numbers. Every computed element is equal to the smaller one between the current element and the previously computed element. The returned array and the input array have always the same length.\n\nBy default, no-data values are skipped, but stay in the result. Setting the `ignore_nodata` flag to `true` makes that once a no-data value (`null`) is reached all following elements are set to `null` in the result.", + "description": "Finds cumulative minima of an array of numbers. Every computed element is equal to the smaller one between the current element and the previously computed element. The returned array and the input array have always the same length.\n\nBy default, no-data values are skipped, but stay in the result. Setting the `ignore_nodata` flag to `true` makes that once a no-data value is reached all following elements are set to the no-data value in the result.", "categories": [ "math > cumulative" ], @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not and ignores them by default. Setting this flag to `false` considers no-data values so that `null` is set for all the following elements.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, the first no-data value makes all following values also no-data values.", "schema": { "type": "boolean" }, @@ -99,4 +99,4 @@ ] } ] -} \ No newline at end of file +} diff --git a/proposals/cumproduct.json b/proposals/cumproduct.json index f5e6ae1b..3c7b455e 100644 --- a/proposals/cumproduct.json +++ b/proposals/cumproduct.json @@ -1,7 +1,7 @@ { "id": "cumproduct", "summary": "Cumulative products", - "description": "Computes cumulative products of an array of numbers. Every computed element is equal to the product of the current and all previous values. The returned array and the input array have always the same length.\n\nBy default, no-data values are skipped, but stay in the result. Setting the `ignore_nodata` flag to `true` makes that once a no-data value (`null`) is reached all following elements are set to `null` in the result.", + "description": "Computes cumulative products of an array of numbers. Every computed element is equal to the product of the current and all previous values. The returned array and the input array have always the same length.\n\nBy default, no-data values are skipped, but stay in the result. Setting the `ignore_nodata` flag to `true` makes that once a no-data value is reached all following elements are set to the no-data value in the result.", "categories": [ "math > cumulative" ], @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not and ignores them by default. Setting this flag to `false` considers no-data values so that `null` is set for all the following elements.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, the first no-data value makes all following values also no-data values.", "schema": { "type": "boolean" }, @@ -103,4 +103,4 @@ ] } ] -} \ No newline at end of file +} diff --git a/proposals/cumsum.json b/proposals/cumsum.json index 717999e5..abd0e2c3 100644 --- a/proposals/cumsum.json +++ b/proposals/cumsum.json @@ -1,7 +1,7 @@ { "id": "cumsum", "summary": "Cumulative sums", - "description": "Computes cumulative sums of an array of numbers. Every computed element is equal to the sum of current and all previous values. The returned array and the input array have always the same length.\n\nBy default, no-data values are skipped, but stay in the result. Setting the `ignore_nodata` flag to `true` makes that once a no-data value (`null`) is reached all following elements are set to `null` in the result.", + "description": "Computes cumulative sums of an array of numbers. Every computed element is equal to the sum of current and all previous values. The returned array and the input array have always the same length.\n\nBy default, no-data values are skipped, but stay in the result. Setting the `ignore_nodata` flag to `true` makes that once a no-data value is reached all following elements are set to the no-data value in the result.", "categories": [ "math > cumulative" ], @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not and ignores them by default. Setting this flag to `false` considers no-data values so that `null` is set for all the following elements.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, the first no-data value makes all following values also no-data values.", "schema": { "type": "boolean" }, @@ -99,4 +99,4 @@ ] } ] -} \ No newline at end of file +} diff --git a/proposals/fit_curve.json b/proposals/fit_curve.json index aafb917e..407e9547 100644 --- a/proposals/fit_curve.json +++ b/proposals/fit_curve.json @@ -69,7 +69,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is passed to the model function.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that no-data values are passed to the model function.", "schema": { "type": "boolean" }, diff --git a/proposals/load_geojson.json b/proposals/load_geojson.json index 70566a56..89e8440b 100644 --- a/proposals/load_geojson.json +++ b/proposals/load_geojson.json @@ -18,7 +18,7 @@ }, { "name": "properties", - "description": "A list of properties from the GeoJSON file to construct an additional dimension from. A new dimension with the name `properties` and type `other` is created if at least one property is provided. Only applies for GeoJSON Features and FeatureCollections. Missing values are generally set to no-data (`null`).\n\nDepending on the number of properties provided, the process creates the dimension differently:\n\n- Single property with scalar values: A single dimension label with the name of the property and a single value per geometry.\n- Single property of type array: The dimension labels correspond to the array indices. There are as many values and labels per geometry as there are for the largest array.\n- Multiple properties with scalar values: The dimension labels correspond to the property names. There are as many values and labels per geometry as there are properties provided here.", + "description": "A list of properties from the GeoJSON file to construct an additional dimension from. A new dimension with the name `properties` and type `other` is created if at least one property is provided. Only applies for GeoJSON Features and FeatureCollections. Missing values are generally set to the no-data value in the data cube.\n\nDepending on the number of properties provided, the process creates the dimension differently:\n\n- Single property with scalar values: A single dimension label with the name of the property and a single value per geometry.\n- Single property of type array: The dimension labels correspond to the array indices. There are as many values and labels per geometry as there are for the largest array.\n- Multiple properties with scalar values: The dimension labels correspond to the property names. There are as many values and labels per geometry as there are properties provided here.", "schema": { "type": "array", "uniqueItems": true, diff --git a/proposals/load_stac.json b/proposals/load_stac.json index 262745fc..318edc67 100644 --- a/proposals/load_stac.json +++ b/proposals/load_stac.json @@ -90,13 +90,13 @@ }, { "title": "GeoJSON", - "description": "Limits the data cube to the bounding box of the given geometries. For raster data, all pixels inside the bounding box that do not intersect with any of the polygons will be set to no data (`null`).\n\nThe GeoJSON type `GeometryCollection` is not supported. Empty geometries are ignored.", + "description": "Limits the data cube to the bounding box of the given geometries. For raster data, all pixels inside the bounding box that do not intersect with any of the polygons will be set to the no-data value of the data cube.\n\nThe GeoJSON type `GeometryCollection` is not supported. Empty geometries are ignored.", "type": "object", "subtype": "geojson" }, { "title": "Vector data cube", - "description": "Limits the data cube to the bounding box of the given geometries in the vector data cube. All pixels inside the bounding box that do not intersect with any of the polygons will be set to no data (`null`). Empty geometries are ignored.", + "description": "Limits the data cube to the bounding box of the given geometries in the vector data cube. All pixels inside the bounding box that do not intersect with any of the polygons will be set to the no-data value of the data cube. Empty geometries are ignored.", "type": "object", "subtype": "datacube", "dimensions": [ diff --git a/proposals/predict_curve.json b/proposals/predict_curve.json index ef3e9596..204cbb3f 100644 --- a/proposals/predict_curve.json +++ b/proposals/predict_curve.json @@ -59,7 +59,7 @@ }, { "name": "labels", - "description": "The labels to predict values for. If no labels are given, predicts values only for no-data (`null`) values in the data cube.", + "description": "The labels to predict values for. If no labels are given, predicts values only for no-data values in the data cube.", "optional": true, "default": null, "schema": [ diff --git a/proposals/sar_backscatter.json b/proposals/sar_backscatter.json index 03d13d29..6fb2503a 100644 --- a/proposals/sar_backscatter.json +++ b/proposals/sar_backscatter.json @@ -52,7 +52,7 @@ }, { "name": "elevation_model", - "description": "The digital elevation model to use. Set to `null` (the default) to allow the back-end to choose, which will improve portability, but reduce reproducibility.", + "description": "The digital elevation model to use. The default value `null` allows the back-end to choose, which will improve portability, but reduce reproducibility.", "optional": true, "default": null, "schema": [ @@ -67,7 +67,7 @@ }, { "name": "mask", - "description": "If set to `true`, a data mask is added to the bands with the name `mask`. It indicates which values are valid (1), invalid (0) or contain no-data (null).", + "description": "If set to `true`, a data mask is added to the bands with the name `mask`. It indicates which values are valid (1), invalid (0), or contain a no-data value.", "optional": true, "default": false, "schema": { diff --git a/proposals/vector_to_random_points.json b/proposals/vector_to_random_points.json index b568b54c..6eda87ad 100644 --- a/proposals/vector_to_random_points.json +++ b/proposals/vector_to_random_points.json @@ -1,7 +1,7 @@ { "id": "vector_to_random_points", "summary": "Sample random points from geometries", - "description": "Generate a vector data cube of points by sampling random points from input geometries. At least one point is sampled per input geometry. Empty geometries are passed through without any points assigned. Feature properties are preserved.\n\nIf `geometry_count` and `total_count` are both unrestricted (i.e. set to `null`, which is the default), one sample per geometry is used.", + "description": "Generate a vector data cube of points by sampling random points from input geometries. At least one point is sampled per input geometry. Empty geometries are passed through without any points assigned. Feature properties are preserved.\n\nIf `geometry_count` and `total_count` are both unrestricted (i.e. set to the default value `null`), one sample per geometry is used.", "categories": [ "cubes", "vector" diff --git a/quantiles.json b/quantiles.json index 033a4d89..f47fc5a9 100644 --- a/quantiles.json +++ b/quantiles.json @@ -53,7 +53,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that an array with `null` values is returned if any element is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in an array with solely no-data (or `null`) values.", "schema": { "type": "boolean" }, diff --git a/resample_cube_temporal.json b/resample_cube_temporal.json index 260954d0..e8308a01 100644 --- a/resample_cube_temporal.json +++ b/resample_cube_temporal.json @@ -1,7 +1,7 @@ { "id": "resample_cube_temporal", "summary": "Resample temporal dimensions to match a target data cube", - "description": "Resamples one or more given temporal dimensions from a source data cube to align with the corresponding dimensions of the given target data cube using the nearest neighbor method. Returns a new data cube with the resampled dimensions.\n\nBy default, this process simply takes the nearest neighbor independent of the value (including values such as no-data / `null`). Depending on the data cubes this may lead to values being assigned to two target timestamps. To only consider valid values in a specific range around the target timestamps, use the parameter `valid_within`.\n\nThe rare case of ties is resolved by choosing the earlier timestamps.", + "description": "Resamples one or more given temporal dimensions from a source data cube to align with the corresponding dimensions of the given target data cube using the nearest neighbor method. Returns a new data cube with the resampled dimensions.\n\nBy default, this process simply takes the nearest neighbor independent of the value (including no-data values). Depending on the data cubes this may lead to values being assigned to two target timestamps. To only consider valid values in a specific range around the target timestamps, use the parameter `valid_within`.\n\nThe rare case of ties is resolved by choosing the earlier timestamps.", "categories": [ "cubes", "reproject" @@ -47,7 +47,7 @@ }, { "name": "valid_within", - "description": "Setting this parameter to a numerical value enables that the process searches for valid values within the given period of days before and after the target timestamps. Valid values are determined based on the function ``is_valid()``. For example, the limit of `7` for the target timestamps `2020-01-15 12:00:00` looks for a nearest neighbor after `2020-01-08 12:00:00` and before `2020-01-22 12:00:00`. If no valid value is found within the given period, the value will be set to no-data (`null`).", + "description": "Setting this parameter to a numerical value enables that the process searches for valid values within the given period of days before and after the target timestamps. Valid values are determined based on the function ``is_valid()``. For example, the limit of `7` for the target timestamps `2020-01-15 12:00:00` looks for a nearest neighbor after `2020-01-08 12:00:00` and before `2020-01-22 12:00:00`. If no valid value is found within the given period, the value will be set to the no-data value of the data cube given for the parameter `data`.", "schema": { "type": [ "number", diff --git a/resample_spatial.json b/resample_spatial.json index fb34f194..418f13ec 100644 --- a/resample_spatial.json +++ b/resample_spatial.json @@ -49,7 +49,7 @@ }, { "name": "projection", - "description": "Warps the data cube to the target projection, specified as as [EPSG code](http://www.epsg-registry.org/) or [WKT2 CRS string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html). By default (`null`), the projection is not changed.", + "description": "Warps the data cube to the target projection, specified as as [EPSG code](http://www.epsg-registry.org/) or [WKT2 CRS string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html). For the default value `null`, the projection is not changed.", "schema": [ { "title": "EPSG Code", diff --git a/round.json b/round.json index cb1ff9e0..aa1d8d87 100644 --- a/round.json +++ b/round.json @@ -1,7 +1,7 @@ { "id": "round", "summary": "Round to a specified precision", - "description": "Rounds a real number `x` to specified precision `p`.\n\nIf `x` is halfway between closest numbers of precision `p`, it is rounded to the closest even number of precision `p`.\nThis behavior follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) and is often called \"round to nearest (even)\" or \"banker's rounding\". It minimizes rounding errors that result from consistently rounding a midpoint value in a single direction.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Rounds a real number `x` to specified precision `p`.\n\nIf `x` is halfway between closest numbers of precision `p`, it is rounded to the closest even number of precision `p`.\nThis behavior follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) and is often called \"round to nearest (even)\" or \"banker's rounding\". It minimizes rounding errors that result from consistently rounding a midpoint value in a single direction.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > rounding" ], diff --git a/sd.json b/sd.json index 156e4b38..4616756b 100644 --- a/sd.json +++ b/sd.json @@ -1,7 +1,7 @@ { "id": "sd", "summary": "Standard deviation", - "description": "Computes the sample standard deviation, which quantifies the amount of variation of an array of numbers. It is defined to be the square root of the corresponding variance (see ``variance()``).\n\nA low standard deviation indicates that the values tend to be close to the expected value, while a high standard deviation indicates that the values are spread out over a wider range.\n\nAn array without non-`null` elements resolves always with `null`.", + "description": "Computes the sample standard deviation, which quantifies the amount of variation of an array of numbers. It is defined to be the square root of the corresponding variance (see ``variance()``).\n\nA low standard deviation indicates that the values tend to be close to the expected value, while a high standard deviation indicates that the values are spread out over a wider range.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "math > statistics", "reducer" @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in a no-data value (or `null`).", "schema": { "type": "boolean" }, @@ -62,13 +62,6 @@ "ignore_nodata": false }, "returns": null - }, - { - "description": "The input array is empty: return `null`.", - "arguments": { - "data": [] - }, - "returns": null } ], "links": [ @@ -101,4 +94,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/sgn.json b/sgn.json index ecdbd9d1..5019957e 100644 --- a/sgn.json +++ b/sgn.json @@ -1,7 +1,7 @@ { "id": "sgn", "summary": "Signum", - "description": "The signum (also known as *sign*) of `x` is defined as:\n\n* *1* if *x > 0*\n* *0* if *x = 0*\n* *-1* if *x < 0*\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "The signum (also known as *sign*) of `x` is defined as:\n\n* *1* if *x > 0*\n* *0* if *x = 0*\n* *-1* if *x < 0*\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math" ], diff --git a/sin.json b/sin.json index 15285979..01fbc9cb 100644 --- a/sin.json +++ b/sin.json @@ -1,7 +1,7 @@ { "id": "sin", "summary": "Sine", - "description": "Computes the sine of `x`.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the sine of `x`.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > trigonometric" ], diff --git a/sinh.json b/sinh.json index 6eced19c..3ee8271e 100644 --- a/sinh.json +++ b/sinh.json @@ -1,7 +1,7 @@ { "id": "sinh", "summary": "Hyperbolic sine", - "description": "Computes the hyperbolic sine of `x`.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the hyperbolic sine of `x`.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > trigonometric" ], diff --git a/sort.json b/sort.json index 422f8d53..a375e386 100644 --- a/sort.json +++ b/sort.json @@ -45,7 +45,7 @@ }, { "name": "nodata", - "description": "Controls the handling of no-data values (`null`). By default, they are removed. If set to `true`, missing values in the data are put last; if set to `false`, they are put first.", + "description": "Controls the handling of no-data values. For the default value `null`, all no-data values get removed. If set to `true`, no-data values in the data are moved to the end of the array. If set to `false`, they are moved to the start of the array.", "schema": { "type": [ "boolean", diff --git a/sqrt.json b/sqrt.json index b85caf94..efe65919 100644 --- a/sqrt.json +++ b/sqrt.json @@ -1,7 +1,7 @@ { "id": "sqrt", "summary": "Square root", - "description": "Computes the square root of a real number `x`, which is equal to calculating `x` to the power of *0.5*. For negative `x`, the process returns `NaN`.\n\nA square root of x is a number a such that *`a² = x`*. Therefore, the square root is the inverse function of a to the power of 2, but only for *a >= 0*.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the square root of a real number `x`, which is equal to calculating `x` to the power of *0.5*. For negative `x`, the process returns `NaN`.\n\nA square root of x is a number a such that *`a² = x`*. Therefore, the square root is the inverse function of a to the power of 2, but only for *a >= 0*.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math", "math > exponential & logarithmic" diff --git a/subtract.json b/subtract.json index 2cf8aba7..feb24c06 100644 --- a/subtract.json +++ b/subtract.json @@ -1,7 +1,7 @@ { "id": "subtract", "summary": "Subtraction of two numbers", - "description": "Subtracts argument `y` from the argument `x` (*`x - y`*) and returns the computed result.\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": "Subtracts argument `y` from the argument `x` (*`x - y`*) and returns the computed result.\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" ], @@ -71,4 +71,4 @@ "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic" } ] -} \ No newline at end of file +} diff --git a/sum.json b/sum.json index 17af5bfe..912ba47a 100644 --- a/sum.json +++ b/sum.json @@ -1,7 +1,7 @@ { "id": "sum", "summary": "Compute the sum by adding up numbers", - "description": "Sums up all elements in a sequential array of numbers and returns the computed sum.\n\nBy default no-data values are ignored. Setting `ignore_nodata` to `false` considers no-data values 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 all elements in a sequential array of numbers and returns the computed sum.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "math", "reducer" @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in a no-data value (or `null`).", "schema": { "type": "boolean" }, @@ -105,4 +105,4 @@ "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic" } ] -} \ No newline at end of file +} diff --git a/tan.json b/tan.json index 6e927ffc..59557039 100644 --- a/tan.json +++ b/tan.json @@ -1,7 +1,7 @@ { "id": "tan", "summary": "Tangent", - "description": "Computes the tangent of `x`. The tangent is defined to be the sine of x divided by the cosine of x.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`tan(pi()/2 + multipliy(pi(), n))`* with `n` being any integer results in ±infinity. -infinity for negative values passed to `tan`, +infinity otherwise. If the processing environment does not supports it, an exception is thrown.", + "description": "Computes the tangent of `x`. The tangent is defined to be the sine of x divided by the cosine of x.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`tan(pi()/2 + multipliy(pi(), n))`* with `n` being any integer results in ±infinity. -infinity for negative values passed to `tan`, +infinity otherwise. If the processing environment does not supports it, an exception is thrown.", "categories": [ "math > trigonometric" ], diff --git a/tanh.json b/tanh.json index a38462c9..96b15804 100644 --- a/tanh.json +++ b/tanh.json @@ -1,7 +1,7 @@ { "id": "tanh", "summary": "Hyperbolic tangent", - "description": "Computes the hyperbolic tangent of `x`. The tangent is defined to be the hyperbolic sine of x divided by the hyperbolic cosine of x.\n\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the hyperbolic tangent of `x`. The tangent is defined to be the hyperbolic sine of x divided by the hyperbolic cosine of x.\n\nNo-data values are passed through and therefore get propagated.", "categories": [ "math > trigonometric" ], diff --git a/text_begins.json b/text_begins.json index 766d5f0f..f422999f 100644 --- a/text_begins.json +++ b/text_begins.json @@ -1,7 +1,7 @@ { "id": "text_begins", "summary": "Text begins with another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the beginning. Both are expected to be encoded in UTF-8 by default. The no-data value `null` is passed through and therefore gets propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the beginning. Both are expected to be encoded in UTF-8 by default. No-data values are passed through and therefore get propagated.", "categories": [ "texts", "comparison" diff --git a/text_contains.json b/text_contains.json index 9b78318f..d0046131 100644 --- a/text_contains.json +++ b/text_contains.json @@ -1,7 +1,7 @@ { "id": "text_contains", "summary": "Text contains another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern`. Both are expected to be encoded in UTF-8 by default. The no-data value `null` is passed through and therefore gets propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern`. Both are expected to be encoded in UTF-8 by default. No-data values are passed through and therefore get propagated.", "categories": [ "texts", "comparison" diff --git a/text_ends.json b/text_ends.json index f31e8e12..7bd2238c 100644 --- a/text_ends.json +++ b/text_ends.json @@ -1,7 +1,7 @@ { "id": "text_ends", "summary": "Text ends with another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the end. Both are expected to be encoded in UTF-8 by default. The no-data value `null` is passed through and therefore gets propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the end. Both are expected to be encoded in UTF-8 by default. No-data values are passed through and therefore get propagated.", "categories": [ "texts", "comparison" diff --git a/variance.json b/variance.json index 78f76feb..0ab044d7 100644 --- a/variance.json +++ b/variance.json @@ -1,7 +1,7 @@ { "id": "variance", "summary": "Variance", - "description": "Computes the sample variance of an array of numbers by calculating the square of the standard deviation (see ``sd()``). It is defined to be the expectation of the squared deviation of a random variable from its expected value. Basically, it measures how far the numbers in the array are spread out from their average value.\n\nAn array without non-`null` elements resolves always with `null`.", + "description": "Computes the sample variance of an array of numbers by calculating the square of the standard deviation (see ``sd()``). It is defined to be the expectation of the squared deviation of a random variable from its expected value. Basically, it measures how far the numbers in the array are spread out from their average value.\n\nAn array with solely no-data values returns the no-data value (or `null`).", "categories": [ "math > statistics", "reducer" @@ -22,7 +22,7 @@ }, { "name": "ignore_nodata", - "description": "Indicates whether no-data values are ignored or not. Ignores them by default. Setting this flag to `false` considers no-data values so that `null` is returned if any value is such a value.", + "description": "Indicates whether no-data values are ignored or not. Ignores them by default. If set to `false`, any no-data value in the array results in a no-data value (or `null`).", "schema": { "type": "boolean" }, @@ -75,13 +75,6 @@ "ignore_nodata": false }, "returns": null - }, - { - "description": "The input array is empty: return `null`.", - "arguments": { - "data": [] - }, - "returns": null } ], "links": [ @@ -149,4 +142,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/xor.json b/xor.json index 6af7ae5e..01b8efda 100644 --- a/xor.json +++ b/xor.json @@ -1,7 +1,7 @@ { "id": "xor", "summary": "Logical XOR (exclusive or)", - "description": "Checks if **exactly one** of the values is true. If a component 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 | null | null\nfalse || null | false | true\ntrue || null | true | false\n```", + "description": "Checks if **exactly one** of the values is true. 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 | no-data | no-data\nfalse || no-data | false | true\ntrue || no-data | true | false\n```", "categories": [ "logic" ], From d19039a6f3d205991c8138f78f441e804ae7db40 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 3 Jan 2024 14:56:03 +0100 Subject: [PATCH 2/3] Clarify NaN in comparisons, clarify character encoding issues --- CHANGELOG.md | 8 ++++++-- eq.json | 9 ++++++++- gt.json | 9 ++++++++- gte.json | 9 ++++++++- lt.json | 9 ++++++++- lte.json | 9 ++++++++- meta/implementation.md | 22 ++++++++++++++++++---- neq.json | 9 ++++++++- proposals/is_infinite.json | 4 ++-- text_begins.json | 2 +- text_contains.json | 2 +- text_ends.json | 2 +- 12 files changed, 77 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4811eee..f4ec2834 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,8 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed -- 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) +- 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) - `array_interpolate_linear`: Apply interpolation to NaN and no-data values. - `clip`: Throw an exception if min > max. [#472](https://github.com/Open-EO/openeo-processes/issues/472) diff --git a/eq.json b/eq.json index b1b23385..73ffaaa4 100644 --- a/eq.json +++ b/eq.json @@ -1,7 +1,7 @@ { "id": "eq", "summary": "Equal to comparison", - "description": "Compares whether `x` is strictly equal to `y`.\n\n**Remarks:**\n\n* Data types MUST be checked strictly. For example, a string with the content *1* is not equal to the number *1*. Nevertheless, an integer *1* is equal to a floating-point number *1.0* as `integer` is a sub-type of `number`.\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is strictly equal to `y`.\n\n**Remarks:**\n\n* Data types MUST be checked strictly. For example, a string with the content *1* is not equal to the number *1*. Nevertheless, an integer *1* is equal to a floating-point number *1.0* as `integer` is a sub-type of `number`.\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* The comparison of `NaN` (not a number) follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229).\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "texts", "comparison" @@ -146,5 +146,12 @@ }, "returns": false } + ], + "links": [ + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/4610935", + "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" + } ] } diff --git a/gt.json b/gt.json index 542f618c..dbb33296 100644 --- a/gt.json +++ b/gt.json @@ -1,7 +1,7 @@ { "id": "gt", "summary": "Greater than comparison", - "description": "Compares whether `x` is strictly greater than `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* If any operand is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is strictly greater than `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* The comparison of `NaN` (not a number) follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229).\n* If any operand is not the data type `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "comparison" ], @@ -90,5 +90,12 @@ }, "returns": false } + ], + "links": [ + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/4610935", + "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" + } ] } diff --git a/gte.json b/gte.json index 712b6b9c..3c054ba8 100644 --- a/gte.json +++ b/gte.json @@ -1,7 +1,7 @@ { "id": "gte", "summary": "Greater than or equal to comparison", - "description": "Compares whether `x` is greater than or equal to `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* If the operands are not equal (see process ``eq()``) and any of them is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is greater than or equal to `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* The comparison of `NaN` (not a number) follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229).\n* If the operands are not equal (see process ``eq()``) and any of them is not the data type `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "comparison" ], @@ -84,6 +84,13 @@ "returns": false } ], + "links": [ + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/4610935", + "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" + } + ], "process_graph": { "eq": { "process_id": "eq", diff --git a/lt.json b/lt.json index b7e35bf4..bcb167b1 100644 --- a/lt.json +++ b/lt.json @@ -1,7 +1,7 @@ { "id": "lt", "summary": "Less than comparison", - "description": "Compares whether `x` is strictly less than `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* If any operand is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is strictly less than `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* The comparison of `NaN` (not a number) follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229).\n* If any operand is not the data type `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "comparison" ], @@ -90,5 +90,12 @@ }, "returns": false } + ], + "links": [ + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/4610935", + "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" + } ] } diff --git a/lte.json b/lte.json index 5ab05126..0968dfa1 100644 --- a/lte.json +++ b/lte.json @@ -1,7 +1,7 @@ { "id": "lte", "summary": "Less than or equal to comparison", - "description": "Compares whether `x` is less than or equal to `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* If the operands are not equal (see process ``eq()``) and any of them is not a `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is less than or equal to `y`.\n\n**Remarks:**\n\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* The comparison of `NaN` (not a number) follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229).\n* If the operands are not equal (see process ``eq()``) and any of them is not the data type `number`, the process returns `false`.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "comparison" ], @@ -84,6 +84,13 @@ "returns": false } ], + "links": [ + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/4610935", + "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" + } + ], "process_graph": { "eq": { "process_id": "eq", diff --git a/meta/implementation.md b/meta/implementation.md index fafe6ea0..0f7e75ca 100644 --- a/meta/implementation.md +++ b/meta/implementation.md @@ -4,16 +4,16 @@ This file is meant to provide some additional implementation details for back-en ## No-data value -A data cube shall always keep reference of the applicable no-data values. -The no-data value can be chosen by the back-end implementation, e.g. depending on the data type of the data. +A data cube shall always keep reference of the applicable no-data value(s). +The no-data values can be chosen by the back-end implementation, e.g. depending on the data type of the data. No-data values should be exposed for each pre-defined Collection in its metadata. For all data generated through openEO (e.g. through synchronous or batch jobs), the metadata and/or data shall expose the no-data values. -The openEO process specifications generally use `null` as a generic value to express no-data values. +The openEO process specifications generally uses `null` as a generic value to express no-data values. This is primarily meant for the JSON encoding, this means: 1. in the process specification (data type `null` in the schema), and -2. in the process graph (if the no-data value exposed through the metadata can't be used in JSON). +2. in the process graph (if the no-data value exposed through the metadata can't be used in JSON, e.g. `NaN`). Back-ends may or may not use `null` as a no-data value internally. @@ -23,12 +23,26 @@ no-data values in openEO and `NaN` (IEEE 754) sometimes differs. **Array processes:** Some array processes (e.g. `array_find` or `any`) use `null` as a return value. In the context of data cube operations (e.g. in `reduce_dimension`), `null` values returned by the array processes shall be replaced with the no-data value of the data cube. +As the processes may be used outside of data cubes where the no-data values are undefined, +most processes fall back to `null` in this case (reflected through the mention of "(or `null`)" in the process description). ## Optimizations for conditions (e.g. `if`) None of the openEO processes per se is "special" and thus all are treated the same way by default. Nevertheless, there are some cases where a special treatment can make a huge difference. +## Character encoding + +String-related processes previously mentioned that strings have to be "encoded in UTF-8 by default". +This was removed and we clarify the behavior here: + +For data transfer through the API, the character encoding of strings is specified using HTTP headers. +This means all strings provided in the process graph have the same encoding as specified in the HTTP headers. +Back-ends can internally use any character encoding and as such may need to convert the character encoding +upon receipt of the process graph. +It is recommended to use a [Unicode](https://en.wikipedia.org/wiki/Unicode) character encoding such as UTF-8. +In case of doubt, clients and server should assume UTF-8 as character encoding. + ### Branching behavior The `if` process (and any process that is working on some kind of condition) are usually diff --git a/neq.json b/neq.json index 1b115b3b..383d6b8b 100644 --- a/neq.json +++ b/neq.json @@ -1,7 +1,7 @@ { "id": "neq", "summary": "Not equal to comparison", - "description": "Compares whether `x` is **not** strictly equal to `y`.\n\n**Remarks:**\n\n* Data types MUST be checked strictly. For example, a string with the content *1* is not equal to the number *1*. Nevertheless, an integer *1* is equal to a floating-point number *1.0* as `integer` is a sub-type of `number`.\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* Strings are expected to be encoded in UTF-8 by default.\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", + "description": "Compares whether `x` is **not** strictly equal to `y`.\n\n**Remarks:**\n\n* Data types MUST be checked strictly. For example, a string with the content *1* is not equal to the number *1*. Nevertheless, an integer *1* is equal to a floating-point number *1.0* as `integer` is a sub-type of `number`.\n* If any operand is a no-data value, the result will be the no-data value (or `null`).\n* The comparison of `NaN` (not a number) follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229).\n* Temporal strings are normal strings. To compare temporal strings as dates/times, use ``date_difference()``.", "categories": [ "texts", "comparison" @@ -147,6 +147,13 @@ "returns": true } ], + "links": [ + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/4610935", + "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" + } + ], "process_graph": { "eq": { "process_id": "eq", diff --git a/proposals/is_infinite.json b/proposals/is_infinite.json index b6a5acca..da0d165f 100644 --- a/proposals/is_infinite.json +++ b/proposals/is_infinite.json @@ -1,7 +1,7 @@ { "id": "is_infinite", "summary": "Value is an infinite number", - "description": "Checks whether the specified value `x` is an infinite number. The definition of infinite numbers follows the [IEEE Standard 754](https://ieeexplore.ieee.org/document/4610935). The special numerical value `NaN` (not a number) as defined by the [IEEE Standard 754](https://ieeexplore.ieee.org/document/4610935) is not an infinite number and must return `false`.", + "description": "Checks whether the specified value `x` is an infinite number. The definition of infinite numbers (and `NaN`) follows the [IEEE Standard 754](https://ieeexplore.ieee.org/document/4610935). `NaN` (not a number) is not an infinite number and must return `false`.", "categories": [ "comparison" ], @@ -28,4 +28,4 @@ "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" } ] -} \ No newline at end of file +} diff --git a/text_begins.json b/text_begins.json index f422999f..8fc39624 100644 --- a/text_begins.json +++ b/text_begins.json @@ -1,7 +1,7 @@ { "id": "text_begins", "summary": "Text begins with another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the beginning. Both are expected to be encoded in UTF-8 by default. No-data values are passed through and therefore get propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the beginning. No-data values are passed through and therefore get propagated.", "categories": [ "texts", "comparison" diff --git a/text_contains.json b/text_contains.json index d0046131..a41a3d95 100644 --- a/text_contains.json +++ b/text_contains.json @@ -1,7 +1,7 @@ { "id": "text_contains", "summary": "Text contains another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern`. Both are expected to be encoded in UTF-8 by default. No-data values are passed through and therefore get propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern`. No-data values are passed through and therefore get propagated.", "categories": [ "texts", "comparison" diff --git a/text_ends.json b/text_ends.json index 7bd2238c..70a04855 100644 --- a/text_ends.json +++ b/text_ends.json @@ -1,7 +1,7 @@ { "id": "text_ends", "summary": "Text ends with another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the end. Both are expected to be encoded in UTF-8 by default. No-data values are passed through and therefore get propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the end. No-data values are passed through and therefore get propagated.", "categories": [ "texts", "comparison" From 281584a1a61e225387e83dab554b30a7101615f7 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 5 Jan 2024 13:33:39 +0100 Subject: [PATCH 3/3] Updates according to PR review --- absolute.json | 2 +- all.json | 2 +- any.json | 2 +- arccos.json | 2 +- arcosh.json | 2 +- arcsin.json | 2 +- arctan.json | 2 +- array_find.json | 4 ++-- arsinh.json | 2 +- artanh.json | 2 +- between.json | 2 +- ceil.json | 2 +- clip.json | 2 +- cos.json | 2 +- cosh.json | 2 +- exp.json | 2 +- floor.json | 2 +- int.json | 2 +- linear_scale_range.json | 2 +- ln.json | 2 +- meta/implementation.md | 1 + not.json | 2 +- proposals/array_find_label.json | 6 +++--- round.json | 2 +- sgn.json | 2 +- sin.json | 2 +- sinh.json | 2 +- sqrt.json | 2 +- tan.json | 2 +- tanh.json | 2 +- text_begins.json | 2 +- text_contains.json | 2 +- text_ends.json | 2 +- 33 files changed, 36 insertions(+), 35 deletions(-) diff --git a/absolute.json b/absolute.json index fa5d003f..3b83437a 100644 --- a/absolute.json +++ b/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\nNo-data values are passed through and therefore get 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" ], diff --git a/all.json b/all.json index 2e8bec38..dbf751a4 100644 --- a/all.json +++ b/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 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.", + "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" diff --git a/any.json b/any.json index f54c9cf4..4cdce32d 100644 --- a/any.json +++ b/any.json @@ -1,7 +1,7 @@ { "id": "any", "summary": "Is at least one value true?", - "description": "Checks if **any** (i.e. at least one) value in `data` is `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 the no-data value (or `null`) if all values are no-data, `true` if at least one value is 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 | no-data | true\nfalse || no-data | false | true\ntrue || true | true | 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 `true`.", + "description": "Checks if **any** (i.e. at least one) value in `data` is `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 at least one value is 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 | no-data | true\nfalse || no-data | false | true\ntrue || true | true | 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 `true`.", "categories": [ "logic", "reducer" diff --git a/arccos.json b/arccos.json index 87378a40..91e19977 100644 --- a/arccos.json +++ b/arccos.json @@ -1,7 +1,7 @@ { "id": "arccos", "summary": "Inverse cosine", - "description": "Computes the arc cosine of `x`. The arc cosine is the inverse function of the cosine so that *`arccos(cos(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated. `NaN` is returned for values outside of the allowed range.", + "description": "Computes the arc cosine of `x`. The arc cosine is the inverse function of the cosine so that *`arccos(cos(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through. `NaN` is returned for values < -1 and > 1.", "categories": [ "math > trigonometric" ], diff --git a/arcosh.json b/arcosh.json index 800ad449..9222a122 100644 --- a/arcosh.json +++ b/arcosh.json @@ -1,7 +1,7 @@ { "id": "arcosh", "summary": "Inverse hyperbolic cosine", - "description": "Computes the inverse hyperbolic cosine of `x`. It is the inverse function of the hyperbolic cosine so that *`arcosh(cosh(x)) = x`*.\n\nNo-data values are passed through and therefore get propagated. `NaN` is returned for values outside of the allowed range.", + "description": "Computes the inverse hyperbolic cosine of `x`. It is the inverse function of the hyperbolic cosine so that *`arcosh(cosh(x)) = x`*.\n\nNo-data values are passed through. `NaN` is returned for values outside of the allowed range.", "categories": [ "math > trigonometric" ], diff --git a/arcsin.json b/arcsin.json index 9f6c72ee..b927813d 100644 --- a/arcsin.json +++ b/arcsin.json @@ -1,7 +1,7 @@ { "id": "arcsin", "summary": "Inverse sine", - "description": "Computes the arc sine of `x`. The arc sine is the inverse function of the sine so that *`arcsin(sin(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated. `NaN` is returned for values < -1 and > 1.", + "description": "Computes the arc sine of `x`. The arc sine is the inverse function of the sine so that *`arcsin(sin(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through. `NaN` is returned for values < -1 and > 1.", "categories": [ "math > trigonometric" ], diff --git a/arctan.json b/arctan.json index 08c7eb5c..c091218b 100644 --- a/arctan.json +++ b/arctan.json @@ -1,7 +1,7 @@ { "id": "arctan", "summary": "Inverse tangent", - "description": "Computes the arc tangent of `x`. The arc tangent is the inverse function of the tangent so that *`arctan(tan(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated.", + "description": "Computes the arc tangent of `x`. The arc tangent is the inverse function of the tangent so that *`arctan(tan(x)) = x`*.\n\nWorks on radians only.\nNo-data values are passed through.", "categories": [ "math > trigonometric" ], diff --git a/array_find.json b/array_find.json index 6344d223..58eb5ea7 100644 --- 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": "Returns the zero-based index of the first (or last) occurrence of the value specified by `value` in the array specified by `data` or `null` if there is no match. Use the parameter `reverse` to switch from the first to the last match.\n\n**Remarks:**\n\n* Use ``array_contains()`` to check if an array contains a value regardless of the position.\n* Use ``array_find_label()`` to find the index for a label.\n* All definitions for the process ``eq()`` regarding the comparison of values apply here as well. A no-data return value from ``eq()`` is handled as `false` (no match).\n* 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.\n* If the specified value is an array, object or null, the process always returns `null`. See the examples to find no-data values.", + "description": "Returns the zero-based index of the first (or last) occurrence of the value specified by `value` in the array specified by `data` or the no-data value (or `null`) if there is no match. Use the parameter `reverse` to switch from the first to the last match.\n\n**Remarks:**\n\n* Use ``array_contains()`` to check if an array contains a value regardless of the position.\n* Use ``array_find_label()`` to find the index for a label.\n* All definitions for the process ``eq()`` regarding the comparison of values apply here as well. A no-data return value from ``eq()`` is handled as `false` (no match).\n* 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.\n* If the specified value is an array, object or null, the process always returns the no-data value (or `null`). See the examples to find no-data values.", "categories": [ "arrays", "reducer" @@ -35,7 +35,7 @@ } ], "returns": { - "description": "The index of the first element with the specified value. If no element was found, `null` is returned.", + "description": "The index of the first element with the specified value. If no element was found, the no-data value (or `null`) is returned.", "schema": [ { "type": "null" diff --git a/arsinh.json b/arsinh.json index 405ab410..31e6bf56 100644 --- a/arsinh.json +++ b/arsinh.json @@ -1,7 +1,7 @@ { "id": "arsinh", "summary": "Inverse hyperbolic sine", - "description": "Computes the inverse hyperbolic sine of `x`. It is the inverse function of the hyperbolic sine so that *`arsinh(sinh(x)) = x`*.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Computes the inverse hyperbolic sine of `x`. It is the inverse function of the hyperbolic sine so that *`arsinh(sinh(x)) = x`*.\n\nNo-data values are passed through.", "categories": [ "math > trigonometric" ], diff --git a/artanh.json b/artanh.json index c7d4778d..a61956c1 100644 --- a/artanh.json +++ b/artanh.json @@ -1,7 +1,7 @@ { "id": "artanh", "summary": "Inverse hyperbolic tangent", - "description": "Computes the inverse hyperbolic tangent of `x`. It is the inverse function of the hyperbolic tangent so that *`artanh(tanh(x)) = x`*.\n\nNo-data values are passed through and therefore get propagated. `NaN` is returned for values outside of the allowed range. The computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, `x` = 1 results in +infinity and `x` = 0 results in -infinity. Otherwise, an exception is thrown.", + "description": "Computes the inverse hyperbolic tangent of `x`. It is the inverse function of the hyperbolic tangent so that *`artanh(tanh(x)) = x`*.\n\nNo-data values are passed through. `NaN` is returned for values outside of the allowed range. The computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, `x` = 1 results in +infinity and `x` = 0 results in -infinity. Otherwise, an exception is thrown.", "categories": [ "math > trigonometric" ], diff --git a/between.json b/between.json index b09d09fb..a362776c 100644 --- a/between.json +++ b/between.json @@ -8,7 +8,7 @@ "parameters": [ { "name": "x", - "description": "The value to check.\n\nNo-data values are passed through and therefore get propagated.", + "description": "The value to check.\n\nNo-data values are passed through.", "schema": { "description": "Any data type is allowed." } diff --git a/ceil.json b/ceil.json index 9f237bf1..f98dccdc 100644 --- a/ceil.json +++ b/ceil.json @@ -1,7 +1,7 @@ { "id": "ceil", "summary": "Round fractions up", - "description": "The least integer greater than or equal to the number `x`.\n\nNo-data values are passed through and therefore get propagated.", + "description": "The least integer greater than or equal to the number `x`.\n\nNo-data values are passed through.", "categories": [ "math > rounding" ], diff --git a/clip.json b/clip.json index 04c2d7b4..a34a191e 100644 --- a/clip.json +++ b/clip.json @@ -1,7 +1,7 @@ { "id": "clip", "summary": "Clip a value between a minimum and a maximum", - "description": "Clips a number between specified minimum and maximum values. A value larger than the maximum value is set to the maximum value, a value lower than the minimum value is set to the minimum value. If the maximum value is smaller than the minimum number, the process throws a `MinMaxSwapped` exception.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Clips a number between specified minimum and maximum values. A value larger than the maximum value is set to the maximum value, a value lower than the minimum value is set to the minimum value. If the maximum value is smaller than the minimum number, the process throws a `MinMaxSwapped` exception.\n\nNo-data values are passed through.", "categories": [ "math" ], diff --git a/cos.json b/cos.json index ac312c20..b1e0b98c 100644 --- a/cos.json +++ b/cos.json @@ -1,7 +1,7 @@ { "id": "cos", "summary": "Cosine", - "description": "Computes the cosine of `x`.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated.", + "description": "Computes the cosine of `x`.\n\nWorks on radians only.\nNo-data values are passed through.", "categories": [ "math > trigonometric" ], diff --git a/cosh.json b/cosh.json index 572a6161..64fbd88d 100644 --- a/cosh.json +++ b/cosh.json @@ -1,7 +1,7 @@ { "id": "cosh", "summary": "Hyperbolic cosine", - "description": "Computes the hyperbolic cosine of `x`.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Computes the hyperbolic cosine of `x`.\n\nNo-data values are passed through.", "categories": [ "math > trigonometric" ], diff --git a/exp.json b/exp.json index bceeef2c..a7bb1746 100644 --- a/exp.json +++ b/exp.json @@ -1,7 +1,7 @@ { "id": "exp", "summary": "Exponentiation to the base e", - "description": "Exponential function to the base *e* raised to the power of `p`.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Exponential function to the base *e* raised to the power of `p`.\n\nNo-data values are passed through.", "categories": [ "math > exponential & logarithmic" ], diff --git a/floor.json b/floor.json index 63c1c48d..621513af 100644 --- a/floor.json +++ b/floor.json @@ -1,7 +1,7 @@ { "id": "floor", "summary": "Round fractions down", - "description": "The greatest integer less than or equal to the number `x`.\n\nThis process is *not* an alias for the ``int()`` process as defined by some mathematicians, see the examples for negative numbers in both processes for differences.\n\nNo-data values are passed through and therefore get propagated.", + "description": "The greatest integer less than or equal to the number `x`.\n\nThis process is *not* an alias for the ``int()`` process as defined by some mathematicians, see the examples for negative numbers in both processes for differences.\n\nNo-data values are passed through.", "categories": [ "math > rounding" ], diff --git a/int.json b/int.json index 32d1424a..20ede2df 100644 --- a/int.json +++ b/int.json @@ -1,7 +1,7 @@ { "id": "int", "summary": "Integer part of a number", - "description": "The integer part of the real number `x`.\n\nThis process is *not* an alias for the ``floor()`` process as defined by some mathematicians, see the examples for negative numbers in both processes for differences.\n\nNo-data values are passed through and therefore get propagated.", + "description": "The integer part of the real number `x`.\n\nThis process is *not* an alias for the ``floor()`` process as defined by some mathematicians, see the examples for negative numbers in both processes for differences.\n\nNo-data values are passed through.", "categories": [ "math", "math > rounding" diff --git a/linear_scale_range.json b/linear_scale_range.json index c3de1096..9346d8ba 100644 --- a/linear_scale_range.json +++ b/linear_scale_range.json @@ -1,7 +1,7 @@ { "id": "linear_scale_range", "summary": "Linear transformation between two ranges", - "description": "Performs a linear transformation between the input and output range.\n\nThe given number in `x` is clipped to the bounds specified in `inputMin` and `inputMax` so that the underlying formula *`((x - inputMin) / (inputMax - inputMin)) * (outputMax - outputMin) + outputMin`* never returns a value outside of the range defined by `outputMin` and `outputMax`.\n\nPotential use case include\n\n* scaling values to the 8-bit range (0 - 255) often used for numeric representation of values in one of the channels of the [RGB colour model](https://en.wikipedia.org/wiki/RGB_color_model#Numeric_representations) or\n* calculating percentages (0 - 100).\n\nNo-data values are passed through and therefore get propagated.", + "description": "Performs a linear transformation between the input and output range.\n\nThe given number in `x` is clipped to the bounds specified in `inputMin` and `inputMax` so that the underlying formula *`((x - inputMin) / (inputMax - inputMin)) * (outputMax - outputMin) + outputMin`* never returns a value outside of the range defined by `outputMin` and `outputMax`.\n\nPotential use case include\n\n* scaling values to the 8-bit range (0 - 255) often used for numeric representation of values in one of the channels of the [RGB colour model](https://en.wikipedia.org/wiki/RGB_color_model#Numeric_representations) or\n* calculating percentages (0 - 100).\n\nNo-data values are passed through.", "categories": [ "math" ], diff --git a/ln.json b/ln.json index 6b9b5022..54729115 100644 --- a/ln.json +++ b/ln.json @@ -1,7 +1,7 @@ { "id": "ln", "summary": "Natural logarithm", - "description": "The natural logarithm is the logarithm to the base *e* of the number `x`, which equals to using the *log* process with the base set to *e*. The natural logarithm is the inverse function of taking *e* to the power x.\n\nNo-data values are passed through and therefore get propagated.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`ln(0)`* results in -infinity if the processing environment supports it or otherwise an exception is thrown. `NaN` is returned for values outside of the allowed range.", + "description": "The natural logarithm is the logarithm to the base *e* of the number `x`, which equals to using the *log* process with the base set to *e*. The natural logarithm is the inverse function of taking *e* to the power x.\n\nNo-data values are passed through.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`ln(0)`* results in -infinity if the processing environment supports it or otherwise an exception is thrown. `NaN` is returned for values outside of the allowed range.", "categories": [ "math > exponential & logarithmic" ], diff --git a/meta/implementation.md b/meta/implementation.md index 0f7e75ca..10137a06 100644 --- a/meta/implementation.md +++ b/meta/implementation.md @@ -25,6 +25,7 @@ In the context of data cube operations (e.g. in `reduce_dimension`), `null` valu by the array processes shall be replaced with the no-data value of the data cube. As the processes may be used outside of data cubes where the no-data values are undefined, most processes fall back to `null` in this case (reflected through the mention of "(or `null`)" in the process description). +This effectively means that `null` is the default value for an undefined no-data value in openEO. ## Optimizations for conditions (e.g. `if`) diff --git a/not.json b/not.json index 5879a767..8701a4e3 100644 --- a/not.json +++ b/not.json @@ -1,7 +1,7 @@ { "id": "not", "summary": "Inverting a boolean", - "description": "Inverts a single boolean so that `true` gets `false` and `false` gets `true`.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Inverts a single boolean so that `true` gets `false` and `false` gets `true`.\n\nNo-data values are passed through.", "categories": [ "logic" ], diff --git a/proposals/array_find_label.json b/proposals/array_find_label.json index 98371cb5..fb8c24fd 100644 --- a/proposals/array_find_label.json +++ b/proposals/array_find_label.json @@ -1,7 +1,7 @@ { "id": "array_find_label", "summary": "Get the index for a label in a labeled array", - "description": "Checks whether the labeled array specified for `data` has the label specified in `label` and returns the zero-based index for it. If there's no match as either the label doesn't exist or the array is not labeled, `null` is returned.\n\nUse ``array_find()`` to find the index for a given value in the array.", + "description": "Checks whether the labeled array specified for `data` has the label specified in `label` and returns the zero-based index for it. If there's no match as either the label doesn't exist or the array is not labeled, the no-data value (or `null`) is returned.\n\nUse ``array_find()`` to find the index for a given value in the array.", "categories": [ "arrays", "reducer" @@ -32,7 +32,7 @@ } ], "returns": { - "description": "The index of the element with the specified label assigned. If no such label was found, `null` is returned.", + "description": "The index of the element with the specified label assigned. If no such label was found, the no-data value (or `null`) is returned.", "schema": [ { "type": "null" @@ -43,4 +43,4 @@ } ] } -} \ No newline at end of file +} diff --git a/round.json b/round.json index aa1d8d87..8f61b8a0 100644 --- a/round.json +++ b/round.json @@ -1,7 +1,7 @@ { "id": "round", "summary": "Round to a specified precision", - "description": "Rounds a real number `x` to specified precision `p`.\n\nIf `x` is halfway between closest numbers of precision `p`, it is rounded to the closest even number of precision `p`.\nThis behavior follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) and is often called \"round to nearest (even)\" or \"banker's rounding\". It minimizes rounding errors that result from consistently rounding a midpoint value in a single direction.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Rounds a real number `x` to specified precision `p`.\n\nIf `x` is halfway between closest numbers of precision `p`, it is rounded to the closest even number of precision `p`.\nThis behavior follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) and is often called \"round to nearest (even)\" or \"banker's rounding\". It minimizes rounding errors that result from consistently rounding a midpoint value in a single direction.\n\nNo-data values are passed through.", "categories": [ "math > rounding" ], diff --git a/sgn.json b/sgn.json index 5019957e..98772952 100644 --- a/sgn.json +++ b/sgn.json @@ -1,7 +1,7 @@ { "id": "sgn", "summary": "Signum", - "description": "The signum (also known as *sign*) of `x` is defined as:\n\n* *1* if *x > 0*\n* *0* if *x = 0*\n* *-1* if *x < 0*\n\nNo-data values are passed through and therefore get propagated.", + "description": "The signum (also known as *sign*) of `x` is defined as:\n\n* *1* if *x > 0*\n* *0* if *x = 0*\n* *-1* if *x < 0*\n\nNo-data values are passed through.", "categories": [ "math" ], diff --git a/sin.json b/sin.json index 01fbc9cb..989be23d 100644 --- a/sin.json +++ b/sin.json @@ -1,7 +1,7 @@ { "id": "sin", "summary": "Sine", - "description": "Computes the sine of `x`.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated.", + "description": "Computes the sine of `x`.\n\nWorks on radians only.\nNo-data values are passed through.", "categories": [ "math > trigonometric" ], diff --git a/sinh.json b/sinh.json index 3ee8271e..4bfa4975 100644 --- a/sinh.json +++ b/sinh.json @@ -1,7 +1,7 @@ { "id": "sinh", "summary": "Hyperbolic sine", - "description": "Computes the hyperbolic sine of `x`.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Computes the hyperbolic sine of `x`.\n\nNo-data values are passed through.", "categories": [ "math > trigonometric" ], diff --git a/sqrt.json b/sqrt.json index efe65919..446ded3c 100644 --- a/sqrt.json +++ b/sqrt.json @@ -1,7 +1,7 @@ { "id": "sqrt", "summary": "Square root", - "description": "Computes the square root of a real number `x`, which is equal to calculating `x` to the power of *0.5*. For negative `x`, the process returns `NaN`.\n\nA square root of x is a number a such that *`a² = x`*. Therefore, the square root is the inverse function of a to the power of 2, but only for *a >= 0*.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Computes the square root of a real number `x`, which is equal to calculating `x` to the power of *0.5*. For negative `x`, the process returns `NaN`.\n\nA square root of x is a number a such that *`a² = x`*. Therefore, the square root is the inverse function of a to the power of 2, but only for *a >= 0*.\n\nNo-data values are passed through.", "categories": [ "math", "math > exponential & logarithmic" diff --git a/tan.json b/tan.json index 59557039..372e3188 100644 --- a/tan.json +++ b/tan.json @@ -1,7 +1,7 @@ { "id": "tan", "summary": "Tangent", - "description": "Computes the tangent of `x`. The tangent is defined to be the sine of x divided by the cosine of x.\n\nWorks on radians only.\nNo-data values are passed through and therefore get propagated.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`tan(pi()/2 + multipliy(pi(), n))`* with `n` being any integer results in ±infinity. -infinity for negative values passed to `tan`, +infinity otherwise. If the processing environment does not supports it, an exception is thrown.", + "description": "Computes the tangent of `x`. The tangent is defined to be the sine of x divided by the cosine of x.\n\nWorks on radians only.\nNo-data values are passed through.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`tan(pi()/2 + multipliy(pi(), n))`* with `n` being any integer results in ±infinity. -infinity for negative values passed to `tan`, +infinity otherwise. If the processing environment does not supports it, an exception is thrown.", "categories": [ "math > trigonometric" ], diff --git a/tanh.json b/tanh.json index 96b15804..41eab735 100644 --- a/tanh.json +++ b/tanh.json @@ -1,7 +1,7 @@ { "id": "tanh", "summary": "Hyperbolic tangent", - "description": "Computes the hyperbolic tangent of `x`. The tangent is defined to be the hyperbolic sine of x divided by the hyperbolic cosine of x.\n\nNo-data values are passed through and therefore get propagated.", + "description": "Computes the hyperbolic tangent of `x`. The tangent is defined to be the hyperbolic sine of x divided by the hyperbolic cosine of x.\n\nNo-data values are passed through.", "categories": [ "math > trigonometric" ], diff --git a/text_begins.json b/text_begins.json index 8fc39624..873fd649 100644 --- a/text_begins.json +++ b/text_begins.json @@ -1,7 +1,7 @@ { "id": "text_begins", "summary": "Text begins with another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the beginning. No-data values are passed through and therefore get propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the beginning. No-data values are passed through.", "categories": [ "texts", "comparison" diff --git a/text_contains.json b/text_contains.json index a41a3d95..21d5ea9f 100644 --- a/text_contains.json +++ b/text_contains.json @@ -1,7 +1,7 @@ { "id": "text_contains", "summary": "Text contains another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern`. No-data values are passed through and therefore get propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern`. No-data values are passed through.", "categories": [ "texts", "comparison" diff --git a/text_ends.json b/text_ends.json index 70a04855..a63fc424 100644 --- a/text_ends.json +++ b/text_ends.json @@ -1,7 +1,7 @@ { "id": "text_ends", "summary": "Text ends with another text", - "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the end. No-data values are passed through and therefore get propagated.", + "description": "Checks whether the text (also known as *string*) specified for `data` contains the text specified for `pattern` at the end. No-data values are passed through.", "categories": [ "texts", "comparison"