From 1a7d6de3074e5e91abc4f7e842ac89528b48501e Mon Sep 17 00:00:00 2001 From: Michael Niklas Date: Thu, 22 Oct 2026 09:41:23 +0200 Subject: [PATCH 1/3] Document how interp handles Dask chunks Co-authored-by: Claude --- doc/user-guide/interpolation.md | 19 +++++++++++++++++++ doc/whats-new.rst | 5 +++++ xarray/core/dataarray.py | 6 ++++++ xarray/core/dataset.py | 6 ++++++ 4 files changed, 36 insertions(+) diff --git a/doc/user-guide/interpolation.md b/doc/user-guide/interpolation.md index ff9e778547d..db711b4ec74 100644 --- a/doc/user-guide/interpolation.md +++ b/doc/user-guide/interpolation.md @@ -295,6 +295,25 @@ filled.interp(x=[0.5, 1.5, 2.5], method="cubic") For the details of {py:meth}`~xarray.DataArray.interpolate_na`, see {ref}`Missing values `. +(interp.dask)= + +## Interpolating Dask arrays + +{py:meth}`~xarray.DataArray.interp` works lazily on {ref}`Dask arrays `. +Each task needs the full extent of the dimensions being interpolated along, +so the chunks along these dimensions are merged into a single chunk. + +With `method="linear"` or `"nearest"`, the data is first subset to the range +of the new coordinates, so only the chunks that are needed are read. This +requires the new coordinates to be in memory: if they are chunked, xarray does +not compute them in advance, so all chunks along the interpolated dimensions +are read and merged. If the new coordinates are cheap to compute, loading them +first can reduce the memory use considerably: + +```python +da.interp(x=new_x.compute()) +``` + ## Example Let's see how {py:meth}`~xarray.DataArray.interp` works on real data. diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 3abeff78a77..4a8fa5a3a71 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -349,6 +349,11 @@ Bug Fixes Documentation ~~~~~~~~~~~~~ +- Document how :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp` handle + chunks of Dask arrays, and that loading chunked new coordinates first can + reduce the memory use for ``method="linear"`` and ``"nearest"`` + (:pull:`XXXXX`). + By `Michael Niklas `_. - Add hidden intersphinx inventory entries for methods, properties and attributes at the path where they are defined, e.g. ``xarray.core.dataarray.DataArray.sel``. This lets tools such as diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 202924b5b8a..d4d6a4d7fce 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -2436,6 +2436,12 @@ def interp( - When interpolating along multiple dimensions with methods `linear` and `nearest`, the process attempts to decompose the interpolation into independent interpolations along one dimension at a time. + - For Dask arrays, the chunks along the interpolated dimensions are merged + into a single chunk. With methods `linear` and `nearest`, the data is + first subset to the range of the new coordinates, so only the chunks that + are needed are read. This only happens if the new coordinates are in + memory, so load chunked new coordinates first (e.g. with ``.compute()``) + if they are cheap to compute. See :ref:`interp.dask`. - The specific interpolation method and dimensionality determine which interpolant is used: diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 7976a8b5f62..18246ca61ac 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -3902,6 +3902,12 @@ def interp( - When interpolating along multiple dimensions with methods `linear` and `nearest`, the process attempts to decompose the interpolation into independent interpolations along one dimension at a time. + - For Dask arrays, the chunks along the interpolated dimensions are merged + into a single chunk. With methods `linear` and `nearest`, the data is + first subset to the range of the new coordinates, so only the chunks that + are needed are read. This only happens if the new coordinates are in + memory, so load chunked new coordinates first (e.g. with ``.compute()``) + if they are cheap to compute. See :ref:`interp.dask`. - The specific interpolation method and dimensionality determine which interpolant is used: From caed74ba21fcbf77f7d5e248fa754269510a5639 Mon Sep 17 00:00:00 2001 From: Michael Niklas Date: Thu, 22 Oct 2026 09:43:30 +0200 Subject: [PATCH 2/3] Add PR number to whats-new Co-authored-by: Claude --- doc/whats-new.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 4a8fa5a3a71..6fdf85ff01b 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -352,7 +352,7 @@ Documentation - Document how :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp` handle chunks of Dask arrays, and that loading chunked new coordinates first can reduce the memory use for ``method="linear"`` and ``"nearest"`` - (:pull:`XXXXX`). + (:pull:`11786`). By `Michael Niklas `_. - Add hidden intersphinx inventory entries for methods, properties and attributes at the path where they are defined, e.g. From 2a51068fb926f312c9bb879076c2a668320abadb Mon Sep 17 00:00:00 2001 From: Michael Niklas Date: Mon, 26 Oct 2026 13:45:53 +0100 Subject: [PATCH 3/3] Keep the interp Dask notes in the docstrings only Co-Authored-By: Claude Opus 5.5 --- doc/user-guide/interpolation.md | 19 ------------------- xarray/core/dataarray.py | 4 ++-- xarray/core/dataset.py | 4 ++-- 3 files changed, 4 insertions(+), 23 deletions(-) diff --git a/doc/user-guide/interpolation.md b/doc/user-guide/interpolation.md index db711b4ec74..ff9e778547d 100644 --- a/doc/user-guide/interpolation.md +++ b/doc/user-guide/interpolation.md @@ -295,25 +295,6 @@ filled.interp(x=[0.5, 1.5, 2.5], method="cubic") For the details of {py:meth}`~xarray.DataArray.interpolate_na`, see {ref}`Missing values `. -(interp.dask)= - -## Interpolating Dask arrays - -{py:meth}`~xarray.DataArray.interp` works lazily on {ref}`Dask arrays `. -Each task needs the full extent of the dimensions being interpolated along, -so the chunks along these dimensions are merged into a single chunk. - -With `method="linear"` or `"nearest"`, the data is first subset to the range -of the new coordinates, so only the chunks that are needed are read. This -requires the new coordinates to be in memory: if they are chunked, xarray does -not compute them in advance, so all chunks along the interpolated dimensions -are read and merged. If the new coordinates are cheap to compute, loading them -first can reduce the memory use considerably: - -```python -da.interp(x=new_x.compute()) -``` - ## Example Let's see how {py:meth}`~xarray.DataArray.interp` works on real data. diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index d4d6a4d7fce..c3e6d0a3b9e 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -2440,8 +2440,8 @@ def interp( into a single chunk. With methods `linear` and `nearest`, the data is first subset to the range of the new coordinates, so only the chunks that are needed are read. This only happens if the new coordinates are in - memory, so load chunked new coordinates first (e.g. with ``.compute()``) - if they are cheap to compute. See :ref:`interp.dask`. + memory, so loading chunked new coordinates first (e.g. with ``.compute()``) + can reduce the memory use considerably if they are cheap to compute. - The specific interpolation method and dimensionality determine which interpolant is used: diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 18246ca61ac..d61835b2b21 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -3906,8 +3906,8 @@ def interp( into a single chunk. With methods `linear` and `nearest`, the data is first subset to the range of the new coordinates, so only the chunks that are needed are read. This only happens if the new coordinates are in - memory, so load chunked new coordinates first (e.g. with ``.compute()``) - if they are cheap to compute. See :ref:`interp.dask`. + memory, so loading chunked new coordinates first (e.g. with ``.compute()``) + can reduce the memory use considerably if they are cheap to compute. - The specific interpolation method and dimensionality determine which interpolant is used: