Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs on view / copies #8744

Merged
merged 8 commits into from
Mar 25, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions doc/user-guide/indexing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:

Expand Down
12 changes: 8 additions & 4 deletions xarray/core/dataarray.py
Original file line number Diff line number Diff line change
Expand Up @@ -761,11 +761,15 @@ def data(self, value: Any) -> None:
@property
def values(self) -> np.ndarray:
"""
The array's 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).
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

Expand Down
Loading