From 8a7016e57db233d0a232479893a90dc1b04048c2 Mon Sep 17 00:00:00 2001 From: Kevin Schwarzwald Date: Tue, 13 Feb 2024 11:08:01 -0500 Subject: [PATCH 1/4] Clarify pydata#8728 in docs - Add reference to numpy docs on view / copies in the corresponding section of the xarray docs, to help clarify pydata#8728 . - Add note that `da.values()` returns a view in the header for `da.values()`. --- doc/user-guide/indexing.rst | 6 ++++-- xarray/core/dataarray.py | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/user-guide/indexing.rst b/doc/user-guide/indexing.rst index 90b7cbaf2a9..4882403342f 100644 --- a/doc/user-guide/indexing.rst +++ b/doc/user-guide/indexing.rst @@ -747,7 +747,7 @@ Whether array indexing returns a view or a copy of the underlying data depends on the nature of the labels. For positional (integer) -indexing, xarray follows the same rules as NumPy: +indexing, xarray follows the same `rules`_ as NumPy: * Positional indexing with only integers and slices returns a view. * Positional indexing with arrays or lists returns a copy. @@ -764,8 +764,10 @@ Whether data is a copy or a view is more predictable in xarray than in pandas, s unlike pandas, xarray does not produce `SettingWithCopy warnings`_. However, you should still avoid assignment with chained indexing. -.. _SettingWithCopy warnings: https://pandas.pydata.org/pandas-docs/stable/indexing.html#returning-a-view-versus-a-copy +Note that other operations (such as :py:meth:`~xarray.DataArray.values`) may also return views rather than copies. +.. _SettingWithCopy warnings: https://pandas.pydata.org/pandas-docs/stable/indexing.html#returning-a-view-versus-a-copy +.. _rules: https://numpy.org/doc/stable/user/basics.copies.html .. _multi-level indexing: diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index c00fe1a9e67..4bbefa0e8e7 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -761,7 +761,7 @@ def data(self, value: Any) -> None: @property def values(self) -> np.ndarray: """ - The array's data as a numpy.ndarray. + A view onto the DataArray's underlying data as a numpy.ndarray. If the array's data is not a numpy.ndarray this will attempt to convert it naively using np.array(), which will raise an error if the array From 347647571df3db36461dadca1e0711de9dcaa2f5 Mon Sep 17 00:00:00 2001 From: Kevin Schwarzwald Date: Mon, 26 Feb 2024 15:14:27 -0500 Subject: [PATCH 2/4] tweaks to the header --- xarray/core/dataarray.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 4bbefa0e8e7..a3256c4830e 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -761,11 +761,15 @@ def data(self, value: Any) -> None: @property def values(self) -> np.ndarray: """ - A view onto the DataArray's underlying data as a numpy.ndarray. + The array's data converted to numpy.ndarray. - If the array's data is not a numpy.ndarray this will attempt to convert - it naively using np.array(), which will raise an error if the array - type does not support coercion like this (e.g. cupy). + Note that this array is not copied; operations on it follow + numpy's rules of what generates a view vs. a copy, and changes + to this array may be reflected in the DataArray as well. + + This will attempt to convert the array naively using np.array(), + which will raise an error if the array type does not support + coercion like this (e.g. cupy). """ return self.variable.values From 81adbbe442b6df60544b897e9bf824181551f809 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 26 Feb 2024 20:17:21 +0000 Subject: [PATCH 3/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- xarray/core/dataarray.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index a3256c4830e..a3210327f3d 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -763,12 +763,12 @@ def values(self) -> np.ndarray: """ The array's data converted to numpy.ndarray. - Note that this array is not copied; operations on it follow - numpy's rules of what generates a view vs. a copy, and changes + Note that this array is not copied; operations on it follow + numpy's rules of what generates a view vs. a copy, and changes to this array may be reflected in the DataArray as well. - This will attempt to convert the array naively using np.array(), - which will raise an error if the array type does not support + This will attempt to convert the array naively using np.array(), + which will raise an error if the array type does not support coercion like this (e.g. cupy). """ return self.variable.values From 327228b3ca99b248ebcf2a75a67ac2a3882ae14d Mon Sep 17 00:00:00 2001 From: Kevin Schwarzwald Date: Mon, 11 Mar 2024 13:03:54 -0400 Subject: [PATCH 4/4] flip order of new .to_values() doc header paragraphs --- xarray/core/dataarray.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index a13d4252abe..64f02fa3b44 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -763,13 +763,13 @@ def values(self) -> np.ndarray: """ The array's data converted to numpy.ndarray. - Note that this array is not copied; operations on it follow - numpy's rules of what generates a view vs. a copy, and changes - to this array may be reflected in the DataArray as well. - This will attempt to convert the array naively using np.array(), which will raise an error if the array type does not support coercion like this (e.g. cupy). + + Note that this array is not copied; operations on it follow + numpy's rules of what generates a view vs. a copy, and changes + to this array may be reflected in the DataArray as well. """ return self.variable.values