ENH: DTI/TDI as_unit (#50616)

* ENH: DTI/TDI as_unit

* mypy fixup

* docstring

* validation for uit

Author: jbrockmendel

doc/source/reference/indexing.rst

@@ -385,6 +385,7 @@ Conversion
 .. autosummary::
    :toctree: api/
 
+   DatetimeIndex.as_unit
    DatetimeIndex.to_period
    DatetimeIndex.to_pydatetime
    DatetimeIndex.to_series
@@ -423,6 +424,7 @@ Conversion
 .. autosummary::
    :toctree: api/
 
+   TimedeltaIndex.as_unit
    TimedeltaIndex.to_pytimedelta
    TimedeltaIndex.to_series
    TimedeltaIndex.round

doc/source/whatsnew/v2.0.0.rst

@@ -150,6 +150,7 @@ Other enhancements
 - :meth:`DataFrame.plot.hist` now recognizes ``xlabel`` and ``ylabel`` arguments (:issue:`49793`)
 - Improved error message in :func:`to_datetime` for non-ISO8601 formats, informing users about the position of the first error (:issue:`50361`)
 - Improved error message when trying to align :class:`DataFrame` objects (for example, in :func:`DataFrame.compare`) to clarify that "identically labelled" refers to both index and columns (:issue:`50083`)
+- Added :meth:`DatetimeIndex.as_unit` and :meth:`TimedeltaIndex.as_unit` to convert to different resolutions; supported resolutions are "s", "ms", "us", and "ns" (:issue:`50616`)
 -
 
 .. ---------------------------------------------------------------------------

pandas/core/arrays/datetimelike.py

@@ -1971,6 +1971,9 @@ def unit(self) -> str:
         return dtype_to_unit(self.dtype)  # type: ignore[arg-type]
 
     def as_unit(self: TimelikeOpsT, unit: str) -> TimelikeOpsT:
+        if unit not in ["s", "ms", "us", "ns"]:
+            raise ValueError("Supported units are 's', 'ms', 'us', 'ns'")
+
         dtype = np.dtype(f"{self.dtype.kind}8[{unit}]")
         new_values = astype_overflowsafe(self._ndarray, dtype, round_ok=True)
 

pandas/core/indexes/datetimelike.py

@@ -396,6 +396,25 @@ class DatetimeTimedeltaMixin(DatetimeIndexOpsMixin):
 
     _join_precedence = 10
 
+    @property
+    def unit(self) -> str:
+        return self._data.unit
+
+    def as_unit(self: _TDT, unit: str) -> _TDT:
+        """
+        Convert to a dtype with the given unit resolution.
+
+        Parameters
+        ----------
+        unit : {'s', 'ms', 'us', 'ns'}
+
+        Returns
+        -------
+        same type as self
+        """
+        arr = self._data.as_unit(unit)
+        return type(self)._simple_new(arr, name=self.name)
+
     def _with_freq(self, freq):
         arr = self._data._with_freq(freq)
         return type(self)._simple_new(arr, name=self._name)

pandas/tests/arrays/test_timedeltas.py

@@ -29,6 +29,15 @@ def test_non_nano(self, unit):
         assert tda.dtype == arr.dtype
         assert tda[0].unit == unit
 
+    def test_as_unit_raises(self, tda):
+        # GH#50616
+        with pytest.raises(ValueError, match="Supported units"):
+            tda.as_unit("D")
+
+        tdi = pd.Index(tda)
+        with pytest.raises(ValueError, match="Supported units"):
+            tdi.as_unit("D")
+
     @pytest.mark.parametrize("field", TimedeltaArray._field_ops)
     def test_fields(self, tda, field):
         as_nano = tda._ndarray.astype("m8[ns]")

pandas/tests/indexes/datetimes/methods/test_snap.py

@@ -7,13 +7,6 @@
 import pandas._testing as tm
 
 
-def astype_non_nano(dti_nano, unit):
-    # TODO(2.0): remove once DTI supports as_unit
-    dta = dti_nano._data.as_unit(unit)
-    dti = DatetimeIndex(dta, name=dti_nano.name)
-    return dti
-
-
 @pytest.mark.parametrize("tz", [None, "Asia/Shanghai", "Europe/Berlin"])
 @pytest.mark.parametrize("name", [None, "my_dti"])
 @pytest.mark.parametrize("unit", ["ns", "us", "ms", "s"])
@@ -32,12 +25,12 @@ def test_dti_snap(name, tz, unit):
         tz=tz,
         freq="D",
     )
-    dti = astype_non_nano(dti, unit)
+    dti = dti.as_unit(unit)
 
     result = dti.snap(freq="W-MON")
     expected = date_range("12/31/2001", "1/7/2002", name=name, tz=tz, freq="w-mon")
     expected = expected.repeat([3, 4])
-    expected = astype_non_nano(expected, unit)
+    expected = expected.as_unit(unit)
     tm.assert_index_equal(result, expected)
     assert result.tz == expected.tz
     assert result.freq is None
@@ -47,7 +40,7 @@ def test_dti_snap(name, tz, unit):
 
     expected = date_range("1/1/2002", "1/7/2002", name=name, tz=tz, freq="b")
     expected = expected.repeat([1, 1, 1, 2, 2])
-    expected = astype_non_nano(expected, unit)
+    expected = expected.as_unit(unit)
     tm.assert_index_equal(result, expected)
     assert result.tz == expected.tz
     assert result.freq is None

pandas/tests/series/test_constructors.py

@@ -1587,9 +1587,8 @@ def test_convert_non_ns(self):
         ser = Series(arr)
         assert ser.dtype == arr.dtype
 
-        tdi = timedelta_range("00:00:01", periods=3, freq="s")
-        tda = tdi._data.as_unit("s")
-        expected = Series(tda)
+        tdi = timedelta_range("00:00:01", periods=3, freq="s").as_unit("s")
+        expected = Series(tdi)
         assert expected.dtype == arr.dtype
         tm.assert_series_equal(ser, expected)