Time accessor (#64)

* added _get_axis_coord_alt for groupby(T.month)

* rename _alt to _time_accessor

* Update cf_xarray/tests/test_accessor.py

* ran black

* flake8

* Actually use mapper :)

* add _get_axis_coord_time_accessor to group

* rm "groupby_time_accessor" from test line 156

* Add whats-new

* Update example notebook

* fix whats-new entry

Author: jukent

cf_xarray/accessor.py

@@ -182,6 +182,36 @@ def _get_axis_coord_single(var: Union[DataArray, Dataset], key: str,) -> List[st
     return results
 
 
+def _get_axis_coord_time_accessor(var, key):
+    """
+    Helper method for when our key name is of the nature "T.month" and we want to
+    isolate the "T" for coordinate mapping
+
+    Parameters
+    ----------
+    var: DataArray, Dataset
+        DataArray belonging to the coordinate to be checked
+    key: str, ["X", "Y", "Z", "T", "longitude", "latitude", "vertical", "time"]
+        key to check for.
+
+    Returns
+    -------
+    List[str], Variable name(s) in parent xarray object that matches axis or coordinate `key` appended by the frequency extension (e.g. ".month")
+
+    Notes
+    -----
+    Returns an empty list if there is no frequency extension specified.
+    """
+    if "." in key:
+        key, ext = key.split(".", 1)
+
+        results = _get_axis_coord_single(var, key)
+        return [v + "." + ext for v in results]
+
+    else:
+        return []
+
+
 def _get_axis_coord(var: Union[DataArray, Dataset], key: str,) -> List[str]:
     """
     Translate from axis or coord name to variable name
@@ -308,7 +338,7 @@ def _get_measure(da: Union[DataArray, Dataset], key: str) -> List[str]:
     "dims_or_levels": (_get_axis_coord,),  # reset_index
     "window": (_get_axis_coord,),  # rolling_exp
     "coord": (_get_axis_coord_single,),  # differentiate, integrate
-    "group": (_get_axis_coord_single,),
+    "group": (_get_axis_coord_single, _get_axis_coord_time_accessor),
     "indexer": (_get_axis_coord_single,),  # resample
     "variables": (_get_axis_coord,),  # sortby
     "weights": (_get_measure_variable,),  # type: ignore

cf_xarray/tests/test_accessor.py

@@ -126,6 +126,7 @@ def test_rename_like():
         ("resample", {"time": "M"}, {"T": "M"}),
         ("rolling", {"lat": 5}, {"Y": 5}),
         ("groupby", {"group": "time"}, {"group": "T"}),
+        ("groupby", {"group": "time.month"}, {"group": "T.month"}),
         ("groupby_bins", {"group": "lat", "bins": 5}, {"group": "latitude", "bins": 5}),
         pytest.param(
             "coarsen",

doc/examples/introduction.ipynb

@@ -14,8 +14,8 @@
    "execution_count": null,
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2020-07-24T20:12:00.609657Z",
-     "start_time": "2020-07-24T20:11:59.698753Z"
+     "end_time": "2020-07-27T23:20:40.515653Z",
+     "start_time": "2020-07-27T23:20:39.578412Z"
     }
    },
    "outputs": [],
@@ -37,8 +37,8 @@
    "execution_count": null,
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2020-07-24T20:12:00.805176Z",
-     "start_time": "2020-07-24T20:12:00.718615Z"
+     "end_time": "2020-07-27T23:20:41.803595Z",
+     "start_time": "2020-07-27T23:20:41.713269Z"
     }
    },
    "outputs": [],
@@ -718,18 +718,25 @@
     "ds.cf.resample(T=\"D\").mean()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`cf_xarray` also understands the \"datetime accessor\" syntax for groupby\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2020-06-30T23:25:33.106698Z",
-     "start_time": "2020-06-30T23:25:33.037746Z"
+     "end_time": "2020-07-27T23:21:24.092199Z",
+     "start_time": "2020-07-27T23:21:24.025943Z"
     }
    },
    "outputs": [],
    "source": [
-    "ds.cf.groupby(\"time.month\").mean(\"longitude\")"
+    "ds.cf.groupby(\"T.month\").mean(\"longitude\")"
    ]
   },
   {
@@ -780,13 +787,13 @@
    "execution_count": null,
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2020-06-30T23:25:33.212324Z",
-     "start_time": "2020-06-30T23:25:33.164373Z"
+     "end_time": "2020-07-27T23:20:59.326974Z",
+     "start_time": "2020-07-27T23:20:59.261728Z"
     }
    },
    "outputs": [],
    "source": [
-    "ds.cf.groupby(\"time.month\").mean([\"lat\", \"X\"])"
+    "ds.cf.groupby(\"T.month\").mean([\"lat\", \"X\"])"
    ]
   },
   {
@@ -853,7 +860,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.6"
+   "version": "3.7.8"
   },
   "toc": {
    "base_numbering": 1,

doc/whats-new.rst

@@ -4,6 +4,8 @@ What's New
 v0.1.6 (unreleased)
 ===================
 
+- Remap datetime accessor syntax for groupby. E.g. ``.cf.groupby("T.month")`` → ``.cf.groupby("ocean_time.month")``.
+  (:pr:`64`, :issue:`6`). `Julia Kent`_.
 - Added ``.cf.rename_like`` to rename matching variables. Only coordinate variables
   i.e. those that match the criteria for ``("latitude", "longitude", "vertical", "time")``
   are renamed for now. (:pr:`55`) `Deepak Cherian`_.
@@ -32,3 +34,4 @@ v0.1.3
 - Support expanding key to multiple dimension names.
 
 .. _`Deepak Cherian`: https://github.com/dcherian
+.. _`Julia Kent`: https://github.com/jukent