Merge branch 'main' into forman-break_node_traversal

# Conflicts:
#	CHANGES.md

Author: forman

CHANGES.md

@@ -1,9 +1,10 @@
 
 ## Early development snapshots
 
-- Version 0.0.3 (in development)
+- Version 0.0.3 (08.01.2025)
   - enhanced "simple" output format by colors and links 
   - new xcube rule "increasing-time"
+  - new xcube rule "data-var-colors"
   - new `RuleExit` exception to exit rule logic and 
     stop further node traversal
 

README.md

@@ -17,19 +17,19 @@ there is no stable release yet. See
 
 ## Features 
 
-- Flexible validation for `xarray.Dataset` objects by configurable _rules_.
-- Available from _CLI_ and _Python API_.
-- _Custom plugins_ providing _custom rule_ sets allow addressing 
+- Flexible validation for `xarray.Dataset` objects by configurable rules.
+- Available from CLI and Python API.
+- Custom plugins providing custom rule sets allow addressing 
   different dataset conventions.
-- _Project-specific configurations_ including configuration of individual 
+- Project-specific configurations including configuration of individual 
   rules and file-specific settings.
 
 ## Inbuilt Rules
 
 The following rule plugins are currently built into the code base:
 
 - `xrlint.plugins.core`: Implementing the rules for
