add freq as CFTimeIndex property and to CFTimeIndex.__repr__ (#4597)

* add freq as property and to repr

* lint

* Update test_cftimeindex.py

* Update test_cftimeindex.py

* require cftime110

* Only show freq if more than two items

* Update test_cftimeindex.py

* Update cftime_offsets.py

* Require cftime110 for all repr tests

* Update test_cftimeindex.py

* Update xarray/tests/test_cftimeindex.py

* Update test_cftimeindex.py

* Update xarray/tests/test_cftimeindex.py

* final lint

* freq in repr always and add to hidden-api

* fix doctests by adding freq=None

* rerun CI after timeout

* api-hidden

* rerun CI

Author: aaronspring

doc/api-hidden.rst

@@ -689,6 +689,7 @@
    CFTimeIndex.dayofyear
    CFTimeIndex.dtype
    CFTimeIndex.empty
+   CFTimeIndex.freq
    CFTimeIndex.has_duplicates
    CFTimeIndex.hasnans
    CFTimeIndex.hour

doc/whats-new.rst

@@ -55,6 +55,9 @@ New Features
   By `Julius Busecke <https://github.com/jbusecke>`_.
 - Added the ``keep_attrs`` keyword to ``rolling_exp.mean()``; it now keeps attributes
   per default. By `Mathias Hauser <https://github.com/mathause>`_ (:pull:`4592`).
+- Added ``freq`` as property to :py:class:`CFTimeIndex` and into the
+  ``CFTimeIndex.repr``. (:issue:`2416`, :pull:`4597`)
+  By `Aaron Spring <https://github.com/aaronspring>`_.
 
 Bug fixes
 ~~~~~~~~~

xarray/coding/cftime_offsets.py

@@ -939,7 +939,7 @@ def cftime_range(
     >>> xr.cftime_range(start="2000", periods=6, freq="2MS", calendar="noleap")
     CFTimeIndex([2000-01-01 00:00:00, 2000-03-01 00:00:00, 2000-05-01 00:00:00,
                  2000-07-01 00:00:00, 2000-09-01 00:00:00, 2000-11-01 00:00:00],
-                dtype='object', length=6, calendar='noleap')
+                dtype='object', length=6, calendar='noleap', freq='2MS')
 
     As in the standard pandas function, three of the ``start``, ``end``,
     ``periods``, or ``freq`` arguments must be specified at a given time, with

xarray/coding/cftimeindex.py

@@ -261,6 +261,7 @@ def format_attrs(index, separator=", "):
         "length": f"{len(index)}",
         "calendar": f"'{index.calendar}'",
     }
+    attrs["freq"] = f"'{index.freq}'" if len(index) >= 3 else None
     attrs_str = [f"{k}={v}" for k, v in attrs.items()]
     attrs_str = f"{separator}".join(attrs_str)
     return attrs_str
@@ -524,10 +525,10 @@ def shift(self, n, freq):
         >>> index = xr.cftime_range("2000", periods=1, freq="M")
         >>> index
         CFTimeIndex([2000-01-31 00:00:00],
-                    dtype='object', length=1, calendar='gregorian')
+                    dtype='object', length=1, calendar='gregorian', freq=None)
         >>> index.shift(1, "M")
         CFTimeIndex([2000-02-29 00:00:00],
-                    dtype='object', length=1, calendar='gregorian')
+                    dtype='object', length=1, calendar='gregorian', freq=None)
         """
         from .cftime_offsets import to_offset
 
@@ -614,7 +615,7 @@ def to_datetimeindex(self, unsafe=False):
         >>> times = xr.cftime_range("2000", periods=2, calendar="gregorian")
         >>> times
         CFTimeIndex([2000-01-01 00:00:00, 2000-01-02 00:00:00],
-                    dtype='object', length=2, calendar='gregorian')
+                    dtype='object', length=2, calendar='gregorian', freq=None)
         >>> times.to_datetimeindex()
         DatetimeIndex(['2000-01-01', '2000-01-02'], dtype='datetime64[ns]', freq=None)
         """
@@ -683,6 +684,13 @@ def calendar(self):
 
         return infer_calendar_name(self)
 
