Merge branch 'main' into concat_default_kwargs

Author: jsignell

.github/workflows/ci-additional.yaml

@@ -123,7 +123,7 @@ jobs:
           python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
 
       - name: Upload mypy coverage to Codecov
-        uses: codecov/[email protected].2
+        uses: codecov/[email protected].3
         with:
           file: mypy_report/cobertura.xml
           flags: mypy
@@ -174,7 +174,7 @@ jobs:
           python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
 
       - name: Upload mypy coverage to Codecov
-        uses: codecov/[email protected].2
+        uses: codecov/[email protected].3
         with:
           file: mypy_report/cobertura.xml
           flags: mypy-min
@@ -230,7 +230,7 @@ jobs:
           python -m pyright xarray/
 
       - name: Upload pyright coverage to Codecov
-        uses: codecov/[email protected].2
+        uses: codecov/[email protected].3
         with:
           file: pyright_report/cobertura.xml
           flags: pyright
@@ -286,7 +286,7 @@ jobs:
           python -m pyright xarray/
 
       - name: Upload pyright coverage to Codecov
-        uses: codecov/[email protected].2
+        uses: codecov/[email protected].3
         with:
           file: pyright_report/cobertura.xml
           flags: pyright39

.github/workflows/ci.yaml

@@ -172,7 +172,7 @@ jobs:
           path: pytest.xml
 
       - name: Upload code coverage to Codecov
-        uses: codecov/[email protected].2
+        uses: codecov/[email protected].3
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
         with:

.github/workflows/upstream-dev-ci.yaml

@@ -140,7 +140,7 @@ jobs:
         run: |
           python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
       - name: Upload mypy coverage to Codecov
-        uses: codecov/[email protected].2
+        uses: codecov/[email protected].3
         with:
           file: mypy_report/cobertura.xml
           flags: mypy

CONTRIBUTING.md

@@ -1 +1 @@
-Xarray's contributor guidelines [can be found in our online documentation](https://docs.xarray.dev/en/stable/contributing.html)
+Xarray's contributor guidelines [can be found in our online documentation](https://docs.xarray.dev/en/stable/contribute/contributing.html)

asv_bench/benchmarks/indexing.py

@@ -39,18 +39,30 @@
     "2d-1scalar": xr.DataArray(randn(100, frac_nan=0.1), dims=["x"]),
 }
 
