Respect user-specified coordinates attribute.

doc/io.rst

@@ -440,6 +440,17 @@ supported by netCDF4-python: 'standard', 'gregorian', 'proleptic_gregorian' 'nol
 By default, xarray uses the 'proleptic_gregorian' calendar and units of the smallest time
 difference between values, with a reference time of the first time value.
 
+Coordinates
+...........
+
+You can control the ``coordinates`` attribute written to disk by specifying ``encoding["coordinates"]``.
+If not specified, xarray automatically sets the ``"coordinates"`` attribute to a space-delimited list
+of names of coordinate variables that share dimensions with the variable.
+This allows perfect roundtripping of xarray datasets but may not be desirable.
+When an xarray dataset contains non-dimensional coordinates that do not share dimensions with any of
+the variables, these coordinate variable names are saved under a global ``"coordinates"`` attribute.
+This is not CF-compliant but again facilitates roundtripping of xarray datasets.
+
 Invalid netCDF files
 ~~~~~~~~~~~~~~~~~~~~
 

doc/whats-new.rst

@@ -63,6 +63,8 @@ New Features
   invoked. (:issue:`3378`, :pull:`3446`)
   By `Deepak Cherian <https://github.com/dcherian>`_ and
   `Guido Imperiale <https://github.com/crusaderky>`_.
+- xarray now respects the ``encoding["coordinates"]`` attribute when writing to disk. (:issue:`3351`, :pull:`3487`)
+  By `Deepak Cherian <https://github.com/dcherian>`_.
 
 Bug fixes
 ~~~~~~~~~

xarray/conventions.py

@@ -663,31 +663,42 @@ def _encode_coordinates(variables, attributes, non_dim_coord_names):
                 global_coordinates.discard(coord_name)
 
     variables = {k: v.copy(deep=False) for k, v in variables.items()}
-
-    # These coordinates are saved according to CF conventions
-    for var_name, coord_names in variable_coordinates.items():
-        attrs = variables[var_name].attrs
+    for name, var in variables.items():
+        encoding = var.encoding
+        attrs = var.attrs
         if "coordinates" in attrs:
-            raise ValueError(
-                "cannot serialize coordinates because variable "
-                "%s already has an attribute 'coordinates'" % var_name
+            warnings.warn(
+                f"'coordinates' found in attrs for variable {name!r}. This will be ignored. Instead please specify the 'coordinates' string in encoding.",
+                UserWarning,
             )
-        attrs["coordinates"] = " ".join(map(str, coord_names))
+
+        if "coordinates" in encoding:
+            warnings.warn(
+                f"'coordinates' attribute detected on variable {name!r}. This may prevent faithful roundtripping of xarray Datasets.",
+                UserWarning,
+            )
+            attrs["coordinates"] = encoding["coordinates"]
+        else:
+            if variable_coordinates[name]:
+                attrs["coordinates"] = " ".join(map(str, variable_coordinates[name]))
 
     # These coordinates are not associated with any particular variables, so we
     # save them under a global 'coordinates' attribute so xarray can roundtrip
     # the dataset faithfully. Because this serialization goes beyond CF
     # conventions, only do it if necessary.
     # Reference discussion:
-    # http://mailman.cgd.ucar.edu/pipermail/cf-metadata/2014/057771.html
+    # http://mailman.cgd.ucar.edu/pipermail/cf-metadata/2014/007571.html
     if global_coordinates:
         attributes = dict(attributes)
         if "coordinates" in attributes:
-            raise ValueError(
-                "cannot serialize coordinates because the global "
-                "attribute 'coordinates' already exists"
+            warnings.warn(
+                f"cannot serialize global coordinates {global_coordinates!r} because the global "
+                f"attribute 'coordinates' already exists. This may prevent faithful roundtripping"
+                f"of xarray datasets",
+                UserWarning,
             )
-        attributes["coordinates"] = " ".join(map(str, global_coordinates))
+        else:
+            attributes["coordinates"] = " ".join(map(str, global_coordinates))
 
     return variables, attributes
 

xarray/tests/test_backends.py

@@ -810,6 +810,17 @@ def equals_latlon(obj):
                 assert "coordinates" not in ds["lat"].attrs
                 assert "coordinates" not in ds["lon"].attrs
 
+        original["temp"].encoding["coordinates"] = "lat"
+        with self.roundtrip(original) as actual:
+            assert_identical(actual, original)
+        with create_tmp_file() as tmp_file:
+            original.to_netcdf(tmp_file)
+            with open_dataset(tmp_file, decode_coords=False) as ds:
+                assert equals_latlon(ds.precip.attrs["coordinates"])
+                assert "lon" not in ds["temp"].attrs["coordinates"]
+                assert "coordinates" not in ds["lat"].attrs
+                assert "coordinates" not in ds["lon"].attrs
+
     def test_roundtrip_endian(self):
         ds = Dataset(
             {

xarray/tests/test_conventions.py

@@ -136,6 +136,21 @@ def test_multidimensional_coordinates(self):
         # Should not have any global coordinates.
         assert "coordinates" not in attrs
 
+    def test_do_not_overwrite_user_coordinates(self):
+        orig = Dataset(
+            coords={"x": [0, 1, 2], "y": ("x", [5, 6, 7]), "z": ("x", [8, 9, 10])},
+            data_vars={"a": ("x", [1, 2, 3]), "b": ("x", [3, 5, 6])},
+        )
+        orig["a"].encoding["coordinates"] = "y"
+        orig["b"].encoding["coordinates"] = "z"
+        with pytest.warns(UserWarning, match="'coordinates' attribute"):
+            enc, _ = conventions.encode_dataset_coordinates(orig)
+        assert enc["a"].attrs["coordinates"] == "y"
+        assert enc["b"].attrs["coordinates"] == "z"
+        orig["a"].attrs["coordinates"] = "foo"
+        with pytest.warns(UserWarning, match="'coordinates' found in attrs"):
+            conventions.encode_dataset_coordinates(orig)
+
     @requires_dask
     def test_string_object_warning(self):
         original = Variable(("x",), np.array(["foo", "bar"], dtype=object)).chunk()