+    @property
+    def freq(self):
+        """The frequency used by the dates in the index."""
+        from .frequencies import infer_freq
+
+        return infer_freq(self)
+
     def _round_via_method(self, freq, method):
         """Round dates using a specified method."""
         from .cftime_offsets import CFTIME_TICKS, to_offset

xarray/tests/test_cftimeindex.py

@@ -916,7 +916,7 @@ def test_cftimeindex_calendar_property(calendar, expected):
     assert index.calendar == expected
 
 
-@requires_cftime
+@requires_cftime_1_1_0
 @pytest.mark.parametrize(
     ("calendar", "expected"),
     [
@@ -936,7 +936,7 @@ def test_cftimeindex_calendar_repr(calendar, expected):
     assert "2000-01-01 00:00:00, 2000-01-02 00:00:00" in repr_str
 
 
-@requires_cftime
+@requires_cftime_1_1_0
 @pytest.mark.parametrize("periods", [2, 40])
 def test_cftimeindex_periods_repr(periods):
     """Test that cftimeindex has periods property in repr."""
@@ -945,22 +945,32 @@ def test_cftimeindex_periods_repr(periods):
     assert f" length={periods}" in repr_str
 
 
-@requires_cftime
+@requires_cftime_1_1_0
+@pytest.mark.parametrize("calendar", ["noleap", "360_day", "standard"])
+@pytest.mark.parametrize("freq", ["D", "H"])
+def test_cftimeindex_freq_in_repr(freq, calendar):
+    """Test that cftimeindex has frequency property in repr."""
+    index = xr.cftime_range(start="2000", periods=3, freq=freq, calendar=calendar)
+    repr_str = index.__repr__()
+    assert f", freq='{freq}'" in repr_str
+
+
+@requires_cftime_1_1_0
 @pytest.mark.parametrize(
     "periods,expected",
     [
         (
             2,
             """\
 CFTimeIndex([2000-01-01 00:00:00, 2000-01-02 00:00:00],
-            dtype='object', length=2, calendar='gregorian')""",
+            dtype='object', length=2, calendar='gregorian', freq=None)""",
         ),
         (
             4,
             """\
 CFTimeIndex([2000-01-01 00:00:00, 2000-01-02 00:00:00, 2000-01-03 00:00:00,
              2000-01-04 00:00:00],
-            dtype='object', length=4, calendar='gregorian')""",
+            dtype='object', length=4, calendar='gregorian', freq='D')""",
         ),
         (
             101,
@@ -974,18 +984,18 @@ def test_cftimeindex_periods_repr(periods):
              2000-04-04 00:00:00, 2000-04-05 00:00:00, 2000-04-06 00:00:00,
              2000-04-07 00:00:00, 2000-04-08 00:00:00, 2000-04-09 00:00:00,
              2000-04-10 00:00:00],
-            dtype='object', length=101, calendar='gregorian')""",
+            dtype='object', length=101, calendar='gregorian', freq='D')""",
         ),
     ],
 )
 def test_cftimeindex_repr_formatting(periods, expected):
     """Test that cftimeindex.__repr__ is formatted similar to pd.Index.__repr__."""
-    index = xr.cftime_range(start="2000", periods=periods)
+    index = xr.cftime_range(start="2000", periods=periods, freq="D")
     expected = dedent(expected)
     assert expected == repr(index)
 
 
-@requires_cftime
+@requires_cftime_1_1_0
 @pytest.mark.parametrize("display_width", [40, 80, 100])
 @pytest.mark.parametrize("periods", [2, 3, 4, 100, 101])
 def test_cftimeindex_repr_formatting_width(periods, display_width):
@@ -1003,7 +1013,7 @@ def test_cftimeindex_repr_formatting_width(periods, display_width):
                 assert s[:len_intro_str] == " " * len_intro_str
 
 
-@requires_cftime
+@requires_cftime_1_1_0
 @pytest.mark.parametrize("periods", [22, 50, 100])
 def test_cftimeindex_repr_101_shorter(periods):
     index_101 = xr.cftime_range(start="2000", periods=101)