From d84e7abc32bb943747437f62f7dff41fb71baa31 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 12 Jun 2020 12:51:07 +0200 Subject: [PATCH 1/3] copy the parameter documentation of Dataset.sel to DataArray.sel --- xarray/core/dataarray.py | 54 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 3451ff14c8f..dfaa943ec5e 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -1076,6 +1076,19 @@ def sel( """Return a new DataArray whose data is given by selecting index labels along the specified dimension(s). + In contrast to `DataArray.isel`, indexers for this method should use + labels instead of integers. + + Under the hood, this method is powered by using pandas's powerful Index + objects. This makes label based indexing essentially just as fast as + using integer indexing. + + It also means this method uses pandas's (well documented) logic for + indexing. This means you can use string shortcuts for datetime indexes + (e.g., '2000-01' to select all values in January 2000). It also means + that slices are treated as inclusive of both the start and stop values, + unlike normal Python indexing. + .. warning:: Do not try to assign values when using any of the indexing methods @@ -1088,6 +1101,47 @@ def sel( Assigning values with the chained indexing using ``.sel`` or ``.isel`` fails silently. + Parameters + ---------- + indexers : dict, optional + A dict with keys matching dimensions and values given + by scalars, slices or arrays of tick labels. For dimensions with + multi-index, the indexer may also be a dict-like object with keys + matching index level names. + If DataArrays are passed as indexers, xarray-style indexing will be + carried out. See :ref:`indexing` for the details. + One of indexers or indexers_kwargs must be provided. + method : {None, 'nearest', 'pad'/'ffill', 'backfill'/'bfill'}, optional + Method to use for inexact matches: + + * None (default): only exact matches + * pad / ffill: propagate last valid index value forward + * backfill / bfill: propagate next valid index value backward + * nearest: use nearest valid index value + tolerance : optional + Maximum distance between original and new labels for inexact + matches. The values of the index at the matching locations must + satisfy the equation ``abs(index[indexer] - target) <= tolerance``. + drop : bool, optional + If ``drop=True``, drop coordinates variables in `indexers` instead + of making them scalar. + **indexers_kwargs : {dim: indexer, ...}, optional + The keyword arguments form of ``indexers``. + One of indexers or indexers_kwargs must be provided. + + Returns + ------- + obj : DataArray + A new DataArray with the same contents as this DataArray, + except the data and each dimension is indexed by the + appropriate indexers. If indexer DataArrays have + coordinates that do not conflict with this object, then + these coordinates will be attached. In general, each + array's data will be a view of the array's data in this + DataArray, unless vectorized indexing was triggered by + using an array indexer, in which case the data will be a + copy. + See Also -------- Dataset.sel From 07558c3af33783b414155ca6366f81f96d87b520 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 12 Jun 2020 12:57:29 +0200 Subject: [PATCH 2/3] reflow the return value documentation --- xarray/core/dataarray.py | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index dfaa943ec5e..44773e36e30 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -1132,15 +1132,13 @@ def sel( Returns ------- obj : DataArray - A new DataArray with the same contents as this DataArray, - except the data and each dimension is indexed by the - appropriate indexers. If indexer DataArrays have - coordinates that do not conflict with this object, then - these coordinates will be attached. In general, each - array's data will be a view of the array's data in this - DataArray, unless vectorized indexing was triggered by - using an array indexer, in which case the data will be a - copy. + A new DataArray with the same contents as this DataArray, except the + data and each dimension is indexed by the appropriate indexers. + If indexer DataArrays have coordinates that do not conflict with + this object, then these coordinates will be attached. + In general, each array's data will be a view of the array's data + in this DataArray, unless vectorized indexing was triggered by using + an array indexer, in which case the data will be a copy. See Also -------- From 2fedb75a86c5060e83349c38558d10bc3d8bed51 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 12 Jun 2020 12:59:28 +0200 Subject: [PATCH 3/3] update whats-new.rst --- doc/whats-new.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 85e73e1b7e8..68b2d738073 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -172,8 +172,10 @@ Documentation By `Matthias Riße `_. - Apply ``black`` to all the code in the documentation (:pull:`4012`) By `Justus Magin `_. -- Narrative documentation now describes :py:meth:`map_blocks`. :ref:`dask.automatic-parallelization`. +- Narrative documentation now describes :py:meth:`map_blocks`: :ref:`dask.automatic-parallelization`. By `Deepak Cherian `_. +- Add documentation for the parameters and return values of :py:meth:`DataArray.sel`. + By `Justus Magin `_. Internal Changes ~~~~~~~~~~~~~~~~