Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions cf_xarray/coding.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ def encode_multi_index_as_compress(ds, idxnames=None):
xarray.Dataset
Encoded Dataset with ``name`` as a integer coordinate with a ``"compress"`` attribute.

Raises
------
ValueError
If a MultiIndex level name contains whitespace, which cannot be
represented in the space-separated ``"compress"`` attribute.

References
----------
CF conventions on `compression by gathering <http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#compression-by-gathering>`_
Expand All @@ -46,6 +52,13 @@ def encode_multi_index_as_compress(ds, idxnames=None):
encoded = ds.reset_index(idxnames)
for idxname in idxnames:
mindex = ds.indexes[idxname]
for name in mindex.names:
if isinstance(name, str) and any(char.isspace() for char in name):
raise ValueError(
f"MultiIndex level name {name!r} contains whitespace and "
"cannot be represented in a CF 'compress' attribute. "
"Rename the level before encoding."
)
coords = dict(zip(mindex.names, mindex.levels, strict=False))
encoded.update(coords)
for c in coords:
Expand Down
45 changes: 45 additions & 0 deletions cf_xarray/tests/test_coding.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,51 @@
import cf_xarray as cfxr


@pytest.mark.parametrize(
"name", ["lat lon", "lat\tlon", "lat\nlon", " lat", "lat ", "lat\u2003lon"]
)
@pytest.mark.parametrize("idxnames", [None, "point", ["point"]])
def test_compression_rejects_whitespace_level_names(name, idxnames):
index = pd.MultiIndex.from_product([[1, 2], [3, 4]], names=(name, "y"))
dataset = xr.Dataset(coords=xr.Coordinates.from_pandas_multiindex(index, "point"))
before = dataset.copy(deep=True)

with pytest.raises(ValueError, match="whitespace"):
cfxr.encode_multi_index_as_compress(dataset, idxnames)

xr.testing.assert_identical(dataset, before)


def test_compression_preserves_unrelated_spaced_variable_names():
index = pd.MultiIndex.from_product([[1, 2], [3, 4]], names=("lat", "lon"))
dataset = xr.Dataset(coords=xr.Coordinates.from_pandas_multiindex(index, "point"))
dataset["unrelated variable"] = xr.DataArray(42)
encoded = cfxr.encode_multi_index_as_compress(dataset)
xr.testing.assert_identical(cfxr.decode_compress_to_multi_index(encoded), dataset)


def test_compression_only_validates_selected_indexes():
selected = pd.MultiIndex.from_product([[1, 2], [3, 4]], names=("lat", "lon"))
unselected = pd.MultiIndex.from_product(
[["a", "b"], [0, 1]], names=("site label", "site type")
)
dataset = xr.Dataset(
coords=xr.Coordinates.from_pandas_multiindex(selected, "point")
).assign_coords(xr.Coordinates.from_pandas_multiindex(unselected, "station"))
before = dataset.copy(deep=True)
encoded = cfxr.encode_multi_index_as_compress(dataset, "point")
xr.testing.assert_identical(encoded["station"], dataset["station"])
xr.testing.assert_identical(dataset, before)


def test_compression_allows_unicode_level_names():
index = pd.MultiIndex.from_product([[1, 2], [3, 4]], names=("lat_α", "lon_β"))
dataset = xr.Dataset(coords=xr.Coordinates.from_pandas_multiindex(index, "point"))
encoded = cfxr.encode_multi_index_as_compress(dataset)
assert encoded.point.attrs["compress"] == "lat_α lon_β"
xr.testing.assert_identical(cfxr.decode_compress_to_multi_index(encoded), dataset)


@pytest.mark.parametrize("with_data", [False, True])
def test_compression_preserves_unrelated_coordinates(with_data):
index = pd.MultiIndex.from_product([[1, 2], [3, 4]], names=("x", "y"))
Expand Down
4 changes: 4 additions & 0 deletions doc/coding.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ convention could be used for either {py:class}`pandas.MultiIndex` objects or `py
`cf_xarray` provides {py:func}`encode_multi_index_as_compress` and {py:func}`decode_compress_to_multi_index` to encode MultiIndex-ed
dimensions using "compression by gathering".

MultiIndex level names must not contain whitespace, because the CF `compress`
attribute stores them as a space-separated list. Rename such levels before encoding;
the validation applies only to the selected MultiIndexes, not unrelated variables.

Here's a test dataset

```{code-cell}
Expand Down
Loading