Skip to content

Adding vectorized indexing docs #4711

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.

Sign up for GitHub

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

Merged
dcherian merged 10 commits into from
Feb 16, 2021
Merged

Adding vectorized indexing docs #4711

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
40f0050
Add example to sel docstring #4630
EricKeenan Dec 18, 2020
942dc17
Add vectorized indexing example to narrative docs (#4630)
EricKeenan Dec 18, 2020
33c6216
Update example to use a dataarray that is made with np.arange
EricKeenan Jan 5, 2021
5b94de5
Add dataarray.isel example
EricKeenan Jan 5, 2021
404f1f1
Attempting to fix a formatting error
EricKeenan Jan 5, 2021
33ee0f9
Add prompts to example
EricKeenan Jan 13, 2021
7949744
Fix: Forgot to add prompts to sel example.
EricKeenan Jan 13, 2021
b374a17
Apply suggestions from code review
mathause Feb 16, 2021
0f83b76
Merge branch 'master' into vectorized-indexing-docs
mathause Feb 16, 2021
1ad0c04
simplify example
mathause Feb 16, 2021
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
16 changes: 16 additions & 0 deletions doc/indexing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -395,6 +395,22 @@ These methods may also be applied to ``Dataset`` objects
ds = da.to_dataset(name="bar")
ds.isel(x=xr.DataArray([0, 1, 2], dims=["points"]))

Vectorized indexing may be used to extract information from the nearest
grid cells of interest, for example, the nearest climate model grid
cells to a collection specified weather station latitudes and longitudes.
Copy link
Collaborator

@keewis keewis Dec 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did tell you to modify the vectorized indexing section, but while reading #3768 I noticed that we already document that in the More advanced indexing section. Given that it uses pointwise indexing as its only example, maybe we should rename it to Pointwise indexing to make this easier to find?

Copy link
Contributor

@dcherian dcherian Dec 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like that section should be merged with "Vectorized Indexing" which could then be renamed to "Pointwise (or vectorized) Indexing)"?

Copy link
Collaborator

@keewis keewis Dec 19, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed. Also, the term vectorized indexing is not really explained (unless I'm missing something, there's only a comment hinting at it's meaning), so it might be good to explicitly do that somewhere. This sounds like a lot of work, though, so it might be better to do that in a different PR.

Copy link
Contributor Author

@EricKeenan EricKeenan Jan 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting discussion. At this point, I don't think I have much to add here. So I concur that this should be addressed in a different PR.


.. ipython:: python

ds = xr.tutorial.open_dataset("air_temperature")

# Define target latitude and longitude (where weather stations might be)
tgt_lat = xr.DataArray(np.linspace(40, 45, num=6), dims="points")
tgt_lon = xr.DataArray(np.linspace(200, 205, num=6), dims="points")

# Retrieve data at the grid cells nearest to the target latitudes and longitudes
da = ds['air'].sel(lon=tgt_lon, lat=tgt_lat, method='nearest')
da

.. tip::

If you are lazily loading your data from disk, not every form of vectorized
Expand Down
51 changes: 51 additions & 0 deletions xarray/core/dataarray.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1087,6 +1087,29 @@ def isel(
--------
Dataset.isel
DataArray.sel

Examples
--------
>>> da = xr.DataArray(
... np.arange(25).reshape(5, 5),
... dims=("x", "y")
... )
>>> da
<xarray.DataArray (x: 5, y: 5)>
array([[ 0, 1, 2, 3, 4],
[ 5, 6, 7, 8, 9],
[10, 11, 12, 13, 14],
[15, 16, 17, 18, 19],
[20, 21, 22, 23, 24]])
Dimensions without coordinates: x, y

>>> tgt_x = xr.DataArray(np.arange(0, 5), dims="points")
>>> tgt_y = xr.DataArray(np.arange(0, 5), dims="points")
>>> da = da.isel(x=tgt_x, y=tgt_y)
>>> da
<xarray.DataArray (points: 5)>
array([ 0, 6, 12, 18, 24])
Dimensions without coordinates: points
"""

indexers = either_dict_or_kwargs(indexers, indexers_kwargs, "isel")
Expand Down Expand Up @@ -1195,6 +1218,34 @@ def sel(
Dataset.sel
DataArray.isel

Examples
--------
>>> da = xr.DataArray(
... np.arange(25).reshape(5, 5),
... coords={"x": np.arange(5), "y": np.arange(5)},
... dims=("x", "y")
... )
>>> da
<xarray.DataArray (x: 5, y: 5)>
array([[ 0, 1, 2, 3, 4],
[ 5, 6, 7, 8, 9],
[10, 11, 12, 13, 14],
[15, 16, 17, 18, 19],
[20, 21, 22, 23, 24]])
Coordinates:
* x (x) int64 0 1 2 3 4
* y (y) int64 0 1 2 3 4

>>> tgt_x = xr.DataArray(np.linspace(0, 4, num=5), dims="points")
>>> tgt_y = xr.DataArray(np.linspace(0, 4, num=5), dims="points")
>>> da = da.sel(x=tgt_x, y=tgt_y, method='nearest')
>>> da
<xarray.DataArray (points: 5)>
array([ 0, 6, 12, 18, 24])
Coordinates:
x (points) int64 0 1 2 3 4
y (points) int64 0 1 2 3 4
Dimensions without coordinates: points
"""
ds = self._to_temp_dataset().sel(
indexers=indexers,
Expand Down