-vectorized_indexes = {
-    "1-1d": {"x": xr.DataArray(randint(0, nx, 400), dims="a")},
-    "2-1d": {
-        "x": xr.DataArray(randint(0, nx, 400), dims="a"),
-        "y": xr.DataArray(randint(0, ny, 400), dims="a"),
-    },
-    "3-2d": {
-        "x": xr.DataArray(randint(0, nx, 400).reshape(4, 100), dims=["a", "b"]),
-        "y": xr.DataArray(randint(0, ny, 400).reshape(4, 100), dims=["a", "b"]),
-        "t": xr.DataArray(randint(0, nt, 400).reshape(4, 100), dims=["a", "b"]),
-    },
-}
+
+def make_vectorized_indexes(n_index):
+    return {
+        "1-1d": {"x": xr.DataArray(randint(0, nx, n_index), dims="a")},
+        "2-1d": {
+            "x": xr.DataArray(randint(0, nx, n_index), dims="a"),
+            "y": xr.DataArray(randint(0, ny, n_index), dims="a"),
+        },
+        "3-2d": {
+            "x": xr.DataArray(
+                randint(0, nx, n_index).reshape(n_index // 100, 100), dims=["a", "b"]
+            ),
+            "y": xr.DataArray(
+                randint(0, ny, n_index).reshape(n_index // 100, 100), dims=["a", "b"]
+            ),
+            "t": xr.DataArray(
+                randint(0, nt, n_index).reshape(n_index // 100, 100), dims=["a", "b"]
+            ),
+        },
+    }
+
+
+vectorized_indexes = make_vectorized_indexes(400)
+big_vectorized_indexes = make_vectorized_indexes(400_000)
 
 vectorized_assignment_values = {
     "1-1d": xr.DataArray(randn((400, ny)), dims=["a", "y"], coords={"a": randn(400)}),
@@ -101,6 +113,20 @@ def time_indexing_basic_ds_large(self, key):
         self.ds_large.isel(**basic_indexes[key]).load()
 
 
+class IndexingOnly(Base):
+    @parameterized(["key"], [list(basic_indexes.keys())])
+    def time_indexing_basic(self, key):
+        self.ds.isel(**basic_indexes[key])
+
+    @parameterized(["key"], [list(outer_indexes.keys())])
+    def time_indexing_outer(self, key):
+        self.ds.isel(**outer_indexes[key])
+
+    @parameterized(["key"], [list(big_vectorized_indexes.keys())])
+    def time_indexing_big_vectorized(self, key):
+        self.ds.isel(**big_vectorized_indexes[key])
+
+
 class Assignment(Base):
     @parameterized(["key"], [list(basic_indexes.keys())])
     def time_assignment_basic(self, key):

doc/user-guide/complex-numbers.rst

@@ -0,0 +1,124 @@
+.. currentmodule:: xarray
+
+.. _complex:
+
+Complex Numbers
+===============
+
+Xarray leverages NumPy to seamlessly handle complex numbers in :py:class:`~xarray.DataArray` and :py:class:`~xarray.Dataset` objects.
+
+In the examples below, we are using a DataArray named ``da`` with complex elements (of :math:`\mathbb{C}`):
+
+.. ipython:: python
+
+    import xarray as xr
+    import numpy as np
+
+    data = np.array([[1 + 2j, 3 + 4j], [5 + 6j, 7 + 8j]])
+    da = xr.DataArray(
+        data,
+        dims=["x", "y"],
+        coords={"x": ["a", "b"], "y": [1, 2]},
+        name="complex_nums",
+    )
+
+
+Operations on Complex Data
+--------------------------
+You can access real and imaginary components using the ``.real`` and ``.imag`` attributes. Most NumPy universal functions (ufuncs) like :py:doc:`numpy.abs <numpy:reference/generated/numpy.absolute>` or :py:doc:`numpy.angle <numpy:reference/generated/numpy.angle>` work directly.
+
+.. ipython:: python
+
+    da.real
+    np.abs(da)
+
+.. note::
+    Like NumPy, ``.real`` and ``.imag`` typically return *views*, not copies, of the original data.
+
+
+Reading and Writing Complex Data
+--------------------------------
+
+Writing complex data to NetCDF files (see :ref:`io.netcdf`) is supported via :py:meth:`~xarray.DataArray.to_netcdf` using specific backend engines that handle complex types:
+
+
+.. tab:: h5netcdf
+
+   This requires the `h5netcdf <https://h5netcdf.org>`_ library to be installed.
+
+   .. ipython:: python
+       :okwarning:
+
+       # write the data to disk
+       da.to_netcdf("complex_nums_h5.nc", engine="h5netcdf")
+       # read the file back into memory
+       ds_h5 = xr.open_dataset("complex_nums_h5.nc", engine="h5netcdf")
+       # check the dtype
+       ds_h5[da.name].dtype
+
+
+.. tab:: netcdf4
+
+   Requires the `netcdf4-python (>= 1.7.1) <https://github.com/Unidata/netcdf4-python>`_ library and you have to enable ``auto_complex=True``.
+
+   .. ipython:: python
+       :okwarning:
+
+       # write the data to disk
+       da.to_netcdf("complex_nums_nc4.nc", engine="netcdf4", auto_complex=True)
+       # read the file back into memory
+       ds_nc4 = xr.open_dataset(
+           "complex_nums_nc4.nc", engine="netcdf4", auto_complex=True
+       )
+       # check the dtype
+       ds_nc4[da.name].dtype
+
+
+.. warning::
+   The ``scipy`` engine only supports NetCDF V3 and does *not* support complex arrays; writing with ``engine="scipy"`` raises a ``TypeError``.
+
+
+Alternative: Manual Handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If direct writing is not supported (e.g., targeting NetCDF3), you can manually
+split the complex array into separate real and imaginary variables before saving:
+
+.. ipython:: python
+
+    # Write data to file
+    ds_manual = xr.Dataset(
+        {
+            f"{da.name}_real": da.real,
+            f"{da.name}_imag": da.imag,
+        }
+    )
+    ds_manual.to_netcdf("complex_manual.nc", engine="scipy")  # Example
+
+    # Read data from file
+    ds = xr.open_dataset("complex_manual.nc", engine="scipy")
+    reconstructed = ds[f"{da.name}_real"] + 1j * ds[f"{da.name}_imag"]
+
+Recommendations
+^^^^^^^^^^^^^^^
+
+- Use ``engine="netcdf4"`` with ``auto_complex=True`` for full compliance and ease.
+- Use ``h5netcdf`` for HDF5-based storage when interoperability with HDF5 is desired.
+- For maximum legacy support (NetCDF3), manually handle real/imaginary components.
+
+.. ipython:: python
+    :suppress:
+
+    # Cleanup
+    import os
+
+    for f in ["complex_nums_nc4.nc", "complex_nums_h5.nc", "complex_manual.nc"]:
+        if os.path.exists(f):
+            os.remove(f)
+
+
+
+See also
+--------
+- :ref:`io.netcdf` — full NetCDF I/O guide
+- `NumPy complex numbers <https://numpy.org/doc/stable/user/basics.types.html#complex>`__

doc/user-guide/index.rst

@@ -32,6 +32,7 @@ examples that describe many common tasks that you can accomplish with Xarray.
    :caption: I/O
 
    io
+   complex-numbers
 
 .. toctree::
    :maxdepth: 2

doc/whats-new.rst

@@ -24,12 +24,15 @@ v2025.05.0 (unreleased)
 
 New Features
 ~~~~~~~~~~~~
-
+- Allow an Xarray index that uses multiple dimensions checking equality with another
+  index for only a subset of those dimensions (i.e., ignoring the dimensions
+  that are excluded from alignment).
+  (:issue:`10243`, :pull:`10293`)
+  By `Benoit Bovy <https://github.com/benbovy>`_.
 
 Breaking changes
 ~~~~~~~~~~~~~~~~
 
-
 Deprecations
 ~~~~~~~~~~~~
 
@@ -47,9 +50,30 @@ Bug fixes
 ~~~~~~~~~
 - Fix :py:class:`~xarray.groupers.BinGrouper` when ``labels`` is not specified (:issue:`10284`).
   By `Deepak Cherian <https://github.com/dcherian>`_.
-
 - Allow accessing arbitrary attributes on Pandas ExtensionArrays.
   By `Deepak Cherian <https://github.com/dcherian>`_.
+- Fix coding empty (zero-size) timedelta64 arrays, ``units`` taking precedence when encoding,
+  fallback to default values when decoding (:issue:`10310`, :pull:`10313`).
+  By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
+- Use dtype from intermediate sum instead of source dtype or "int" for casting of count when
+  calculating mean in rolling for correct operations (preserve float dtypes,
+  correct mean of bool arrays) (:issue:`10340`, :pull:`10341`).
+  By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
+- Raise an error when attempting to encode :py:class:`numpy.datetime64` values
+  prior to the Gregorian calendar reform date of 1582-10-15 with a
+  ``"standard"`` or ``"gregorian"`` calendar. Previously we would warn and
+  encode these as :py:class:`cftime.DatetimeGregorian` objects, but it is not
+  clear that this is the user's intent, since this implicitly converts the
+  calendar of the datetimes from ``"proleptic_gregorian"`` to ``"gregorian"``
+  and prevents round-tripping them as :py:class:`numpy.datetime64` values
+  (:pull:`10352`). By `Spencer Clark <https://github.com/spencerkclark>`_.
+
+Performance
+~~~~~~~~~~~
+- Lazily indexed arrays now use less memory to store keys by avoiding copies
+  in :py:class:`~xarray.indexing.VectorizedIndexer` and :py:class:`~xarray.indexing.OuterIndexer`
+  (:issue:`10316`).
+  By `Jesse Rusak <https://github.com/jder>`_.
 
 
 Documentation
@@ -71,6 +95,15 @@ Alban Farchi, Andrecho, Benoit Bovy, Deepak Cherian, Dimitri Papadopoulos Orfano
 
 New Features
 ~~~~~~~~~~~~
+- By default xarray now encodes :py:class:`numpy.timedelta64` values by
+  converting to :py:class:`numpy.int64` values and storing ``"dtype"`` and
+  ``"units"`` attributes consistent with the dtype of the in-memory
+  :py:class:`numpy.timedelta64` values, e.g. ``"timedelta64[s]"`` and
+  ``"seconds"`` for second-resolution timedeltas. These values will always be
+  decoded to timedeltas without a warning moving forward. Timedeltas encoded
+  via the previous approach can still be roundtripped exactly, but in the
+  future will not be decoded by default (:issue:`1621`, :issue:`10099`,
+  :pull:`10101`). By `Spencer Clark <https://github.com/spencerkclark>`_.
 
 - Added `scipy-stubs <https://github.com/scipy/scipy-stubs>`_ to the ``xarray[types]`` dependencies.
   By `Joren Hammudoglu <https://github.com/jorenham>`_.
@@ -143,6 +176,9 @@ Documentation
 - Switch to `pydata-sphinx-theme <https://github.com/pydata/pydata-sphinx-theme>`_ from `sphinx-book-theme <https://github.com/executablebooks/sphinx-book-theme>`_ (:pull:`8708`).
   By `Scott Henderson <https://github.com/scottyhq>`_.
 
+- Add a dedicated 'Complex Numbers' sections to the User Guide (:issue:`10213`, :pull:`10235`).
+  By `Andre Wendlinger <https://github.com/andrewendlinger>`_.
+
 Internal Changes
 ~~~~~~~~~~~~~~~~
 - Avoid stacking when grouping by a chunked array. This can be a large performance improvement.

pyproject.toml

@@ -2,7 +2,6 @@
 authors = [{ name = "xarray Developers", email = "[email protected]" }]
 classifiers = [
   "Development Status :: 5 - Production/Stable",
-  "License :: OSI Approved :: Apache Software License",
   "Operating System :: OS Independent",
   "Intended Audience :: Science/Research",
   "Programming Language :: Python",
@@ -15,7 +14,7 @@ classifiers = [
 ]
 description = "N-D labeled arrays and datasets in Python"
 dynamic = ["version"]
-license = { text = "Apache-2.0" }
+license = "Apache-2.0"
 name = "xarray"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -94,8 +93,8 @@ dask = "xarray.namedarray.daskmanager:DaskManager"
 build-backend = "setuptools.build_meta"
 requires = ["setuptools>=42", "setuptools-scm>=7"]
 
-[tool.setuptools]
-packages = ["xarray"]
+[tool.setuptools.packages.find]
+include = ["xarray*"]
 
 [tool.setuptools_scm]
 fallback_version = "9999"