-  [tiny data](https://tutorial.xarray.dev/intermediate/data_cleaning/05.1_intro.html)
+  [tidy data](https://tutorial.xarray.dev/intermediate/data_cleaning/05.1_intro.html)
   and the 
   [CF-Conventions](https://cfconventions.org/cf-conventions/cf-conventions.html).
 - `xrlint.plugins.core`: Implementing the rules for 

docs/cli.md

@@ -6,14 +6,14 @@ The following are the command's options and arguments:
 ```
 Usage: xrlint [OPTIONS] [FILES]...
 
-  Lint the given dataset FILES.
+  Validate the given dataset FILES.
 
-  Reads configuration from `./xrlint.config.py` if `--no-default-config` is
-  not set and `--config PATH` is not provided, then validates each dataset in
-  FILES against the configuration. The validation result is dumped to standard
-  output if not otherwise stated by `--output-file PATH`. The output format is
-  `simple`. Other inbuilt formats are `json` and `html` which can by setting
-  the `--format NAME` option.
+  Reads configuration from `xrlint.config.*` if file exists and unless `--no-
+  default-config` is set or `--config PATH` is provided. Then validates each
+  dataset in FILES against the configuration. The validation result is dumped
+  to standard output if not otherwise stated by `--output-file PATH`. The
+  output format is `simple`. Other inbuilt formats are `json` and `html` which
+  can by setting the `--format NAME` option.
 
 Options:
   --no-default-config     Disable use of default configuration from
@@ -24,12 +24,12 @@ Options:
                           that defines an 'export_plugin()' function.
   --rule SPEC             Specify rules. SPEC must have format '<rule-name>:
                           <rule-config>' (note the space character).
-  -f, --format NAME       Use a specific output format - default: simple
   -o, --output-file PATH  Specify file to write report to
+  -f, --format NAME       Use a specific output format - default: simple
+  --color / --no-color    Force enabling/disabling of color
   --max-warnings COUNT    Number of warnings to trigger nonzero exit code -
                           default: 5
   --init                  Write initial configuration file and exit.
   --version               Show the version and exit.
   --help                  Show this message and exit.
-
 ```

docs/index.md

@@ -10,19 +10,20 @@ there is no stable release yet. See [to-do list](https://github.com/bcdev/xrlint
 
 ## Features 
 
-- Flexible validation for `xarray.Dataset` objects by configurable _rules_.
-- Available from _CLI_ and _Python API_.
-- _Custom plugins_ providing _custom rule_ sets allow addressing 
+- Flexible validation for `xarray.Dataset` objects by configurable rules.
+- Available from CLI and Python API.
+- Custom plugins providing custom rule sets allow addressing 
   different dataset conventions.
-- _Project-specific configurations_ including configuration of individual 
+- Project-specific configurations including configuration of individual 
   rules and file-specific settings.
 
+
 ## Inbuilt Rules
 
 The following rule plugins are currently built into the code base:
 
 - `core`: Implementing the rules for
-  [tiny data](https://tutorial.xarray.dev/intermediate/data_cleaning/05.1_intro.html)
+  [tidy data](https://tutorial.xarray.dev/intermediate/data_cleaning/05.1_intro.html)
   and the 
   [CF-Conventions](https://cfconventions.org/cf-conventions/cf-conventions.html).
 - `xcube`: Implementing the rules for 

docs/rule-ref.md

@@ -46,12 +46,25 @@ Order of dimensions in spatio-temporal datacube variables should be [time, ...,
 
 Contained in:  `all`-:material-lightning-bolt: `recommended`-:material-lightning-bolt:
 
+### :material-lightbulb: `data-var-colors`
+
+Spatial data variables should encode xcube color mappings in their metadata.
+[More information.](https://xcube.readthedocs.io/en/latest/cubespec.html#encoding-of-colors)
+
+Contained in:  `all`-:material-lightning-bolt: `recommended`-:material-alert:
+
 ### :material-lightbulb: `grid-mapping-naming`
 
 Grid mapping variables should be called 'spatial_ref' or 'crs' for compatibility with rioxarray and other packages.
 
 Contained in:  `all`-:material-lightning-bolt: `recommended`-:material-alert:
 
+### :material-bug: `increasing-time`
+
+Time coordinate labels should be monotonically increasing.
+
+Contained in:  `all`-:material-lightning-bolt: `recommended`-:material-lightning-bolt:
+
 ### :material-bug: `lat-lon-naming`
 
 Latitude and longitude coordinates and dimensions should be called 'lat' and 'lon'.

tests/plugins/xcube/rules/test_data_var_colors.py

@@ -0,0 +1,84 @@
+import numpy as np
+
+from xrlint.plugins.xcube.rules.data_var_colors import DataVarColors
+
+import xarray as xr
+
+from xrlint.testing import RuleTester, RuleTest
+
+
+def make_dataset():
+    dims = ["time", "y", "x"]
+    n = 5
+    return xr.Dataset(
+        attrs=dict(title="v-data"),
+        coords={
+            dims[2]: xr.DataArray(
+                np.linspace(0, 1, n), dims=dims[2], attrs={"units": "m"}
+            ),
+            dims[1]: xr.DataArray(
+                np.linspace(0, 1, n), dims=dims[1], attrs={"units": "m"}
+            ),
+            dims[0]: xr.DataArray(
+                [2010, 2011, 2012, 2013, 2014],
+                dims=dims[0],
+                attrs={"units": "years"},
+            ),
+        },
+        data_vars={
+            "chl": xr.DataArray(
+                np.random.random((n, n, n)),
+                dims=dims,
+                attrs={
+                    "units": "mg/m^-3",
+                    "color_bar_name": "plasma",
+                    "color_value_min": 0,
+                    "color_value_max": 100,
+                    "color_norm": "log",
+                },
+            ),
+        },
+    )
+
+
+valid_dataset_1 = make_dataset()
+
+invalid_dataset_1 = make_dataset()
+invalid_dataset_1.chl.attrs = {
+    "units": "mg/m^-3",
+    # Missing:
+    # "color_bar_name": "plasma",
+    # "color_value_min": 0,
+    # "color_value_max": 100,
+    # "color_norm": "log",
+}
+invalid_dataset_2 = make_dataset()
+invalid_dataset_2.chl.attrs = {
+    "units": "mg/m^-3",
+    "color_bar_name": "plasma",
+    # Missing:
+    # "color_value_min": 0,
+    # "color_value_max": 100,
+    # "color_norm": "log",
+}
+invalid_dataset_3 = make_dataset()
+invalid_dataset_3.chl.attrs = {
+    "units": "mg/m^-3",
+    "color_bar_name": "plasma",
+    "color_value_min": 0,
+    "color_value_max": 100,
+    "color_norm": "ln",  # wrong
+}
+
+LatLonNamingTest = RuleTester.define_test(
+    "data-var-colors",
+    DataVarColors,
+    valid=[
+        RuleTest(dataset=valid_dataset_1),
+    ],
+    invalid=[
+        RuleTest(dataset=invalid_dataset_1),
+        RuleTest(dataset=invalid_dataset_2),
+        RuleTest(dataset=invalid_dataset_3),
+    ],
+)

tests/plugins/xcube/test_plugin.py

@@ -21,6 +21,7 @@ def test_rules_complete(self):
             {
                 "any-spatial-data-var",
                 "cube-dims-order",
+                "data-var-colors",
                 "grid-mapping-naming",
                 "lat-lon-naming",
                 "single-grid-mapping",

xrlint/plugins/xcube/__init__.py

@@ -17,6 +17,7 @@ def export_plugin() -> Plugin:
             "rules": {
                 "xcube/any-spatial-data-var": "error",
                 "xcube/cube-dims-order": "error",
+                "xcube/data-var-colors": "warn",
                 "xcube/grid-mapping-naming": "warn",
                 "xcube/increasing-time": "error",
                 "xcube/lat-lon-naming": "error",

xrlint/plugins/xcube/rules/data_var_colors.py

@@ -0,0 +1,43 @@
+import numpy as np
+
+from xrlint.node import DataArrayNode
+from xrlint.plugins.xcube.rules import plugin
+from xrlint.plugins.xcube.util import is_spatial_var
+from xrlint.rule import RuleContext
+from xrlint.rule import RuleOp
+
+
+@plugin.define_rule(
+    "data-var-colors",
+    version="1.0.0",
+    type="suggestion",
+    description=(
+        "Spatial data variables should encode"
+        " xcube color mappings in their metadata."
+    ),
+    docs_url=(
+        "https://xcube.readthedocs.io/en/latest/cubespec.html#encoding-of-colors"
+    ),
+)
+class DataVarColors(RuleOp):
+    def data_array(self, ctx: RuleContext, node: DataArrayNode):
+        array = node.data_array
+        if not node.in_data_vars() or not is_spatial_var(array):
+            return
+        attrs = array.attrs
+        color_bar_name = attrs.get("color_bar_name")
+        if not color_bar_name:
+            ctx.report("Missing attribute 'color_bar_name'")
+        else:
+            color_value_min = attrs.get("color_value_min")
+            color_value_max = attrs.get("color_value_max")
+            if color_value_min is None or color_value_max is None:
+                ctx.report(
+                    "Missing both or one of 'color_value_min' and 'color_value_max'"
+                )
+
+            color_norm = attrs.get("color_norm")
+            if color_norm and color_norm not in ("lin", "log"):
+                ctx.report(
+                    "Invalid value of attribute 'color_norm', should be 'lin' or 'log'"
+                )