Combine dimensions and vice-versa #308

CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased / Draft
 
+### Added
+
+- New processes in proposal state:
+    - `flatten_dimensions`
+    - `unflatten_dimension`
+
 ### Changed
 
 - Added better support for labeled arrays. Labels are not discarded in all cases anymore. Affected processes:

proposals/flatten_dimensions.json

@@ -0,0 +1,58 @@
+{
+    "id": "flatten_dimensions",
+    "summary": "Combine multiple dimensions into a single dimension",
+    "description": "Combines multiple given dimensions into a single dimension by flattening the values and merging the dimension labels with the given `label_separator`. Non-string dimension labels will be converted to strings. This process is the opposite of the process ``unflatten_dimensions()`` but executing both processes subsequently doesn't necessarily create a data cube that is equal to the original data cube.\n\nExample: Executing the process with a data cube with two dimensions `A` (labels: `2020` and `2021`) and `B` (labels: `B1` and `B2`) and the data `[[1,2],[3,4]]` and the parameters `dimensions` = `[A,B]` and `target_dimension` = `X` will result in a data cube with one dimension `X` (labels: `2020~B1`, `2020~B2`, `2021~B1` and `2021~B2`) and the data `[1,2,3,4]`.",
+    "categories": [
+        "cubes"
+    ],
+    "experimental": true,
+    "parameters": [
+        {
+            "name": "data",
+            "description": "A data cube.",
+            "schema": {
+                "type": "object",
+                "subtype": "raster-cube"
+            }
+        },
+        {
+            "name": "dimensions",
+            "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.\n\nFails with a `DimensionNotAvailable` exception if at least one of the specified dimensions does not exist.",
+            "schema": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            }
+        },
+        {
+            "name": "target_dimension",
+            "description": "The name of a target dimension with a single dimension label to replace. If a dimension with the given name doesn't exist yet, it is created with the specified name and the type `other` (see ``add_dimension()``).",
+            "schema": {
+                "type": "string"
+            }
+        },
+        {
+            "name": "label_separator",
+            "description": "The string that will be used as a separator for the concatenated dimension labels.\n\nTo unambiguously revert the dimension labels with the process ``explode_dimensions()``, the given string must not be contained in any of the dimension labels.",
+            "optional": true,
+            "default": "~",
+            "schema": {
+                "type": "string",
+                "minLength": 1
+            }
+        }
+    ],
+    "returns": {
+        "description": "A data cube with the new shape. The dimension properties (name, type, labels, reference system and resolution) for all other dimensions remain unchanged.",
+        "schema": {
+            "type": "object",
+            "subtype": "raster-cube"
+        }
+    },
+    "exceptions": {
+        "DimensionNotAvailable": {
+            "message": "A dimension with the specified name does not exist."
+        }
+    }
+}

proposals/unflatten_dimension.json

@@ -0,0 +1,58 @@
+{
+    "id": "unflatten_dimension",
+    "summary": "Split a single dimensions into multiple dimensions",
+    "description": "Splits a single dimension into multiple dimensions by systematically extracting values and splitting the dimension labels by the given `label_separator`. This process is the opposite of the process ``flatten_dimensions()`` but executing both processes subsequently doesn't necessarily create a data cube that is equal to the original data cube.\n\nExample: Executing the process with a data cube with one dimension `X` (labels: `2020~B1`, `2020~B2`, `2021~B1` and `2021~B2`) and the data `[1,2,3,4]` and the parameters `dimension` = `X` and `target_dimensions` = `[A,B]` will result in a data cube with two dimensions `A` (labels: `2020` and `2021`) and B (labels: `B1` and `B2`) and the data `[[1,2],[3,4]]`.",
+    "categories": [
+        "cubes"
+    ],
+    "experimental": true,
+    "parameters": [
+        {
+            "name": "data",
+            "description": "A data cube that is consistently structured so that operation can execute flawlessly (e.g. the dimension labels need to contain the `label_separator` exactly 1 time for two target dimensions, 2 times for three target dimensions etc.).",
+            "schema": {
+                "type": "object",
+                "subtype": "raster-cube"
+            }
+        },
+        {
+            "name": "dimension",
+            "description": "The name of the dimension to split. The order of the array defines the order in which the dimension labels and values are split.\n\nFails with a `DimensionNotAvailable` exception if the specified dimension does not exist.",
+            "schema": {
+                "type": "string"
+            }
+        },
+        {
+            "name": "target_dimensions",
+            "description": "The names of the target dimensions, each with a single dimension label to replace. Non-existing dimensions will be created with the specified name and the type `other` (see ``add_dimension()``).",
+            "schema": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            }
+        },
+        {
+            "name": "label_separator",
+            "description": "The string that will be used as a separator to split the dimension labels. Each label will be split at the first occurrence of the given string only.",
+            "optional": true,
+            "default": "~",
+            "schema": {
+                "type": "string",
+                "minLength": 1
+            }
+        }
+    ],
+    "returns": {
+        "description": "A data cube with the new shape. The dimension properties (name, type, labels, reference system and resolution) for all other dimensions remain unchanged.",
+        "schema": {
+            "type": "object",
+            "subtype": "raster-cube"
+        }
+    },
+    "exceptions": {
+        "DimensionNotAvailable": {
+            "message": "A dimension with the specified name does not exist."
+        }
+    }
+}