Support _FillValue or missing_value encoding

Author: spencerkclark

xarray/coding/times.py

@@ -94,8 +94,6 @@
 
 
 _INVALID_LITERAL_TIMEDELTA64_ENCODING_KEYS = [
-    "_FillValue",
-    "missing_value",
     "add_offset",
     "scale_factor",
 ]
@@ -1465,17 +1463,17 @@ def encode(self, variable: Variable, name: T_Name = None) -> Variable:
                     k in encoding for k in _INVALID_LITERAL_TIMEDELTA64_ENCODING_KEYS
                 ):
                     raise ValueError(
-                        f"Specifying '_FillValue', 'missing_value', "
-                        f"'add_offset', or 'scale_factor' is not supported "
-                        f"when literally encoding the np.timedelta64 values "
-                        f"of variable {name!r}. To encode {name!r} with such "
-                        f"encoding parameters, additionally set "
-                        f"encoding['units'] to a unit of time, e.g. "
-                        f"'seconds'. To proceed with literal np.timedelta64 "
-                        f"encoding of {name!r}, remove any encoding entries "
-                        f"for '_FillValue', 'missing_value', 'add_offset', "
-                        f"or 'scale_factor'."
+                        f"Specifying 'add_offset' or 'scale_factor' is not "
+                        f"supported when literally encoding the "
+                        f"np.timedelta64 values of variable {name!r}. To "
+                        f"encode {name!r} with such encoding parameters, "
+                        f"additionally set encoding['units'] to a unit of "
+                        f"time, e.g. 'seconds'. To proceed with literal "
+                        f"np.timedelta64 encoding of {name!r}, remove any "
+                        f"encoding entries for 'add_offset' or 'scale_factor'."
                     )
+                if "_FillValue" not in encoding and "missing_value" not in encoding:
+                    encoding["_FillValue"] = np.iinfo(np.int64).min
 
             data, units = encode_cf_timedelta(data, units, dtype)
             safe_setitem(attrs, "units", units, name=name)
@@ -1500,9 +1498,8 @@ def decode(self, variable: Variable, name: T_Name = None) -> Variable:
                 ):
                     raise ValueError(
                         "Decoding np.timedelta64 values via dtype is not "
-                        "supported when '_FillValue', 'missing_value', "
-                        "'add_offset', or 'scale_factor' are present in "
-                        "encoding."
+                        "supported when 'add_offset', or 'scale_factor' are "
+                        "present in encoding."
                     )
                 dtype = pop_to(attrs, encoding, "dtype", name=name)
                 dtype = np.dtype(dtype)

xarray/tests/test_coding_times.py

@@ -1964,14 +1964,15 @@ def test_decode_floating_point_timedelta_no_serialization_warning() -> None:
 
 
 def test_literal_timedelta64_coding(time_unit: PDDatetimeUnitOptions) -> None:
-    timedeltas = pd.timedelta_range(0, freq="D", periods=3, unit=time_unit)  # type: ignore[call-arg]
+    timedeltas = np.array([0, 1, "NaT"], dtype=f"timedelta64[{time_unit}]")
     variable = Variable(["time"], timedeltas)
     expected_dtype = f"timedelta64[{time_unit}]"
     expected_units = _numpy_to_netcdf_timeunit(time_unit)
 
     encoded = conventions.encode_cf_variable(variable)
     assert encoded.attrs["dtype"] == expected_dtype
     assert encoded.attrs["units"] == expected_units
+    assert encoded.attrs["_FillValue"] == np.iinfo(np.int64).min
 
     decoded = conventions.decode_cf_variable("timedeltas", encoded)
     assert decoded.encoding["dtype"] == expected_dtype
@@ -2011,7 +2012,7 @@ def test_literal_timedelta_encode_invalid_attribute(attribute) -> None:
 
 
 @pytest.mark.parametrize("invalid_key", _INVALID_LITERAL_TIMEDELTA64_ENCODING_KEYS)
-def test_literal_timedelta_encoding_mask_and_scale_error(invalid_key) -> None:
+def test_literal_timedelta_encoding_invalid_key_error(invalid_key) -> None:
     encoding = {invalid_key: 1.0}
     timedeltas = pd.timedelta_range(0, freq="D", periods=3)
     variable = Variable(["time"], timedeltas, encoding=encoding)
@@ -2020,7 +2021,7 @@ def test_literal_timedelta_encoding_mask_and_scale_error(invalid_key) -> None:
 
 
 @pytest.mark.parametrize("invalid_key", _INVALID_LITERAL_TIMEDELTA64_ENCODING_KEYS)
-def test_literal_timedelta_decoding_mask_and_scale_error(invalid_key) -> None:
+def test_literal_timedelta_decoding_invalid_key_error(invalid_key) -> None:
     attrs = {invalid_key: 1.0, "dtype": "timedelta64[s]", "units": "seconds"}
     variable = Variable(["time"], [0, 1, 2], attrs=attrs)
     with pytest.raises(ValueError, match=invalid_key):
@@ -2044,6 +2045,12 @@ def test_literal_timedelta_decoding_mask_and_scale_error(invalid_key) -> None:
 def test_timedelta_decoding_options(
     decode_via_units, decode_via_dtype, attrs, expect_timedelta64
 ) -> None:
+    # Note with literal timedelta encoding, we always add a _FillValue, even
+    # if one is not present in the original encoding parameters, which is why
+    # we ensure one is defined here when "dtype" is present in attrs.
+    if "dtype" in attrs:
+        attrs["_FillValue"] = np.iinfo(np.int64).min
+
     array = np.array([0, 1, 2], dtype=np.dtype("int64"))
     encoded = Variable(["time"], array, attrs=attrs)
 
@@ -2083,3 +2090,33 @@ def test_timedelta_encoding_explicit_non_timedelta64_dtype() -> None:
     assert_identical(reencoded, encoded)
     assert encoded.attrs["units"] == "days"
     assert encoded.dtype == np.dtype("int32")
+
+
+@pytest.mark.parametrize("mask_attribute", ["_FillValue", "missing_value"])
+def test_literal_timedelta64_coding_with_mask(
+    time_unit: PDDatetimeUnitOptions, mask_attribute: str
+) -> None:
+    timedeltas = np.array([0, 1, "NaT"], dtype=f"timedelta64[{time_unit}]")
+    mask = 10
+    variable = Variable(["time"], timedeltas, encoding={mask_attribute: mask})
+    expected_dtype = f"timedelta64[{time_unit}]"
+    expected_units = _numpy_to_netcdf_timeunit(time_unit)
+
+    encoded = conventions.encode_cf_variable(variable)
+    assert encoded.attrs["dtype"] == expected_dtype
+    assert encoded.attrs["units"] == expected_units
+    assert encoded.attrs[mask_attribute] == mask
+    assert encoded[-1] == mask
+
+    decoded = conventions.decode_cf_variable("timedeltas", encoded)
+    assert decoded.encoding["dtype"] == expected_dtype
+    assert decoded.encoding["units"] == expected_units
+    assert decoded.encoding[mask_attribute] == mask
+    assert np.isnat(decoded[-1])
+
+    assert_identical(decoded, variable)
+    assert decoded.dtype == variable.dtype
+
+    reencoded = conventions.encode_cf_variable(decoded)
+    assert_identical(reencoded, encoded)
+    assert reencoded.dtype == encoded.dtype