From 7b558aca5f2f13855c35fbbddaa8205fbdeb7d4d Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 25 May 2023 13:30:59 +0200 Subject: [PATCH 01/27] clean-up --- .github/workflows/docs.yml | 1 - tests/docs.html | 4 ++-- tests/package.json | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4e8f4f28..29baf6db 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,7 +5,6 @@ on: push: branches: - draft - - draft-2.0 - master jobs: deploy: diff --git a/tests/docs.html b/tests/docs.html index 23ef98e4..04b1c192 100644 --- a/tests/docs.html +++ b/tests/docs.html @@ -113,8 +113,8 @@ props: { document: 'processes.json', categorize: true, - apiVersion: '1.1.0', - title: 'openEO processes (draft)', + apiVersion: '1.2.0', + title: 'openEO processes (2.0.0-rc.1)', notice: '**Note:** This is the list of all processes specified by the openEO project. Back-ends implement a varying set of processes. Thus, the processes you can use at a specific back-end may derive from the specification, may include non-standardized processes and may not implement all processes listed here. Please check each back-end individually for the processes they support. The client libraries usually have a function called `listProcesses` or `list_processes` for that.' } }) diff --git a/tests/package.json b/tests/package.json index 15f6d2e8..1da8693f 100644 --- a/tests/package.json +++ b/tests/package.json @@ -1,6 +1,6 @@ { "name": "@openeo/processes", - "version": "2.0.0", + "version": "2.0.0-rc.1", "author": "openEO Consortium", "contributors": [ { From 7a293786b4c464d2c7452d7b5f13104098a25232 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Mon, 31 Jul 2023 13:52:05 +0200 Subject: [PATCH 02/27] aggregate_spatial_window typo fix (#446) --- proposals/aggregate_spatial_window.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/aggregate_spatial_window.json b/proposals/aggregate_spatial_window.json index 747db151..9e5dce4a 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\nSet the parameter `align` to specifies to which corner the data is aligned to.", + "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.", "schema": { "type": "string", "enum": [ From 0833d4ebab71b16a09658c21e7278e40688b3bf1 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Sat, 30 Sep 2023 09:21:44 +0200 Subject: [PATCH 03/27] Issue #460 doc crossreferences between filter_bbox/filter_spatial/filter_vector (#462) --- filter_bbox.json | 2 +- filter_spatial.json | 2 +- proposals/filter_vector.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/filter_bbox.json b/filter_bbox.json index 3e2a7485..e95d5fa2 100644 --- a/filter_bbox.json +++ b/filter_bbox.json @@ -1,7 +1,7 @@ { "id": "filter_bbox", "summary": "Spatial filter using a bounding box", - "description": "Limits the data cube to the specified bounding box.\n\n* For raster data cubes, the filter retains a pixel in the data cube if the point at the pixel center intersects with the bounding box (as defined in the Simple Features standard by the OGC). Alternatively, ``filter_spatial()`` can be used to filter by geometry.\n* For vector data cubes, the filter retains the geometry in the data cube if the geometry is fully within the bounding box (as defined in the Simple Features standard by the OGC). All geometries that were empty or not contained fully within the bounding box will be removed from the data cube.\n\nAlternatively, ``filter_vector()`` can be used to filter by geometry.", + "description": "Limits the data cube to the specified bounding box.\n\n* For raster data cubes, the filter retains a pixel in the data cube if the point at the pixel center intersects with the bounding box (as defined in the Simple Features standard by the OGC). Alternatively, ``filter_spatial()`` can be used to filter by geometry.\n* For vector data cubes, the filter retains the geometry in the data cube if the geometry is fully within the bounding box (as defined in the Simple Features standard by the OGC). All geometries that were empty or not contained fully within the bounding box will be removed from the data cube.\n\nAlternatively, filter spatially with geometries using ``filter_spatial()`` (on a raster data cube) or ``filter_vector()`` (on a vector data cube).", "categories": [ "cubes", "filter" diff --git a/filter_spatial.json b/filter_spatial.json index c0c116cd..f2648b05 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 geometry 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 by bounding box.", + "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 geometry 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.", "categories": [ "cubes", "filter" diff --git a/proposals/filter_vector.json b/proposals/filter_vector.json index 349f8d0f..1bb33c86 100644 --- a/proposals/filter_vector.json +++ b/proposals/filter_vector.json @@ -1,7 +1,7 @@ { "id": "filter_vector", "summary": "Spatial vector filter using geometries", - "description": "Limits the vector data cube to the specified geometries. The process works on geometries as defined in the Simple Features standard by the OGC. All geometries that were empty or become empty will be removed from the data cube. Alternatively, use ``filter_bbox()`` to filter by bounding box.", + "description": "Limits the vector data cube to the specified geometries. The process works on geometries as defined in the Simple Features standard by the OGC. All geometries that were empty or become empty will be removed from the data cube. Alternatively, use ``filter_bbox()`` to filter with a bounding box or ``filter_spatial()`` to filter a raster data cube based on geometries.", "categories": [ "cubes", "filter", From c130dd732c912624dea89c8eb15134c1378bd9e7 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 12 Oct 2023 11:24:39 +0200 Subject: [PATCH 04/27] Move tests to dev --- .github/workflows/docs.yml | 6 +++--- .github/workflows/tests.yml | 6 +++--- README.md | 2 +- {tests => dev}/.gitignore | 0 {tests => dev}/.words | 0 {tests => dev}/README.md | 0 {tests => dev}/docs.html | 0 {tests => dev}/package.json | 0 {tests => dev}/testConfig.json | 0 9 files changed, 7 insertions(+), 7 deletions(-) rename {tests => dev}/.gitignore (100%) rename {tests => dev}/.words (100%) rename {tests => dev}/README.md (100%) rename {tests => dev}/docs.html (100%) rename {tests => dev}/package.json (100%) rename {tests => dev}/testConfig.json (100%) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 29baf6db..b09f6e3d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,7 +19,7 @@ jobs: - run: | npm install npm run generate - working-directory: tests + working-directory: dev - name: clone gh-pages and clean-up if: ${{ env.GITHUB_REF_SLUG == 'master' }} run: | @@ -31,8 +31,8 @@ jobs: if: ${{ env.GITHUB_REF_SLUG != 'master' }} run: mkdir gh-pages - run: | - cp tests/docs.html index.html - cp tests/processes.json processes.json + cp dev/docs.html index.html + cp dev/processes.json processes.json rsync -vrm --include='*.json' --include='*.html' --include='meta/***' --include='proposals/***' --exclude='*' . gh-pages - name: deploy to root (master) uses: peaceiris/actions-gh-pages@v3 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index b108eb18..25659365 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -8,8 +8,8 @@ jobs: with: node-version: 'lts/*' - uses: actions/checkout@v3 - - name: Run tests + - name: Run linter run: | npm install - npm run test - working-directory: tests \ No newline at end of file + npm test + working-directory: dev \ No newline at end of file diff --git a/README.md b/README.md index 24c28899..621276b6 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ This repository contains a set of files formally describing the openEO Processes * [implementation.md](meta/implementation.md) in the `meta` folder provide some additional implementation details for back-ends. For back-end implementors, it's highly recommended to read them. * [subtype-schemas.json](meta/subtype-schemas.json) in the `meta` folder defines common data types (`subtype`s) for JSON Schema used in openEO processes. * Previously, an `examples` folder contained examples of user-defined processes. These have been migrated to the [openEO Community Examples](https://github.com/Open-EO/openeo-community-examples/tree/main/processes) repository. -* The [`tests`](tests/) folder can be used to test the process specification for validity and consistent "style". It also allows rendering the processes in a web browser. Check the [tests documentation](tests/README.md) for details. +* The [`dev`](dev/) folder can be used to test the process specification for validity and consistent "style". It also allows rendering the processes in a web browser. Check the [development documentation](dev/README.md) for details. ## Process diff --git a/tests/.gitignore b/dev/.gitignore similarity index 100% rename from tests/.gitignore rename to dev/.gitignore diff --git a/tests/.words b/dev/.words similarity index 100% rename from tests/.words rename to dev/.words diff --git a/tests/README.md b/dev/README.md similarity index 100% rename from tests/README.md rename to dev/README.md diff --git a/tests/docs.html b/dev/docs.html similarity index 100% rename from tests/docs.html rename to dev/docs.html diff --git a/tests/package.json b/dev/package.json similarity index 100% rename from tests/package.json rename to dev/package.json diff --git a/tests/testConfig.json b/dev/testConfig.json similarity index 100% rename from tests/testConfig.json rename to dev/testConfig.json From c2d77e2e5fea0cafc6576d10a97d472aa6616ffb Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 25 Oct 2023 14:51:17 +0200 Subject: [PATCH 05/27] Use x \ y instead of a \ b --- and.json | 4 ++-- or.json | 4 ++-- xor.json | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/and.json b/and.json index c24ce95b..3b28c8ef 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```\na \\ b || 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 `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```", "categories": [ "logic" ], @@ -90,4 +90,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/or.json b/or.json index 5964a341..4a83a63e 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```\na \\ b || 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 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```", "categories": [ "logic" ], @@ -90,4 +90,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/xor.json b/xor.json index d8dbde50..6af7ae5e 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```\na \\ b || 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 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```", "categories": [ "logic" ], @@ -125,4 +125,4 @@ "result": true } } -} \ No newline at end of file +} From 13c3f85696d6f142f68694ba4726337b1fecca28 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 27 Oct 2023 11:07:14 +0200 Subject: [PATCH 06/27] `sqrt`: Clarified that NaN is returned for negative numbers #474 (#475) --- CHANGELOG.md | 4 ++++ sqrt.json | 9 +++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 407447dc..78b16e73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased / Draft +### Fixed + +- `sqrt`: Clarified that NaN is returned for negative numbers. + ## [2.0.0-rc.1] - 2023-05-25 ### Added diff --git a/sqrt.json b/sqrt.json index bc1aeb6c..b85caf94 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*.\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\nThe no-data value `null` is passed through and therefore gets propagated.", "categories": [ "math", "math > exponential & logarithmic" @@ -58,6 +58,11 @@ "rel": "about", "href": "http://mathworld.wolfram.com/SquareRoot.html", "title": "Square root explained by Wolfram MathWorld" + }, + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/8766229", + "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic" } ], "process_graph": { @@ -72,4 +77,4 @@ "result": true } } -} \ No newline at end of file +} From 4fd92b217ec84bfb27273c2d1acdb8418574b7b7 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 27 Oct 2023 11:08:00 +0200 Subject: [PATCH 07/27] `clip`: Throw an exception if min > max #472 (#477) --- CHANGELOG.md | 4 ++++ clip.json | 40 ++++++++-------------------------------- 2 files changed, 12 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 78b16e73..281ab2d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased / Draft +### Changed + +- `clip`: Throw an exception if min > max [#472](https://github.com/Open-EO/openeo-processes/issues/472) + ### Fixed - `sqrt`: Clarified that NaN is returned for negative numbers. diff --git a/clip.json b/clip.json index adbf7eaa..de2a4d1a 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.\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\nThe no-data value `null` is passed through and therefore gets propagated.", "categories": [ "math" ], @@ -40,6 +40,11 @@ ] } }, + "exceptions": { + "MinMaxSwapped": { + "message": "The minimum value should be lower than or equal to the maximum value." + } + }, "examples": [ { "arguments": { @@ -73,34 +78,5 @@ }, "returns": null } - ], - "process_graph": { - "min": { - "process_id": "min", - "arguments": { - "data": [ - { - "from_parameter": "max" - }, - { - "from_parameter": "x" - } - ] - } - }, - "max": { - "process_id": "max", - "arguments": { - "data": [ - { - "from_parameter": "min" - }, - { - "from_node": "min" - } - ] - }, - "result": true - } - } -} \ No newline at end of file + ] +} From ab4a62eb3fc3eac0c66a51f5670aa131e52c0745 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 27 Oct 2023 12:24:32 +0200 Subject: [PATCH 08/27] `array_append`: Added `number` type for labels to be consistent with other processes. Default to numerical index instead of string. (#478) --- CHANGELOG.md | 4 ++++ array_append.json | 22 +++++++++++++++------- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 281ab2d8..0319d15d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [2.0.0-rc.1] - 2023-05-25 +### Fixed + +- `array_append`: Added `number` type for labels to be consistent with other processes. Default to numerical index instead of string. Clarify that the `label` parameter only applies to labeled arrays. + ### Added - New processes in proposal state: diff --git a/array_append.json b/array_append.json index 80b48d12..f09145d2 100644 --- a/array_append.json +++ b/array_append.json @@ -25,15 +25,20 @@ }, { "name": "label", - "description": "If the given array is a labeled array, a new label for the new value should be given. If not given or `null`, the array index as string is used as the label. If in any case the label exists, a `LabelExists` exception is thrown.", + "description": "Provides a label for the new value. If not given or `null`, the natural next array index as number is used as the label. If in any case the label exists, a `LabelExists` exception is thrown.\n\nThis parameter only applies if the given array is a labeled array. If a non-null values is provided and the array is not labeled, an `ArrayNotLabeled` exception is thrown.", "optional": true, "default": null, - "schema": { - "type": [ - "string", - "null" - ] - } + "schema": [ + { + "type": "number" + }, + { + "type": "string" + }, + { + "type": "null" + } + ] } ], "returns": { @@ -48,6 +53,9 @@ "exceptions": { "LabelExists": { "message": "An array element with the specified label already exists." + }, + "ArrayNotLabeled": { + "message": "A label can't be provided as the given array is not labeled." } }, "examples": [ From f303adfce42cba91cd436934766cfa82dddd7b53 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 27 Oct 2023 12:29:23 +0200 Subject: [PATCH 09/27] `filter_spatial`: Clarify masking (#470) * `filter_spatial`: Clarified that a masking get applied for the given geometries. #469 * `filter_bbox`: Clarified that the bounding box is reprojected to the CRS of the spatial data cube dimensions if required. --------- Co-authored-by: Stefaan Lippens --- CHANGELOG.md | 2 ++ dev/.words | 1 + filter_bbox.json | 2 +- filter_spatial.json | 4 ++-- load_collection.json | 2 +- proposals/load_stac.json | 2 +- 6 files changed, 8 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0319d15d..f3cf3bc8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- `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) - `sqrt`: Clarified that NaN is returned for negative numbers. ## [2.0.0-rc.1] - 2023-05-25 diff --git a/dev/.words b/dev/.words index a50285ba..846e729a 100644 --- a/dev/.words +++ b/dev/.words @@ -23,6 +23,7 @@ orthorectified radiometrically reflectances reproject +reprojected Reprojects resample resampled diff --git a/filter_bbox.json b/filter_bbox.json index e95d5fa2..b7335847 100644 --- a/filter_bbox.json +++ b/filter_bbox.json @@ -39,7 +39,7 @@ }, { "name": "extent", - "description": "A bounding box, which may include a vertical axis (see `base` and `height`).", + "description": "A bounding box, which may include a vertical axis (see `base` and `height`).\n\nIf the bounding box is not provided in the coordinate reference system (CRS) of the data cube, the bounding box is reprojected to the CRS of the spatial data cube dimensions.", "schema": { "type": "object", "subtype": "bounding-box", diff --git a/filter_spatial.json b/filter_spatial.json index f2648b05..ed4f7c3f 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 geometry 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.", + "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.", "categories": [ "cubes", "filter" @@ -26,7 +26,7 @@ }, { "name": "geometries", - "description": "One or more geometries used for filtering, given as GeoJSON or vector data cube. If multiple geometries are provided, the union of them is used. Empty geometries are ignored.\n\nLimits the data cube to the bounding box of the given geometries. No implicit masking gets applied. To mask the pixels of the data cube use ``mask_polygon()``.", + "description": "One or more geometries used for spatial filtering and masking, given as GeoJSON or vector data cube.", "schema": [ { "title": "Vector Data Cube", diff --git a/load_collection.json b/load_collection.json index b93c879c..a6701cc3 100644 --- a/load_collection.json +++ b/load_collection.json @@ -64,7 +64,7 @@ "default": null }, "crs": { - "description": "Coordinate reference system of the extent, specified as as [EPSG code](http://www.epsg-registry.org/) or [WKT2 CRS string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html). Defaults to `4326` (EPSG code 4326) unless the client explicitly requests a different coordinate reference system.", + "description": "Coordinate reference system of the extent, specified as as [EPSG code](http://www.epsg-registry.org/) or [WKT2 CRS string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html). Defaults to `4326` (EPSG code 4326) unless the client explicitly requests a different coordinate reference system. If the bounding box is not provided in the coordinate reference system (CRS) of the data cube, the bounding box is reprojected to the CRS of the spatial data cube dimensions.", "anyOf": [ { "title": "EPSG Code", diff --git a/proposals/load_stac.json b/proposals/load_stac.json index c71d3a80..262745fc 100644 --- a/proposals/load_stac.json +++ b/proposals/load_stac.json @@ -67,7 +67,7 @@ "default": null }, "crs": { - "description": "Coordinate reference system of the extent, specified as as [EPSG code](http://www.epsg-registry.org/) or [WKT2 CRS string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html). Defaults to `4326` (EPSG code 4326) unless the client explicitly requests a different coordinate reference system.", + "description": "Coordinate reference system of the extent, specified as as [EPSG code](http://www.epsg-registry.org/) or [WKT2 CRS string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html). Defaults to `4326` (EPSG code 4326) unless the client explicitly requests a different coordinate reference system. If the bounding box is not provided in the coordinate reference system (CRS) of the data cube, the bounding box is reprojected to the CRS of the spatial data cube dimensions.", "anyOf": [ { "title": "EPSG Code", From d8cf96a68f421a02f2e704ae6080a87841f206e1 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 30 Oct 2023 17:02:00 +0100 Subject: [PATCH 10/27] `between`: Clarify that `null` is passed through --- CHANGELOG.md | 1 + between.json | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f3cf3bc8..87dbf987 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- `between`: Clarify that `null` is passed through. - `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) - `sqrt`: Clarified that NaN is returned for negative numbers. diff --git a/between.json b/between.json index b2e59b92..12e37693 100644 --- a/between.json +++ b/between.json @@ -8,7 +8,7 @@ "parameters": [ { "name": "x", - "description": "The value to check.", + "description": "The value to check.\n\nThe no-data value `null` is passed through and therefore gets propagated.", "schema": { "description": "Any data type is allowed." } @@ -38,7 +38,7 @@ } ], "returns": { - "description": "`true` if `x` is between the specified bounds, otherwise `false`.", + "description": "`true` if `x` is between the specified bounds, `null` if `x` is a no-data value, `false` otherwise.", "schema": { "type": [ "boolean", From 899b8249911fc6f978661bfc63442696bfaeb6f8 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 30 Oct 2023 18:26:09 +0100 Subject: [PATCH 11/27] `eq` and `neq`: Explicitly set the minimum value for the `delta` parameter. --- CHANGELOG.md | 1 + eq.json | 3 ++- neq.json | 3 ++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 87dbf987..c2a4f1d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed - `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) - `sqrt`: Clarified that NaN is returned for negative numbers. diff --git a/eq.json b/eq.json index e7712399..0c62b42c 100644 --- a/eq.json +++ b/eq.json @@ -38,7 +38,8 @@ "type": [ "number", "null" - ] + ], + "minimumExclusive": 0 }, "default": null, "optional": true diff --git a/neq.json b/neq.json index ff6bc9fd..0e22b347 100644 --- a/neq.json +++ b/neq.json @@ -38,7 +38,8 @@ "type": [ "number", "null" - ] + ], + "minimumExclusive": 0 }, "default": null, "optional": true From ab2e6c233a073a1ac23abc004216794127b32c2c Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 31 Oct 2023 16:10:18 +0100 Subject: [PATCH 12/27] Clarify linear_scale_range --- linear_scale_range.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/linear_scale_range.json b/linear_scale_range.json index 172027c9..01f09857 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 any value lower than `outputMin` or greater than `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\nThe no-data value `null` is passed through and therefore gets propagated.", "categories": [ "math" ], @@ -166,4 +166,4 @@ "result": true } } -} \ No newline at end of file +} From ad8a2f3551fe9d69c1689e310bf5307e20d86113 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 8 Dec 2023 11:40:09 +0100 Subject: [PATCH 13/27] Math functions: Clarified value ranges and NaN (#476) * divide, ln, log, mod: Clarified behavior for 0 input / infinity results * Trigonometric functions: Clarified that NaN is returned outside of their defined ranges and the output value range for some processes * Clarified for various mathematical functions the defined input and output ranges. Mention that `NaN` is returned outside of the defined input range where possible. * Remove NaN --- CHANGELOG.md | 3 +++ absolute.json | 4 ++-- arccos.json | 15 +++++++++------ arcosh.json | 14 ++++++++------ arcsin.json | 12 +++++++----- arctan.json | 4 ++-- arsinh.json | 6 +++--- artanh.json | 17 ++++++++++++----- cos.json | 8 +++++--- cosh.json | 11 ++++++----- divide.json | 4 ++-- exp.json | 7 ++++--- ln.json | 9 +++++---- log.json | 9 +++++---- mod.json | 4 ++-- sgn.json | 8 +++++++- sin.json | 8 +++++--- sinh.json | 8 ++++---- tan.json | 11 ++++++++--- tanh.json | 12 +++++++----- 20 files changed, 106 insertions(+), 68 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c2a4f1d7..f70afe7b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,10 +12,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### 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. +- `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 - `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 3b6e91dc..c6a3713d 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\nThe no-data value `null` is passed through and therefore gets propagated.", "categories": [ "math" ], @@ -95,4 +95,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/arccos.json b/arccos.json index 5ffbce35..4cd498a7 100644 --- a/arccos.json +++ b/arccos.json @@ -1,29 +1,32 @@ { "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.", + "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.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "A number.", + "description": "A number in the range *[-1, 1]*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": -1, + "maximum": 1 } } ], "returns": { - "description": "The computed angle in radians.", + "description": "The computed angle in radians in the range *[0, π]*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": 0 } }, "examples": [ @@ -41,4 +44,4 @@ "title": "Inverse cosine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/arcosh.json b/arcosh.json index 6ed581fe..820b8cd4 100644 --- a/arcosh.json +++ b/arcosh.json @@ -1,29 +1,31 @@ { "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\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "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.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "A number.", + "description": "A number in the range *[1, +∞)*.", "schema": { "type": [ "number", "null" ] - } + }, + "minimum": 1 } ], "returns": { - "description": "The computed angle in radians.", + "description": "The computed hyperbolic angle in radians in the range *[0, +∞)*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": 0 } }, "examples": [ @@ -41,4 +43,4 @@ "title": "Inverse hyperbolic cosine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/arcsin.json b/arcsin.json index e37eb2d3..2c772a00 100644 --- a/arcsin.json +++ b/arcsin.json @@ -1,24 +1,26 @@ { "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.", + "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.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "A number.", + "description": "A number in the range *[-1, 1]*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": -1, + "maximum": 1 } } ], "returns": { - "description": "The computed angle in radians.", + "description": "The computed angle in radians in the range *[-π/2, π/2]*.", "schema": { "type": [ "number", @@ -41,4 +43,4 @@ "title": "Inverse sine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/arctan.json b/arctan.json index dc8d5a68..9461eba3 100644 --- a/arctan.json +++ b/arctan.json @@ -18,7 +18,7 @@ } ], "returns": { - "description": "The computed angle in radians.", + "description": "The computed angle in radians in the range *(−π/2, π/2)*.", "schema": { "type": [ "number", @@ -41,4 +41,4 @@ "title": "Inverse tangent explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/arsinh.json b/arsinh.json index 37384dcd..2b7942dd 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\nWorks on radians only.\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\nThe no-data value `null` is passed through and therefore gets propagated.", "categories": [ "math > trigonometric" ], @@ -18,7 +18,7 @@ } ], "returns": { - "description": "The computed angle in radians.", + "description": "The computed hyperbolic angle in radians.", "schema": { "type": [ "number", @@ -41,4 +41,4 @@ "title": "Inverse hyperbolic sine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/artanh.json b/artanh.json index 926b48ea..6308290d 100644 --- a/artanh.json +++ b/artanh.json @@ -1,24 +1,26 @@ { "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\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "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.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "A number.", + "description": "A number in the range *(-1, 1)*.", "schema": { "type": [ "number", "null" - ] + ], + "minimumExclusive": -1, + "maximumExclusive": 1 } } ], "returns": { - "description": "The computed angle in radians.", + "description": "The computed hyperbolic angle in radians.", "schema": { "type": [ "number", @@ -39,6 +41,11 @@ "rel": "about", "href": "http://mathworld.wolfram.com/InverseHyperbolicTangent.html", "title": "Inverse hyperbolic tangent explained by Wolfram MathWorld" + }, + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/4610935", + "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" } ] -} \ No newline at end of file +} diff --git a/cos.json b/cos.json index 6e6e4143..0d6229a8 100644 --- a/cos.json +++ b/cos.json @@ -18,12 +18,14 @@ } ], "returns": { - "description": "The computed cosine of `x`.", + "description": "The computed cosine in the range *[-1, 1]*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": -1, + "maximum": 1 } }, "examples": [ @@ -41,4 +43,4 @@ "title": "Cosine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/cosh.json b/cosh.json index 975958a4..8b56a222 100644 --- a/cosh.json +++ b/cosh.json @@ -1,14 +1,14 @@ { "id": "cosh", "summary": "Hyperbolic cosine", - "description": "Computes the hyperbolic cosine of `x`.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the hyperbolic cosine of `x`.\n\nThe no-data value `null` is passed through and therefore gets propagated.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "An angle in radians.", + "description": "An hyperbolic angle in radians.", "schema": { "type": [ "number", @@ -18,12 +18,13 @@ } ], "returns": { - "description": "The computed hyperbolic cosine of `x`.", + "description": "The computed hyperbolic cosine in the range *[1, +∞)*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": 1 } }, "examples": [ @@ -41,4 +42,4 @@ "title": "Hyperbolic cosine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/divide.json b/divide.json index 5dd664f1..0c6c254a 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. Therefore, a division by zero results in ±infinity if the processing environment supports it. Otherwise, a `DivisionByZero` exception must the thrown.", + "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.", "categories": [ "math" ], @@ -76,4 +76,4 @@ "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic" } ] -} \ No newline at end of file +} diff --git a/exp.json b/exp.json index 5a5e3283..2d551390 100644 --- a/exp.json +++ b/exp.json @@ -18,12 +18,13 @@ } ], "returns": { - "description": "The computed value for *e* raised to the power of `p`.", + "description": "The computed value for *e* raised to the power of `p`. Value is in the range of *(0, +∞)*", "schema": { "type": [ "number", "null" - ] + ], + "minimumExclusive": 0 } }, "examples": [ @@ -65,4 +66,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/ln.json b/ln.json index e073c7a2..1663771b 100644 --- a/ln.json +++ b/ln.json @@ -1,19 +1,20 @@ { "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.", + "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.", "categories": [ "math > exponential & logarithmic" ], "parameters": [ { "name": "x", - "description": "A number to compute the natural logarithm for.", + "description": "A number to compute the natural logarithm for in the range *[0, +∞)*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": 0 } } ], @@ -64,4 +65,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/log.json b/log.json index 89500837..67a19ba2 100644 --- a/log.json +++ b/log.json @@ -1,19 +1,20 @@ { "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, `log(0, 2)` results in ±infinity if the processing environment supports it or otherwise an exception is thrown.", + "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.", "categories": [ "math > exponential & logarithmic" ], "parameters": [ { "name": "x", - "description": "A number to compute the logarithm for.", + "description": "A number to compute the logarithm for in the range *[0, +∞)*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": 0 } }, { @@ -78,4 +79,4 @@ "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic" } ] -} \ No newline at end of file +} diff --git a/mod.json b/mod.json index ca709386..0c8a6ea9 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`. A modulo by zero results in ±infinity if the processing environment supports it. Otherwise, a `DivisionByZero` exception must the thrown.", + "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.", "categories": [ "math" ], @@ -92,4 +92,4 @@ "title": "Modulo explained by Wikipedia" } ] -} \ No newline at end of file +} diff --git a/sgn.json b/sgn.json index f59afdc4..ecdbd9d1 100644 --- a/sgn.json +++ b/sgn.json @@ -23,6 +23,12 @@ "type": [ "number", "null" + ], + "enum": [ + -1, + 0, + 1, + null ] } }, @@ -104,4 +110,4 @@ "result": true } } -} \ No newline at end of file +} diff --git a/sin.json b/sin.json index 06c45cc4..15285979 100644 --- a/sin.json +++ b/sin.json @@ -18,12 +18,14 @@ } ], "returns": { - "description": "The computed sine of `x`.", + "description": "The computed sine in the range *[-1, 1]*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": -1, + "maximum": 1 } }, "examples": [ @@ -41,4 +43,4 @@ "title": "Sine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/sinh.json b/sinh.json index c505b3a3..6eced19c 100644 --- a/sinh.json +++ b/sinh.json @@ -1,14 +1,14 @@ { "id": "sinh", "summary": "Hyperbolic sine", - "description": "Computes the hyperbolic sine of `x`.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the hyperbolic sine of `x`.\n\nThe no-data value `null` is passed through and therefore gets propagated.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "An angle in radians.", + "description": "An hyperbolic angle in radians.", "schema": { "type": [ "number", @@ -18,7 +18,7 @@ } ], "returns": { - "description": "The computed hyperbolic sine of `x`.", + "description": "The computed hyperbolic sine.", "schema": { "type": [ "number", @@ -41,4 +41,4 @@ "title": "Hyperbolic sine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/tan.json b/tan.json index c3952efa..6e927ffc 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.", + "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.", "categories": [ "math > trigonometric" ], @@ -18,7 +18,7 @@ } ], "returns": { - "description": "The computed tangent of `x`.", + "description": "The computed tangent.", "schema": { "type": [ "number", @@ -39,6 +39,11 @@ "rel": "about", "href": "http://mathworld.wolfram.com/Tangent.html", "title": "Tangent explained by Wolfram MathWorld" + }, + { + "rel": "about", + "href": "https://ieeexplore.ieee.org/document/4610935", + "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic" } ] -} \ No newline at end of file +} diff --git a/tanh.json b/tanh.json index 203f581e..a38462c9 100644 --- a/tanh.json +++ b/tanh.json @@ -1,14 +1,14 @@ { "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\nWorks on radians only.\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\nThe no-data value `null` is passed through and therefore gets propagated.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "An angle in radians.", + "description": "An hyperbolic angle in radians.", "schema": { "type": [ "number", @@ -18,12 +18,14 @@ } ], "returns": { - "description": "The computed hyperbolic tangent of `x`.", + "description": "The computed hyperbolic tangent in the range *(-1, 1)*.", "schema": { "type": [ "number", "null" - ] + ], + "minimumExclusive": -1, + "maximumExclusive": 1 } }, "examples": [ @@ -41,4 +43,4 @@ "title": "Hyperbolic tangent explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} From 427421595bc4b052c541de90dfdd995c44f54b30 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 22 Dec 2023 17:07:27 +0100 Subject: [PATCH 14/27] Added uniqueness contraints and clarified DimensionNotAvailable exception in temporal aggregations --- CHANGELOG.md | 2 ++ aggregate_temporal.json | 5 +++-- aggregate_temporal_period.json | 4 ++-- proposals/array_create_labeled.json | 3 ++- proposals/flatten_dimensions.json | 1 + proposals/predict_curve.json | 1 + proposals/unflatten_dimension.json | 1 + rename_labels.json | 2 ++ 8 files changed, 14 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f70afe7b..60a5aa22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,10 +9,12 @@ 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) +- Added a uniqueness contraint to various array-typed parameters (e.g. lists of dimension names or labels) ### Fixed - Clarified for various mathematical functions the defined input and output ranges. Mention that `NaN` is returned outside of the defined input range where possible. +- `aggregate_temporal` and `aggregate_temporal_period`: Clarified that the process throws a `DimensionNotAvailable` exception when no temporal dimension exists. - `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. diff --git a/aggregate_temporal.json b/aggregate_temporal.json index ad1d560b..2c66e0f2 100644 --- a/aggregate_temporal.json +++ b/aggregate_temporal.json @@ -128,6 +128,7 @@ "description": "Distinct labels for the intervals, which can contain dates and/or times. Is only required to be specified if the values for the start of the temporal intervals are not distinct and thus the default labels would not be unique. The number of labels and the number of groups need to be equal.", "schema": { "type": "array", + "uniqueItems": true, "items": { "type": [ "number", @@ -140,7 +141,7 @@ }, { "name": "dimension", - "description": "The name of the temporal dimension for aggregation. All data along the dimension is passed through the specified reducer. If the dimension is not set or set to `null`, the data cube is expected to only have one temporal dimension. Fails with a `TooManyDimensions` exception if it has more dimensions. Fails with a `DimensionNotAvailable` exception if the specified dimension does not exist.", + "description": "The name of the temporal dimension for aggregation. All data along the dimension is passed through the specified reducer. If the dimension is not set or set to `null`, the data cube is expected to only have one temporal dimension. Fails with a `TooManyDimensions` exception if it has more dimensions. Fails with a `DimensionNotAvailable` exception if the specified dimension does not exist or no temporal dimension is available.", "schema": { "type": [ "string", @@ -228,7 +229,7 @@ "message": "The data cube contains multiple temporal dimensions. The parameter `dimension` must be specified." }, "DimensionNotAvailable": { - "message": "A dimension with the specified name does not exist." + "message": "A dimension with the specified name does not exist or no temporal dimension is available." }, "DistinctDimensionLabelsRequired": { "message": "The dimension labels have duplicate values. Distinct labels must be specified." diff --git a/aggregate_temporal_period.json b/aggregate_temporal_period.json index bdaea43e..ce6d4be5 100644 --- a/aggregate_temporal_period.json +++ b/aggregate_temporal_period.json @@ -78,7 +78,7 @@ }, { "name": "dimension", - "description": "The name of the temporal dimension for aggregation. All data along the dimension is passed through the specified reducer. If the dimension is not set or set to `null`, the source data cube is expected to only have one temporal dimension. Fails with a `TooManyDimensions` exception if it has more dimensions. Fails with a `DimensionNotAvailable` exception if the specified dimension does not exist.", + "description": "The name of the temporal dimension for aggregation. All data along the dimension is passed through the specified reducer. If the dimension is not set or set to `null`, the source data cube is expected to only have one temporal dimension. Fails with a `TooManyDimensions` exception if it has more dimensions. Fails with a `DimensionNotAvailable` exception if the specified dimension does not exist or no temporal dimension is available.", "schema": { "type": [ "string", @@ -115,7 +115,7 @@ "message": "The data cube contains multiple temporal dimensions. The parameter `dimension` must be specified." }, "DimensionNotAvailable": { - "message": "A dimension with the specified name does not exist." + "message": "A dimension with the specified name does not exist or no temporal dimension is available." }, "DistinctDimensionLabelsRequired": { "message": "The dimension labels have duplicate values. Distinct labels must be specified." diff --git a/proposals/array_create_labeled.json b/proposals/array_create_labeled.json index 8b5d2034..f83d6559 100644 --- a/proposals/array_create_labeled.json +++ b/proposals/array_create_labeled.json @@ -19,6 +19,7 @@ "description": "An array of labels to be used.", "schema": { "type": "array", + "uniqueItems": true, "items": { "type": [ "number", @@ -43,4 +44,4 @@ "message": "The number of values in the parameters `data` and `labels` don't match." } } -} \ No newline at end of file +} diff --git a/proposals/flatten_dimensions.json b/proposals/flatten_dimensions.json index da3647ab..1c02bf39 100644 --- a/proposals/flatten_dimensions.json +++ b/proposals/flatten_dimensions.json @@ -20,6 +20,7 @@ "description": "The names of the dimension to combine. The order of the array defines the order in which the dimension labels and values are combined (see the example in the process description). Fails with a `DimensionNotAvailable` exception if at least one of the specified dimensions does not exist.", "schema": { "type": "array", + "uniqueItems": true, "items": { "type": "string" } diff --git a/proposals/predict_curve.json b/proposals/predict_curve.json index 479b7fec..ef3e9596 100644 --- a/proposals/predict_curve.json +++ b/proposals/predict_curve.json @@ -68,6 +68,7 @@ }, { "type": "array", + "uniqueItems": true, "items": { "anyOf": [ { diff --git a/proposals/unflatten_dimension.json b/proposals/unflatten_dimension.json index 990e7469..a5a4bb6d 100644 --- a/proposals/unflatten_dimension.json +++ b/proposals/unflatten_dimension.json @@ -27,6 +27,7 @@ "description": "The names of the new target dimensions. New dimensions will be created with the given names and type `other` (see ``add_dimension()``). Fails with a `TargetDimensionExists` exception if any of the dimensions exists.\n\nThe order of the array defines the order in which the dimensions and dimension labels are added to the data cube (see the example in the process description).", "schema": { "type": "array", + "uniqueItems": true, "minItems": 2, "items": { "type": "string" diff --git a/rename_labels.json b/rename_labels.json index 2042737d..de4f07da 100644 --- a/rename_labels.json +++ b/rename_labels.json @@ -26,6 +26,7 @@ "description": "The new names for the labels.\n\nIf a target dimension label already exists in the data cube, a `LabelExists` exception is thrown.", "schema": { "type": "array", + "uniqueItems": true, "items": { "type": [ "number", @@ -39,6 +40,7 @@ "description": "The original names of the labels to be renamed to corresponding array elements in the parameter `target`. It is allowed to only specify a subset of labels to rename, as long as the `target` and `source` parameter have the same length. The order of the labels doesn't need to match the order of the dimension labels in the data cube. By default, the array is empty so that the dimension labels in the data cube are expected to be enumerated.\n\nIf the dimension labels are not enumerated and the given array is empty, the `LabelsNotEnumerated` exception is thrown. If one of the source dimension labels doesn't exist, the `LabelNotAvailable` exception is thrown.", "schema": { "type": "array", + "uniqueItems": true, "items": { "type": [ "number", From d5d0a1896ed64573529a0cc3225e3c3e682c4d46 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 22 Dec 2023 19:26:29 +0100 Subject: [PATCH 15/27] Remove unused exception from aggregate_temporal_period, clarified week definition --- CHANGELOG.md | 2 ++ aggregate_temporal_period.json | 5 +---- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 60a5aa22..9a301787 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - 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 - `between`: Clarify that `null` is passed through. - `eq` and `neq`: Explicitly set the minimum value for the `delta` parameter. diff --git a/aggregate_temporal_period.json b/aggregate_temporal_period.json index ce6d4be5..446afa8d 100644 --- a/aggregate_temporal_period.json +++ b/aggregate_temporal_period.json @@ -23,7 +23,7 @@ }, { "name": "period", - "description": "The time intervals to aggregate. The following pre-defined values are available:\n\n* `hour`: Hour of the day\n* `day`: Day of the year\n* `week`: Week of the year\n* `dekad`: Ten day periods, counted per year with three periods per month (day 1 - 10, 11 - 20 and 21 - end of month). The third dekad of the month can range from 8 to 11 days. For example, the third dekad of a year spans from January 21 till January 31 (11 days), the fourth dekad spans from February 1 till February 10 (10 days) and the sixth dekad spans from February 21 till February 28 or February 29 in a leap year (8 or 9 days respectively).\n* `month`: Month of the year\n* `season`: Three month periods of the calendar seasons (December - February, March - May, June - August, September - November).\n* `tropical-season`: Six month periods of the tropical seasons (November - April, May - October).\n* `year`: Proleptic years\n* `decade`: Ten year periods ([0-to-9 decade](https://en.wikipedia.org/wiki/Decade#0-to-9_decade)), from a year ending in a 0 to the next year ending in a 9.\n* `decade-ad`: Ten year periods ([1-to-0 decade](https://en.wikipedia.org/wiki/Decade#1-to-0_decade)) better aligned with the anno Domini (AD) calendar era, from a year ending in a 1 to the next year ending in a 0.", + "description": "The time intervals to aggregate. The following pre-defined values are available:\n\n* `hour`: Hour of the day\n* `day`: Day of the year\n* `week`: Week of the year as defined in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Week_dates)\n* `dekad`: Ten day periods, counted per year with three periods per month (day 1 - 10, 11 - 20 and 21 - end of month). The third dekad of the month can range from 8 to 11 days. For example, the third dekad of a year spans from January 21 till January 31 (11 days), the fourth dekad spans from February 1 till February 10 (10 days) and the sixth dekad spans from February 21 till February 28 or February 29 in a leap year (8 or 9 days respectively).\n* `month`: Month of the year\n* `season`: Three month periods of the calendar seasons (December - February, March - May, June - August, September - November).\n* `tropical-season`: Six month periods of the tropical seasons (November - April, May - October).\n* `year`: Proleptic years\n* `decade`: Ten year periods ([0-to-9 decade](https://en.wikipedia.org/wiki/Decade#0-to-9_decade)), from a year ending in a 0 to the next year ending in a 9.\n* `decade-ad`: Ten year periods ([1-to-0 decade](https://en.wikipedia.org/wiki/Decade#1-to-0_decade)) better aligned with the anno Domini (AD) calendar era, from a year ending in a 1 to the next year ending in a 0.", "schema": { "type": "string", "enum": [ @@ -116,9 +116,6 @@ }, "DimensionNotAvailable": { "message": "A dimension with the specified name does not exist or no temporal dimension is available." - }, - "DistinctDimensionLabelsRequired": { - "message": "The dimension labels have duplicate values. Distinct labels must be specified." } }, "links": [ From 47b45d4fe65ed7a3dc82d879a884e7736842ef85 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 23 Jan 2024 17:44:44 +0100 Subject: [PATCH 16/27] Renamed `create_data_cube` to `create_cube`. #68 --- CHANGELOG.md | 1 + create_data_cube.json => create_cube.json | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) rename create_data_cube.json => create_cube.json (95%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a301787..d870ae83 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `clip`: Throw an exception if min > max [#472](https://github.com/Open-EO/openeo-processes/issues/472) - Added a uniqueness contraint to various array-typed parameters (e.g. lists of dimension names or labels) +- Renamed `create_data_cube` to `create_cube`. [#68](https://github.com/Open-EO/openeo-processes/issues/68) ### Fixed diff --git a/create_data_cube.json b/create_cube.json similarity index 95% rename from create_data_cube.json rename to create_cube.json index 55f0aede..0f8c7ca2 100644 --- a/create_data_cube.json +++ b/create_cube.json @@ -1,5 +1,5 @@ { - "id": "create_data_cube", + "id": "create_cube", "summary": "Create an empty data cube", "description": "Creates a new data cube without dimensions. Dimensions can be added with ``add_dimension()``.", "categories": [ From 9363471d52fe1c80cfcb8a977ea2a3f53b558750 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 26 Jul 2024 19:51:42 +0200 Subject: [PATCH 17/27] Update docgen --- dev/docs.html | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/dev/docs.html b/dev/docs.html index 04b1c192..0a7d005e 100644 --- a/dev/docs.html +++ b/dev/docs.html @@ -5,7 +5,7 @@ openEO API Processes - +