quantiles: Deprecate q in favor of probabilities #293

CHANGELOG.md

@@ -43,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Renamed `create_raster_cube` to `create_data_cube`. [#68](https://github.com/Open-EO/openeo-processes/issues/68)
 - Updated the processes based on the subtypes `raster-cube` or `vector-cube` to work with the subtype `datacube` instead. [#68](https://github.com/Open-EO/openeo-processes/issues/68)
 - `sort` and `order`: The ordering of ties is not defined anymore. [#409](https://github.com/Open-EO/openeo-processes/issues/409)
+- `quantiles`: Parameter `probabilities` provided as array must be in ascending order. [#297](https://github.com/Open-EO/openeo-processes/pull/297)
 
 ### Removed
 
@@ -92,6 +93,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - Renamed to `inspect`.
     - The log level `error` does not need to stop execution.
     - Added proposals for logging several data types to the implementation guide.
+- `quantiles`: The parameter `probabilities` also accepts an integer value to compute q-quantiles. [#293](https://github.com/Open-EO/openeo-processes/issues/293)
+
+### Deprecated
+
+- `quantiles`: The parameter `q` has been deprecated in favor of the extended parameter `probabilities`. [#293](https://github.com/Open-EO/openeo-processes/issues/293)
 
 ### Removed
 

quantiles.json

@@ -1,7 +1,7 @@
 {
     "id": "quantiles",
     "summary": "Quantiles",
-    "description": "Calculates quantiles, which are cut points dividing the range of a sample distribution into either\n\n* intervals corresponding to the given `probabilities` or\n* equal-sized intervals (q-quantiles based on the parameter `q`).\n\nEither the parameter `probabilities` or `q` must be specified, otherwise the `QuantilesParameterMissing` exception is thrown. If both parameters are set the `QuantilesParameterConflict` exception is thrown.\n\nSample quantiles can be computed with several different algorithms. Hyndman and Fan (1996) have concluded on nine different types, which are commonly implemented in statistical software packages. This process is implementing type 7, which is implemented widely and often also the default type (e.g. in Excel, Julia, Python, R and S).",
+    "description": "Calculates quantiles, which are cut points dividing the range of a sample distribution into either\n\n1. intervals corresponding to the given probabilities *or*\n2. equal-sized intervals (q-quantiles).\n\nEither the parameter `probabilities` or `q` must be specified, otherwise the `QuantilesParameterMissing` exception is thrown. If both parameters are set the `QuantilesParameterConflict` exception is thrown.\n\nSample quantiles can be computed with several different algorithms. Hyndman and Fan (1996) have concluded on nine different types, which are commonly implemented in statistical software packages. This process is implementing type 7, which is implemented widely and often also the default type (e.g. in Excel, Julia, Python, R and S).",
     "categories": [
         "math > statistics"
     ],
@@ -21,20 +21,30 @@
         },
         {
             "name": "probabilities",
-            "description": "A list of probabilities to calculate quantiles for. The probabilities must be between 0 and 1 (inclusive).",
-            "schema": {
-                "type": "array",
-                "items": {
-                    "type": "number",
-                    "minimum": 0,
-                    "maximum": 1
+            "description": "Quantiles to calculate. Either a list of probabilities or the number of intervals:\n\n* Provide an array with a sorted list of probabilities in ascending order to calculate quantiles for. The probabilities must be between 0 and 1 (inclusive). If not sorted in ascending order, an `AscendingProbabilitiesRequired` exception is thrown.\n* Provide an integer to specify the number of intervals to calculate quantiles for. Calculates q-quantiles with equal-sized intervals.",
+            "schema": [
+                {
+                    "title": "List of probabilities",
+                    "type": "array",
+                    "uniqueItems": true,
+                    "items": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                    }
+                },
+                {
+                    "title": "Number of intervals (q-quantiles)",
+                    "type": "integer",
+                    "minimum": 2
                 }
-            },
+            ],
             "optional": true
         },
         {
             "name": "q",
-            "description": "Number of intervals to calculate quantiles for. Calculates q-quantiles with equal-sized intervals.",
+            "description": "Number of intervals to calculate quantiles for. Calculates q-quantiles with equal-sized intervals.\n\nThis parameter has been **deprecated**. Please use the parameter `probabilities` instead.",
+            "deprecated": true,
             "schema": {
                 "type": "integer",
                 "minimum": 2
@@ -69,6 +79,9 @@
         },
         "QuantilesParameterConflict": {
             "message": "The process `quantiles` only allows that either the `probabilities` or the `q` parameter is set."
+        },
+        "AscendingProbabilitiesRequired": {
+            "message": "The values passed for parameter `probabilities` must be sorted in ascending order."
         }
     },
     "examples": [
@@ -114,7 +127,7 @@
                     7,
                     9
                 ],
-                "q": 4
+                "probabilities": 4
             },
             "returns": [
                 4,
@@ -130,7 +143,7 @@
                     null,
                     1
                 ],
-                "q": 2
+                "probabilities": 2
             },
             "returns": [
                 -0.5
@@ -144,7 +157,7 @@
                     null,
                     1
                 ],
-                "q": 4,
+                "probabilities": 4,
                 "ignore_nodata": false
             },
             "returns": [
@@ -181,4 +194,4 @@
             "title": "Hyndman and Fan (1996): Sample Quantiles in Statistical Packages"
         }
     ]
-}
+}