Allow mean with time dtypes (#10227)

* Allow `mean` with time dtypes

Closes #5897
Closes #6995
Closes #10217

* Allow mean() to work with datetime dtypes

- Changed numeric_only from True to False in mean() aggregations
- Added Dataset.mean() override to filter out string variables while preserving datetime/timedelta types
- Only filters data variables, preserves all coordinates
- Added comprehensive tests for datetime mean with edge cases including NaT handling
- Tests cover Dataset, DataArray, groupby, and mixed type scenarios

This enables mean() to work with datetime64 and timedelta64 types as requested in PR #10227 while preventing errors from string variables.

* Skip cftime test when cftime not available

Add pytest.mark.skipif decorator to test_mean_preserves_non_string_object_arrays
to skip the test in minimal dependency environments where cftime is not installed.

* Fix string/datetime handling in mean() aggregations

- Revert numeric_only back to True for mean() to prevent strings from being included
- Add datetime64/timedelta64 types to numeric_only checks in Dataset.reduce() and flox path
- Also check for object arrays containing datetime-like objects (cftime dates)
- This allows mean() to work with datetime types while excluding strings that would cause errors

* Trigger CI workflow

* Format groupby.py numeric_only condition

Auto-formatted the multi-line condition for better readability

* Apply formatting changes to dataset.py and test_groupby.py

- Auto-formatted multi-line conditions for better readability

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix numeric_only parameter in groupby mean for non-flox path

The generated mean() methods for DatasetGroupBy and ResampleGroupBy
were incorrectly passing numeric_only=False in the non-flox path,
causing string variables to fail during reduction. Changed to
numeric_only=True to match the flox path behavior.

This fixes test_groupby_dataset_reduce_ellipsis failures.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Simplify dtype checking with _is_numeric_aggregatable_dtype helper

Created a canonical helper function to check if a dtype can be used in
numeric aggregations. This replaces complex repeated conditionals in
dataset.py and groupby.py with a single, well-documented function.

The helper checks for:
- Numeric types (int, float, complex)
- Boolean type
- Datetime types (datetime64, timedelta64)
- Object arrays containing datetime-like objects (e.g., cftime)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Address review feedback from @dcherian

- Document datetime mean behavior in generate_aggregations.py
- Simplify test assertion using isnull().item() instead of pd.notna
- Remove redundant test_mean_dataarray_datetime test
- Add comprehensive tests for linked issues:
  - Issue #5897: Test mean with cftime objects
  - Issue #6995: Test groupby_bins with datetime64 mean
  - Issue #10217: Test groupby_bins mean on time series data

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix test_mean_with_cftime_objects for non-dask environments

The test was unconditionally using dask operations which caused failures
in the "all-but-dask" CI environment. Now the dask-specific tests are
only run when dask is available.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Use standard @requires_dask decorator for dask-specific tests

Split test_mean_with_cftime_objects into two tests:
- Base test runs without dask
- Dask-specific test uses @requires_dask decorator

This follows xarray's standard pattern for dependency-specific tests
and is cleaner than using if has_dask conditionals.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add testing guidelines and use proper decorators

- Created xarray/tests/CLAUDE.md with comprehensive guidelines for
  handling optional dependencies in tests
- Updated cftime tests to use @requires_cftime decorator instead of
  pytest.importorskip, following xarray's standard patterns
- This ensures consistent handling across CI environments

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix CLAUDE.md blackdoc formatting

Ensure all Python code blocks have complete, valid syntax for blackdoc.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Simplify cftime check in _is_numeric_aggregatable_dtype

As suggested by @dcherian in review comment r2337966239, directly use
_contains_cftime_datetimes(var._data) instead of the more complex check.
This is cleaner since _contains_cftime_datetimes already handles the
object dtype check internally.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Streamline CLAUDE.md and move import to top of file

- Made CLAUDE.md more concise by removing verbose decorator listings
- Moved _is_numeric_aggregatable_dtype import to top of groupby.py
  as suggested by @dcherian in review comment r2337968851

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Address review comments: clarify numeric_only scope and merge tests

- Move datetime/timedelta note to global _NUMERIC_ONLY_NOTES constant
  (addresses comment r2337970143)
- Merge test_mean_preserves_non_string_object_arrays into
  test_mean_with_cftime_objects (addresses comment r2337128692)
- Both changes address reviewer feedback about simplification

* Clarify that @requires decorators should be used instead of skipif patterns

Update testing guidelines to explicitly discourage pytest.mark.skipif
in parametrize, recommending splitting tests or using @requires decorators

* Fix CLAUDE.md blackdoc formatting

Co-authored-by: Claude <no-reply@anthropic.com>

---------

Co-authored-by: Maximilian Roos <m@maxroos.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Claude <no-reply@anthropic.com>

Author: 5 people

xarray/core/_aggregations.py

@@ -1776,10 +1776,6 @@ def mean(
         :ref:`agg`
             User guide on reduction or aggregation operations.
 
-        Notes
-        -----
-        Non-numeric variables will be removed prior to reducing.
-
         Examples
         --------
         >>> da = xr.DataArray(
@@ -2948,10 +2944,6 @@ def mean(
         :ref:`agg`
             User guide on reduction or aggregation operations.
 
-        Notes
-        -----
-        Non-numeric variables will be removed prior to reducing.
-
         Examples
         --------
         >>> da = xr.DataArray(
@@ -4231,8 +4223,6 @@ def mean(
         Pass flox-specific keyword arguments in ``**kwargs``.
         See the `flox documentation <https://flox.readthedocs.io>`_ for more.
 
-        Non-numeric variables will be removed prior to reducing.
-
         Examples
         --------
         >>> da = xr.DataArray(
@@ -5729,8 +5719,6 @@ def mean(
         Pass flox-specific keyword arguments in ``**kwargs``.
         See the `flox documentation <https://flox.readthedocs.io>`_ for more.
 
-        Non-numeric variables will be removed prior to reducing.
-
         Examples
         --------
         >>> da = xr.DataArray(
@@ -7188,8 +7176,6 @@ def mean(
         Pass flox-specific keyword arguments in ``**kwargs``.
         See the `flox documentation <https://flox.readthedocs.io>`_ for more.
 
-        Non-numeric variables will be removed prior to reducing.
-
         Examples
         --------
         >>> da = xr.DataArray(
@@ -8578,8 +8564,6 @@ def mean(
         Pass flox-specific keyword arguments in ``**kwargs``.
         See the `flox documentation <https://flox.readthedocs.io>`_ for more.
 
-        Non-numeric variables will be removed prior to reducing.
-
         Examples
         --------
         >>> da = xr.DataArray(

xarray/core/common.py

@@ -2108,3 +2108,21 @@ def _contains_datetime_like_objects(var: T_Variable) -> bool:
     np.datetime64, np.timedelta64, or cftime.datetime)
     """
     return is_np_datetime_like(var.dtype) or contains_cftime_datetimes(var)
+
+
+def _is_numeric_aggregatable_dtype(var: T_Variable) -> bool:
+    """Check if a variable's dtype can be used in numeric aggregations like mean().
+
+    This includes:
+    - Numeric types (int, float, complex)
+    - Boolean type
+    - Datetime types (datetime64, timedelta64)
+    - Object arrays containing datetime-like objects (e.g., cftime)
+    """
+    return (
+        np.issubdtype(var.dtype, np.number)
+        or (var.dtype == np.bool_)
+        or np.issubdtype(var.dtype, np.datetime64)
+        or np.issubdtype(var.dtype, np.timedelta64)
+        or _contains_cftime_datetimes(var._data)
+    )

xarray/core/dataset.py

@@ -40,6 +40,7 @@
 from xarray.core.common import (
     DataWithCoords,
     _contains_datetime_like_objects,
+    _is_numeric_aggregatable_dtype,
     get_chunksizes,
 )
 from xarray.core.coordinates import (
@@ -6847,8 +6848,7 @@ def reduce(
                 and (
                     not reduce_dims
                     or not numeric_only
-                    or np.issubdtype(var.dtype, np.number)
-                    or (var.dtype == np.bool_)
+                    or _is_numeric_aggregatable_dtype(var)
                 )
             ):
                 # prefer to aggregate over axis=None rather than

xarray/core/groupby.py

@@ -22,7 +22,11 @@
     DataArrayGroupByAggregations,
     DatasetGroupByAggregations,
 )
-from xarray.core.common import ImplementsArrayReduce, ImplementsDatasetReduce
+from xarray.core.common import (
+    ImplementsArrayReduce,
+    ImplementsDatasetReduce,
+    _is_numeric_aggregatable_dtype,
+)
 from xarray.core.coordinates import Coordinates, coordinates_from_variable
 from xarray.core.duck_array_ops import where
 from xarray.core.formatting import format_array_flat
@@ -1068,7 +1072,7 @@ def _flox_reduce(
                 name: var
                 for name, var in variables.items()
                 if (
-                    not (np.issubdtype(var.dtype, np.number) or (var.dtype == np.bool_))
+                    not _is_numeric_aggregatable_dtype(var)
                     # this avoids dropping any levels of a MultiIndex, which raises
                     # a warning
                     and name not in midx_grouping_vars

xarray/namedarray/_aggregations.py

@@ -352,10 +352,6 @@ def mean(
         :ref:`agg`
             User guide on reduction or aggregation operations.
 
-        Notes
-        -----
-        Non-numeric variables will be removed prior to reducing.
-
         Examples
         --------
         >>> from xarray.namedarray.core import NamedArray

xarray/tests/CLAUDE.md

@@ -0,0 +1,132 @@
+# Testing Guidelines for xarray
+
+## Handling Optional Dependencies
+
+xarray has many optional dependencies that may not be available in all testing environments. Always use the standard decorators and patterns when writing tests that require specific dependencies.
+
+### Standard Decorators
+
+**ALWAYS use decorators** like `@requires_dask`, `@requires_cftime`, etc. instead of conditional `if` statements.
+
+All available decorators are defined in `xarray/tests/__init__.py` (look for `requires_*` decorators).
+
+### DO NOT use conditional imports or skipif
+
+❌ **WRONG - Do not do this:**
+
+```python
+def test_mean_with_cftime():
+    if has_dask:  # WRONG!
+        ds = ds.chunk({})
+        result = ds.mean()
+```
+
+❌ **ALSO WRONG - Avoid pytest.mark.skipif in parametrize:**
+
+```python
+@pytest.mark.parametrize(
+    "chunk",
+    [
+        pytest.param(
+            True, marks=pytest.mark.skipif(not has_dask, reason="requires dask")
+        ),
+        False,
+    ],
+)
+def test_something(chunk): ...
+```
+
+✅ **CORRECT - Do this instead:**
+
+```python
+def test_mean_with_cftime():
+    # Test without dask
+    result = ds.mean()
+
+
+@requires_dask
+def test_mean_with_cftime_dask():
+    # Separate test for dask functionality
+    ds = ds.chunk({})
+    result = ds.mean()
+```
+
+✅ **OR for parametrized tests, split them:**
+
+```python
+def test_something_without_dask():
+    # Test the False case
+    ...
+
+
+@requires_dask
+def test_something_with_dask():
+    # Test the True case with dask
+    ...
+```
+
+### Multiple dependencies
+
+When a test requires multiple optional dependencies:
+
+```python
+@requires_dask
+@requires_scipy
+def test_interpolation_with_dask(): ...
+```
+
+### Importing optional dependencies in tests
+
+For imports within test functions, use `pytest.importorskip`:
+
+```python
+def test_cftime_functionality():
+    cftime = pytest.importorskip("cftime")
+    # Now use cftime
+```
+
+### Common patterns
+
+1. **Split tests by dependency** - Don't mix optional dependency code with base functionality:
+
+   ```python
+   def test_base_functionality():
+       # Core test without optional deps
+       result = ds.mean()
+       assert result is not None
+
+
+   @requires_dask
+   def test_dask_functionality():
+       # Dask-specific test
+       ds_chunked = ds.chunk({})
+       result = ds_chunked.mean()
+       assert result is not None
+   ```
+
+2. **Use fixtures for dependency-specific setup**:
+
+   ```python
+   @pytest.fixture
+   def dask_array():
+       pytest.importorskip("dask.array")
+       import dask.array as da
+
+       return da.from_array([1, 2, 3], chunks=2)
+   ```
+
+3. **Check available implementations**:
+
+   ```python
+   from xarray.core.duck_array_ops import available_implementations
+
+
+   @pytest.mark.parametrize("implementation", available_implementations())
+   def test_with_available_backends(implementation): ...
+   ```
+
+### Key Points
+
+- CI environments intentionally exclude certain dependencies (e.g., `all-but-dask`, `bare-minimum`)
+- A test failing in "all-but-dask" because it uses dask is a test bug, not a CI issue
+- Look at similar existing tests for patterns to follow