Deprecate decode timedelta

doc/io.rst

@@ -335,6 +335,10 @@ like ``'days'`` for ``timedelta64`` data. ``calendar`` should be one of the cale
 supported by netCDF4-python: 'standard', 'gregorian', 'proleptic_gregorian' 'noleap',
 '365_day', '360_day', 'julian', 'all_leap', '366_day'.
 
+The automatic decoding of untis like ``'days'`` to ``timedelta64`` is deprecated and
+will be removed in xarray version 0.11. The default behavior will keep the same numeric
+type of the original data instead of converting to ``timedelta64``.
+
 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.
 

doc/time-series.rst

@@ -41,8 +41,8 @@ converted automatically when used as arguments in xarray objects:
     import datetime
     xr.Dataset({'time': datetime.datetime(2000, 1, 1)})
 
-When reading or writing netCDF files, xarray automatically decodes datetime and
-timedelta arrays using `CF conventions`_ (that is, by using a ``units``
+When reading or writing netCDF files, xarray automatically decodes datetime
+arrays using `CF conventions`_ (that is, by using a ``units``
 attribute like ``'days since 2000-01-01'``).
 
 .. _CF conventions: http://cfconventions.org

doc/whats-new.rst

@@ -40,6 +40,19 @@ Enhancements
   This greatly boosts speed and allows chunking on the core dims.
   The function now requires dask >= 0.17.3 to work on dask-backed data
   (:issue:`2074`). By `Guido Imperiale <https://github.com/crusaderky>`_.
+- Deprecate the automatic decoding of time data to timedelta64 (:issue:`1621`).
+
+  .. ipython:: python
+
+    In [1]: wave_periods = xr.Variable(['t'], [0, 1, 2])
+    In [2]: wave_periods.attrs.update({'units': 'seconds'})
+    In [3]: current_behavior = xr.conventions.decode_cf_variable('t', wave_periods)
+    In [4]: print(current_behavior.dtype)
+            timedelta64[ns]
+    In [5]: with xr.set_options(enable_future_time_unit_decoding=True):
+       ...:     new_behavior = xr.conventions.decode_cf_variable('t', wave_periods)
+    In [6]: print(new_behavior.dtype)
+            int64
 
 Bug fixes
 ~~~~~~~~~

xarray/conventions.py

@@ -9,6 +9,7 @@
 from .coding import times, strings, variables
 from .coding.variables import SerializationWarning
 from .core import duck_array_ops, indexing
+from .core.options import OPTIONS
 from .core.pycompat import (
     OrderedDict, basestring, bytes_type, iteritems, dask_array_type,
     unicode_type)
@@ -293,10 +294,19 @@ def decode_cf_variable(name, var, concat_characters=True, mask_and_scale=True,
                       variables.CFScaleOffsetCoder()]:
             var = coder.decode(var, name=name)
 
+    enable_future_time_unit_decoding = OPTIONS[
+        'enable_future_time_unit_decoding']
     if decode_times:
-        for coder in [times.CFTimedeltaCoder(),
-                      times.CFDatetimeCoder()]:
+        if enable_future_time_unit_decoding:
+            coder = times.CFDatetimeCoder()
             var = coder.decode(var, name=name)
+        else:
+            warnings.warn('Decoding timedeltas been deprecated and '
+                          'will be removed in xarray v0.11.',
+                          FutureWarning, stacklevel=2)
+            for coder in [times.CFTimedeltaCoder(),
+                          times.CFDatetimeCoder()]:
+                var = coder.decode(var, name=name)
 
     dimensions, data, attributes, encoding = (
         variables.unpack_for_decoding(var))

xarray/core/options.py

@@ -3,6 +3,7 @@
 OPTIONS = {
     'display_width': 80,
     'arithmetic_join': 'inner',
+    'enable_future_time_unit_decoding': False,
 }
 
 

xarray/tests/test_conventions.py

@@ -9,7 +9,7 @@
 import pytest
 
 from xarray import (Dataset, Variable, SerializationWarning, coding,
-                    conventions, open_dataset)
+                    conventions, open_dataset, set_options)
 from xarray.backends.common import WritableCFDataStore
 from xarray.backends.memory import InMemoryDataStore
 from xarray.conventions import decode_cf
@@ -175,6 +175,23 @@ def test_decode_cf_with_multiple_missing_values(self):
             assert_identical(expected, actual)
             assert 'has multiple fill' in str(w[0].message)
 
+    def test_decode_cf_raises_timedelta_deprecation(self):
+        original = Variable(['t'], [0, 1, 2])
+        original.attrs.update({'units': 'seconds'})
+        with warnings.catch_warnings(record=True) as w:
+            actual = conventions.decode_cf_variable('t', original)
+            assert 'Decoding timedeltas been deprecated' in str(w[0].message)
+            assert np.issubdtype(actual.dtype, np.timedelta64)
+
+    def test_decode_cf_enable_future_time_unit_decoding(self):
+        with set_options(enable_future_time_unit_decoding=True):
+            original = Variable(['t'], [0, 1, 2])
+            original.attrs.update({'units': 'seconds'})
+            with warnings.catch_warnings(record=True) as w:
+                actual = conventions.decode_cf_variable('t', original)
+                assert not w
+                assert np.issubdtype(actual.dtype, original.dtype)
+
     def test_decode_cf_with_drop_variables(self):
         original = Dataset({
             't': ('t', [0, 1, 2], {'units': 'days since 2000-01-01'}),