From 12590005f2c39e3a9459b7ec4966fd535b64c759 Mon Sep 17 00:00:00 2001 From: Tom Nicholas <35968931+TomNicholas@users.noreply.github.com> Date: Tue, 2 Nov 2021 12:37:44 -0400 Subject: [PATCH 01/11] v0.20 Release notes (#5924) * release notes * fix version number * Update doc/whats-new.rst Co-authored-by: Stephan Hoyer * fix length of title underline Co-authored-by: Stephan Hoyer --- doc/whats-new.rst | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 00f7e16480e..64f233ef5c6 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -15,11 +15,22 @@ What's New np.random.seed(123456) -.. _whats-new.0.19.1: +.. _whats-new.0.20.0: -v0.19.1 (unreleased) ---------------------- -.. TODO(by keewis): update deprecations if we decide to skip 0.19.1 +v0.20.0 (1 November 2021) +------------------------- + +This release brings improved support for pint arrays, methods for weighted standard deviation, variance, +and sum of squares, the option to disable the use of the bottleneck library, significantly improved performance of +unstack, as well as many bugfixes and internal changes. + +Many thanks to the 38 contributors to this release!: + +Aaron Spring, Akio Taniguchi, Alan D. Snow, arfy slowy, Benoit Bovy, Christian Jauvin, crusaderky, Deepak Cherian, +Giacomo Caria, Illviljan, James Bourbeau, Joe Hamman, Joseph K Aicher, Julien Herzen, Kai Mühlbauer, +keewis, lusewell, Martin K. Scherer, Mathias Hauser, Max Grover, Maxime Liquet, Maximilian Roos, Mike Taves, pmav99, +Pushkar Kopparla, Ray Bell, Rio McMahon, Scott Staniewicz, Spencer Clark, Stefan Bender, Taher Chegini, Thomas Nicholas, +Tomas Chor, Tom Augspurger, Victor Negîrneac, Zachary Moon, and Zeb Nicholls. New Features ~~~~~~~~~~~~ From 960010b00119367ff6b82e548f2b54ca25c7a59c Mon Sep 17 00:00:00 2001 From: Tom Nicholas <35968931+TomNicholas@users.noreply.github.com> Date: Tue, 2 Nov 2021 14:03:58 -0400 Subject: [PATCH 02/11] Update open_rasterio deprecation version number (#5916) * update version number * also update in documentation [skip-ci] Co-authored-by: Keewis --- doc/user-guide/io.rst | 2 +- xarray/backends/rasterio_.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user-guide/io.rst b/doc/user-guide/io.rst index 6908c6ff535..16b8708231e 100644 --- a/doc/user-guide/io.rst +++ b/doc/user-guide/io.rst @@ -742,7 +742,7 @@ GeoTIFFs and other gridded raster datasets can be opened using `rasterio`_, if rasterio is installed. Here is an example of how to use :py:func:`open_rasterio` to read one of rasterio's `test files`_: -.. deprecated:: 0.19.1 +.. deprecated:: 0.20.0 Deprecated in favor of rioxarray. For information about transitioning, see: diff --git a/xarray/backends/rasterio_.py b/xarray/backends/rasterio_.py index f34240e5e35..9600827a807 100644 --- a/xarray/backends/rasterio_.py +++ b/xarray/backends/rasterio_.py @@ -172,7 +172,7 @@ def open_rasterio( ): """Open a file with rasterio. - .. deprecated:: 0.19.1 + .. deprecated:: 0.20.0 Deprecated in favor of rioxarray. For information about transitioning, see: From b3bc758b9f38aa9cf7ea0f20e91c0bfebfa0beef Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 3 Nov 2021 11:33:06 +0100 Subject: [PATCH 03/11] new whats-new.rst section --- doc/whats-new.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 64f233ef5c6..a971ef2ae9b 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -15,6 +15,26 @@ What's New np.random.seed(123456) +.. _whats-new.0.20.1: + +v0.20.1 (*unreleased*) +---------------------- + +New Features +~~~~~~~~~~~~ + +Breaking changes +~~~~~~~~~~~~~~~~ + +Deprecations +~~~~~~~~~~~~ + +Bug fixes +~~~~~~~~~ + +Internal Changes +~~~~~~~~~~~~~~~~ + .. _whats-new.0.20.0: v0.20.0 (1 November 2021) From 448e403cb2d49d5600bcf04123a9d7afdf3a984e Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Wed, 3 Nov 2021 11:17:41 -0400 Subject: [PATCH 04/11] DOC: add names of missing contributors to 0.20.0 (#5932) --- doc/whats-new.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index a971ef2ae9b..69151530c8a 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -44,13 +44,13 @@ This release brings improved support for pint arrays, methods for weighted stand and sum of squares, the option to disable the use of the bottleneck library, significantly improved performance of unstack, as well as many bugfixes and internal changes. -Many thanks to the 38 contributors to this release!: +Many thanks to the 40 contributors to this release!: Aaron Spring, Akio Taniguchi, Alan D. Snow, arfy slowy, Benoit Bovy, Christian Jauvin, crusaderky, Deepak Cherian, Giacomo Caria, Illviljan, James Bourbeau, Joe Hamman, Joseph K Aicher, Julien Herzen, Kai Mühlbauer, -keewis, lusewell, Martin K. Scherer, Mathias Hauser, Max Grover, Maxime Liquet, Maximilian Roos, Mike Taves, pmav99, -Pushkar Kopparla, Ray Bell, Rio McMahon, Scott Staniewicz, Spencer Clark, Stefan Bender, Taher Chegini, Thomas Nicholas, -Tomas Chor, Tom Augspurger, Victor Negîrneac, Zachary Moon, and Zeb Nicholls. +keewis, lusewell, Martin K. Scherer, Mathias Hauser, Max Grover, Maxime Liquet, Maximilian Roos, Mike Taves, Nathan Lis, +pmav99, Pushkar Kopparla, Ray Bell, Rio McMahon, Scott Staniewicz, Spencer Clark, Stefan Bender, Taher Chegini, +Thomas Nicholas, Tomas Chor, Tom Augspurger, Victor Negîrneac, Zachary Blackwood, Zachary Moon, and Zeb Nicholls. New Features ~~~~~~~~~~~~ @@ -64,7 +64,7 @@ New Features By `Justus Magin `_. - Added ``**kwargs`` argument to :py:meth:`open_rasterio` to access overviews (:issue:`3269`). By `Pushkar Kopparla `_. -- Added ``storage_options`` argument to :py:meth:`to_zarr` (:issue:`5601`). +- Added ``storage_options`` argument to :py:meth:`to_zarr` (:issue:`5601`, :pull:`5615`). By `Ray Bell `_, `Zachary Blackwood `_ and `Nathan Lis `_. - Histogram plots are set with a title displaying the scalar coords if any, similarly to the other plots (:issue:`5791`, :pull:`5792`). From 1d283299147d5000cd6de49585669db2f7264568 Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Wed, 3 Nov 2021 10:55:18 -0600 Subject: [PATCH 05/11] Explicitly list all reductions in api.rst (#5903) --- doc/api-hidden.rst | 208 -------------------- doc/api.rst | 481 ++++++++++++++++++++++++++++++++------------- doc/whats-new.rst | 5 + 3 files changed, 352 insertions(+), 342 deletions(-) diff --git a/doc/api-hidden.rst b/doc/api-hidden.rst index fc27d9c3fe8..a6681715a3e 100644 --- a/doc/api-hidden.rst +++ b/doc/api-hidden.rst @@ -9,24 +9,6 @@ .. autosummary:: :toctree: generated/ - Dataset.nbytes - Dataset.chunks - - Dataset.all - Dataset.any - Dataset.argmax - Dataset.argmin - Dataset.idxmax - Dataset.idxmin - Dataset.max - Dataset.min - Dataset.mean - Dataset.median - Dataset.prod - Dataset.sum - Dataset.std - Dataset.var - core.coordinates.DatasetCoordinates.get core.coordinates.DatasetCoordinates.items core.coordinates.DatasetCoordinates.keys @@ -39,19 +21,6 @@ core.coordinates.DatasetCoordinates.indexes core.coordinates.DatasetCoordinates.variables - core.rolling.DatasetCoarsen.all - core.rolling.DatasetCoarsen.any - core.rolling.DatasetCoarsen.construct - core.rolling.DatasetCoarsen.count - core.rolling.DatasetCoarsen.max - core.rolling.DatasetCoarsen.mean - core.rolling.DatasetCoarsen.median - core.rolling.DatasetCoarsen.min - core.rolling.DatasetCoarsen.prod - core.rolling.DatasetCoarsen.reduce - core.rolling.DatasetCoarsen.std - core.rolling.DatasetCoarsen.sum - core.rolling.DatasetCoarsen.var core.rolling.DatasetCoarsen.boundary core.rolling.DatasetCoarsen.coord_func core.rolling.DatasetCoarsen.obj @@ -59,64 +28,6 @@ core.rolling.DatasetCoarsen.trim_excess core.rolling.DatasetCoarsen.windows - core.groupby.DatasetGroupBy.assign - core.groupby.DatasetGroupBy.assign_coords - core.groupby.DatasetGroupBy.first - core.groupby.DatasetGroupBy.last - core.groupby.DatasetGroupBy.fillna - core.groupby.DatasetGroupBy.quantile - core.groupby.DatasetGroupBy.where - core.groupby.DatasetGroupBy.all - core.groupby.DatasetGroupBy.any - core.groupby.DatasetGroupBy.count - core.groupby.DatasetGroupBy.max - core.groupby.DatasetGroupBy.mean - core.groupby.DatasetGroupBy.median - core.groupby.DatasetGroupBy.min - core.groupby.DatasetGroupBy.prod - core.groupby.DatasetGroupBy.std - core.groupby.DatasetGroupBy.sum - core.groupby.DatasetGroupBy.var - core.groupby.DatasetGroupBy.dims - core.groupby.DatasetGroupBy.groups - - core.resample.DatasetResample.all - core.resample.DatasetResample.any - core.resample.DatasetResample.apply - core.resample.DatasetResample.assign - core.resample.DatasetResample.assign_coords - core.resample.DatasetResample.bfill - core.resample.DatasetResample.count - core.resample.DatasetResample.ffill - core.resample.DatasetResample.fillna - core.resample.DatasetResample.first - core.resample.DatasetResample.last - core.resample.DatasetResample.map - core.resample.DatasetResample.max - core.resample.DatasetResample.mean - core.resample.DatasetResample.median - core.resample.DatasetResample.min - core.resample.DatasetResample.prod - core.resample.DatasetResample.quantile - core.resample.DatasetResample.reduce - core.resample.DatasetResample.std - core.resample.DatasetResample.sum - core.resample.DatasetResample.var - core.resample.DatasetResample.where - core.resample.DatasetResample.dims - core.resample.DatasetResample.groups - - core.rolling.DatasetRolling.argmax - core.rolling.DatasetRolling.argmin - core.rolling.DatasetRolling.count - core.rolling.DatasetRolling.max - core.rolling.DatasetRolling.mean - core.rolling.DatasetRolling.median - core.rolling.DatasetRolling.min - core.rolling.DatasetRolling.prod - core.rolling.DatasetRolling.std - core.rolling.DatasetRolling.sum - core.rolling.DatasetRolling.var core.rolling.DatasetRolling.center core.rolling.DatasetRolling.dim core.rolling.DatasetRolling.min_periods @@ -127,49 +38,12 @@ core.weighted.DatasetWeighted.obj core.weighted.DatasetWeighted.weights - core.rolling_exp.RollingExp.mean - - Dataset.argsort - Dataset.astype - Dataset.clip - Dataset.conj - Dataset.conjugate - Dataset.imag - Dataset.round - Dataset.real - Dataset.cumsum - Dataset.cumprod - Dataset.rank - Dataset.load_store Dataset.dump_to_store - DataArray.ndim - DataArray.nbytes - DataArray.shape - DataArray.size - DataArray.dtype - DataArray.nbytes - DataArray.chunks - DataArray.astype DataArray.item - DataArray.all - DataArray.any - DataArray.argmax - DataArray.argmin - DataArray.idxmax - DataArray.idxmin - DataArray.max - DataArray.min - DataArray.mean - DataArray.median - DataArray.prod - DataArray.sum - DataArray.std - DataArray.var - core.coordinates.DataArrayCoordinates.get core.coordinates.DataArrayCoordinates.items core.coordinates.DataArrayCoordinates.keys @@ -182,19 +56,6 @@ core.coordinates.DataArrayCoordinates.indexes core.coordinates.DataArrayCoordinates.variables - core.rolling.DataArrayCoarsen.all - core.rolling.DataArrayCoarsen.any - core.rolling.DataArrayCoarsen.construct - core.rolling.DataArrayCoarsen.count - core.rolling.DataArrayCoarsen.max - core.rolling.DataArrayCoarsen.mean - core.rolling.DataArrayCoarsen.median - core.rolling.DataArrayCoarsen.min - core.rolling.DataArrayCoarsen.prod - core.rolling.DataArrayCoarsen.reduce - core.rolling.DataArrayCoarsen.std - core.rolling.DataArrayCoarsen.sum - core.rolling.DataArrayCoarsen.var core.rolling.DataArrayCoarsen.boundary core.rolling.DataArrayCoarsen.coord_func core.rolling.DataArrayCoarsen.obj @@ -202,62 +63,6 @@ core.rolling.DataArrayCoarsen.trim_excess core.rolling.DataArrayCoarsen.windows - core.groupby.DataArrayGroupBy.assign_coords - core.groupby.DataArrayGroupBy.first - core.groupby.DataArrayGroupBy.last - core.groupby.DataArrayGroupBy.fillna - core.groupby.DataArrayGroupBy.quantile - core.groupby.DataArrayGroupBy.where - core.groupby.DataArrayGroupBy.all - core.groupby.DataArrayGroupBy.any - core.groupby.DataArrayGroupBy.count - core.groupby.DataArrayGroupBy.max - core.groupby.DataArrayGroupBy.mean - core.groupby.DataArrayGroupBy.median - core.groupby.DataArrayGroupBy.min - core.groupby.DataArrayGroupBy.prod - core.groupby.DataArrayGroupBy.std - core.groupby.DataArrayGroupBy.sum - core.groupby.DataArrayGroupBy.var - core.groupby.DataArrayGroupBy.dims - core.groupby.DataArrayGroupBy.groups - - core.resample.DataArrayResample.all - core.resample.DataArrayResample.any - core.resample.DataArrayResample.apply - core.resample.DataArrayResample.assign_coords - core.resample.DataArrayResample.bfill - core.resample.DataArrayResample.count - core.resample.DataArrayResample.ffill - core.resample.DataArrayResample.fillna - core.resample.DataArrayResample.first - core.resample.DataArrayResample.last - core.resample.DataArrayResample.map - core.resample.DataArrayResample.max - core.resample.DataArrayResample.mean - core.resample.DataArrayResample.median - core.resample.DataArrayResample.min - core.resample.DataArrayResample.prod - core.resample.DataArrayResample.quantile - core.resample.DataArrayResample.reduce - core.resample.DataArrayResample.std - core.resample.DataArrayResample.sum - core.resample.DataArrayResample.var - core.resample.DataArrayResample.where - core.resample.DataArrayResample.dims - core.resample.DataArrayResample.groups - - core.rolling.DataArrayRolling.argmax - core.rolling.DataArrayRolling.argmin - core.rolling.DataArrayRolling.count - core.rolling.DataArrayRolling.max - core.rolling.DataArrayRolling.mean - core.rolling.DataArrayRolling.median - core.rolling.DataArrayRolling.min - core.rolling.DataArrayRolling.prod - core.rolling.DataArrayRolling.std - core.rolling.DataArrayRolling.sum - core.rolling.DataArrayRolling.var core.rolling.DataArrayRolling.center core.rolling.DataArrayRolling.dim core.rolling.DataArrayRolling.min_periods @@ -268,19 +73,6 @@ core.weighted.DataArrayWeighted.obj core.weighted.DataArrayWeighted.weights - DataArray.argsort - DataArray.clip - DataArray.conj - DataArray.conjugate - DataArray.imag - DataArray.searchsorted - DataArray.round - DataArray.real - DataArray.T - DataArray.cumsum - DataArray.cumprod - DataArray.rank - core.accessor_dt.DatetimeAccessor.ceil core.accessor_dt.DatetimeAccessor.floor core.accessor_dt.DatetimeAccessor.round diff --git a/doc/api.rst b/doc/api.rst index 183e9d1425e..9433ecfa56d 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1,5 +1,7 @@ .. currentmodule:: xarray +.. _api: + ############# API reference ############# @@ -63,7 +65,6 @@ Attributes Dataset.attrs Dataset.encoding Dataset.indexes - Dataset.get_index Dataset.chunks Dataset.chunksizes Dataset.nbytes @@ -107,6 +108,7 @@ Dataset contents Dataset.drop_dims Dataset.set_coords Dataset.reset_coords + Dataset.get_index Comparisons ----------- @@ -183,43 +185,44 @@ Computation Dataset.polyfit Dataset.curvefit -**Aggregation**: -:py:attr:`~Dataset.all` -:py:attr:`~Dataset.any` -:py:attr:`~Dataset.argmax` -:py:attr:`~Dataset.argmin` -:py:attr:`~Dataset.idxmax` -:py:attr:`~Dataset.idxmin` -:py:attr:`~Dataset.max` -:py:attr:`~Dataset.mean` -:py:attr:`~Dataset.median` -:py:attr:`~Dataset.min` -:py:attr:`~Dataset.prod` -:py:attr:`~Dataset.sum` -:py:attr:`~Dataset.std` -:py:attr:`~Dataset.var` - -**ndarray methods**: -:py:attr:`~Dataset.astype` -:py:attr:`~Dataset.argsort` -:py:attr:`~Dataset.clip` -:py:attr:`~Dataset.conj` -:py:attr:`~Dataset.conjugate` -:py:attr:`~Dataset.imag` -:py:attr:`~Dataset.round` -:py:attr:`~Dataset.real` -:py:attr:`~Dataset.cumsum` -:py:attr:`~Dataset.cumprod` -:py:attr:`~Dataset.rank` - -**Grouped operations**: -:py:attr:`~core.groupby.DatasetGroupBy.assign` -:py:attr:`~core.groupby.DatasetGroupBy.assign_coords` -:py:attr:`~core.groupby.DatasetGroupBy.first` -:py:attr:`~core.groupby.DatasetGroupBy.last` -:py:attr:`~core.groupby.DatasetGroupBy.fillna` -:py:attr:`~core.groupby.DatasetGroupBy.where` -:py:attr:`~core.groupby.DatasetGroupBy.quantile` +Aggregation +----------- + +.. autosummary:: + :toctree: generated/ + + Dataset.all + Dataset.any + Dataset.argmax + Dataset.argmin + Dataset.idxmax + Dataset.idxmin + Dataset.max + Dataset.min + Dataset.mean + Dataset.median + Dataset.prod + Dataset.sum + Dataset.std + Dataset.var + Dataset.cumsum + Dataset.cumprod + +ndarray methods +--------------- + +.. autosummary:: + :toctree: generated/ + + Dataset.argsort + Dataset.astype + Dataset.clip + Dataset.conj + Dataset.conjugate + Dataset.imag + Dataset.round + Dataset.real + Dataset.rank Reshaping and reorganizing -------------------------- @@ -271,16 +274,22 @@ Attributes DataArray.attrs DataArray.encoding DataArray.indexes - DataArray.get_index DataArray.chunksizes -**ndarray attributes**: -:py:attr:`~DataArray.ndim` -:py:attr:`~DataArray.shape` -:py:attr:`~DataArray.size` -:py:attr:`~DataArray.dtype` -:py:attr:`~DataArray.nbytes` -:py:attr:`~DataArray.chunks` +ndarray attributes +------------------ + +.. autosummary:: + :toctree: generated/ + + DataArray.ndim + DataArray.nbytes + DataArray.shape + DataArray.size + DataArray.dtype + DataArray.nbytes + DataArray.chunks + DataArray contents ------------------ @@ -298,11 +307,9 @@ DataArray contents DataArray.drop_duplicates DataArray.reset_coords DataArray.copy - -**ndarray methods**: -:py:attr:`~DataArray.astype` -:py:attr:`~DataArray.item` - + DataArray.get_index + DataArray.astype + DataArray.item Indexing -------- @@ -382,43 +389,45 @@ Computation DataArray.map_blocks DataArray.curvefit -**Aggregation**: -:py:attr:`~DataArray.all` -:py:attr:`~DataArray.any` -:py:attr:`~DataArray.argmax` -:py:attr:`~DataArray.argmin` -:py:attr:`~DataArray.idxmax` -:py:attr:`~DataArray.idxmin` -:py:attr:`~DataArray.max` -:py:attr:`~DataArray.mean` -:py:attr:`~DataArray.median` -:py:attr:`~DataArray.min` -:py:attr:`~DataArray.prod` -:py:attr:`~DataArray.sum` -:py:attr:`~DataArray.std` -:py:attr:`~DataArray.var` - -**ndarray methods**: -:py:attr:`~DataArray.argsort` -:py:attr:`~DataArray.clip` -:py:attr:`~DataArray.conj` -:py:attr:`~DataArray.conjugate` -:py:attr:`~DataArray.imag` -:py:attr:`~DataArray.searchsorted` -:py:attr:`~DataArray.round` -:py:attr:`~DataArray.real` -:py:attr:`~DataArray.T` -:py:attr:`~DataArray.cumsum` -:py:attr:`~DataArray.cumprod` -:py:attr:`~DataArray.rank` - -**Grouped operations**: -:py:attr:`~core.groupby.DataArrayGroupBy.assign_coords` -:py:attr:`~core.groupby.DataArrayGroupBy.first` -:py:attr:`~core.groupby.DataArrayGroupBy.last` -:py:attr:`~core.groupby.DataArrayGroupBy.fillna` -:py:attr:`~core.groupby.DataArrayGroupBy.where` -:py:attr:`~core.groupby.DataArrayGroupBy.quantile` +Aggregation +----------- + +.. autosummary:: + :toctree: generated/ + + DataArray.all + DataArray.any + DataArray.argmax + DataArray.argmin + DataArray.idxmax + DataArray.idxmin + DataArray.max + DataArray.min + DataArray.mean + DataArray.median + DataArray.prod + DataArray.sum + DataArray.std + DataArray.var + DataArray.cumsum + DataArray.cumprod + +ndarray methods +--------------- + +.. autosummary:: + :toctree: generated/ + + DataArray.argsort + DataArray.clip + DataArray.conj + DataArray.conjugate + DataArray.imag + DataArray.searchsorted + DataArray.round + DataArray.real + DataArray.T + DataArray.rank String manipulation @@ -749,87 +758,291 @@ Coordinates objects GroupBy objects =============== +.. currentmodule:: xarray.core.groupby + +Dataset +------- + .. autosummary:: :toctree: generated/ - core.groupby.DataArrayGroupBy - core.groupby.DataArrayGroupBy.map - core.groupby.DataArrayGroupBy.reduce - core.groupby.DatasetGroupBy - core.groupby.DatasetGroupBy.map - core.groupby.DatasetGroupBy.reduce + DatasetGroupBy + DatasetGroupBy.map + DatasetGroupBy.reduce + DatasetGroupBy.assign + DatasetGroupBy.assign_coords + DatasetGroupBy.first + DatasetGroupBy.last + DatasetGroupBy.fillna + DatasetGroupBy.quantile + DatasetGroupBy.where + DatasetGroupBy.all + DatasetGroupBy.any + DatasetGroupBy.count + DatasetGroupBy.max + DatasetGroupBy.mean + DatasetGroupBy.median + DatasetGroupBy.min + DatasetGroupBy.prod + DatasetGroupBy.std + DatasetGroupBy.sum + DatasetGroupBy.var + DatasetGroupBy.dims + DatasetGroupBy.groups + +DataArray +--------- + +.. autosummary:: + :toctree: generated/ + + DataArrayGroupBy + DataArrayGroupBy.map + DataArrayGroupBy.reduce + DataArrayGroupBy.assign_coords + DataArrayGroupBy.first + DataArrayGroupBy.last + DataArrayGroupBy.fillna + DataArrayGroupBy.quantile + DataArrayGroupBy.where + DataArrayGroupBy.all + DataArrayGroupBy.any + DataArrayGroupBy.count + DataArrayGroupBy.max + DataArrayGroupBy.mean + DataArrayGroupBy.median + DataArrayGroupBy.min + DataArrayGroupBy.prod + DataArrayGroupBy.std + DataArrayGroupBy.sum + DataArrayGroupBy.var + DataArrayGroupBy.dims + DataArrayGroupBy.groups + Rolling objects =============== +.. currentmodule:: xarray.core.rolling + +Dataset +------- + .. autosummary:: :toctree: generated/ - core.rolling.DataArrayRolling - core.rolling.DataArrayRolling.construct - core.rolling.DataArrayRolling.reduce - core.rolling.DatasetRolling - core.rolling.DatasetRolling.construct - core.rolling.DatasetRolling.reduce - core.rolling_exp.RollingExp + DatasetRolling + DatasetRolling.construct + DatasetRolling.reduce + DatasetRolling.argmax + DatasetRolling.argmin + DatasetRolling.count + DatasetRolling.max + DatasetRolling.mean + DatasetRolling.median + DatasetRolling.min + DatasetRolling.prod + DatasetRolling.std + DatasetRolling.sum + DatasetRolling.var -Weighted objects -================ +DataArray +--------- .. autosummary:: :toctree: generated/ - core.weighted.DataArrayWeighted - core.weighted.DataArrayWeighted.mean - core.weighted.DataArrayWeighted.std - core.weighted.DataArrayWeighted.sum - core.weighted.DataArrayWeighted.sum_of_squares - core.weighted.DataArrayWeighted.sum_of_weights - core.weighted.DataArrayWeighted.var - core.weighted.DatasetWeighted - core.weighted.DatasetWeighted.mean - core.weighted.DatasetWeighted.std - core.weighted.DatasetWeighted.sum - core.weighted.DatasetWeighted.sum_of_squares - core.weighted.DatasetWeighted.sum_of_weights - core.weighted.DatasetWeighted.var - + DataArrayRolling + DataArrayRolling.construct + DataArrayRolling.reduce + DataArrayRolling.argmax + DataArrayRolling.argmin + DataArrayRolling.count + DataArrayRolling.max + DataArrayRolling.mean + DataArrayRolling.median + DataArrayRolling.min + DataArrayRolling.prod + DataArrayRolling.std + DataArrayRolling.sum + DataArrayRolling.var Coarsen objects =============== +Dataset +------- + +.. autosummary:: + :toctree: generated/ + + DatasetCoarsen + DatasetCoarsen.all + DatasetCoarsen.any + DatasetCoarsen.construct + DatasetCoarsen.count + DatasetCoarsen.max + DatasetCoarsen.mean + DatasetCoarsen.median + DatasetCoarsen.min + DatasetCoarsen.prod + DatasetCoarsen.reduce + DatasetCoarsen.std + DatasetCoarsen.sum + DatasetCoarsen.var + +DataArray +--------- + +.. autosummary:: + :toctree: generated/ + + DataArrayCoarsen + DataArrayCoarsen.all + DataArrayCoarsen.any + DataArrayCoarsen.construct + DataArrayCoarsen.count + DataArrayCoarsen.max + DataArrayCoarsen.mean + DataArrayCoarsen.median + DataArrayCoarsen.min + DataArrayCoarsen.prod + DataArrayCoarsen.reduce + DataArrayCoarsen.std + DataArrayCoarsen.sum + DataArrayCoarsen.var + +Exponential rolling objects +=========================== + +.. currentmodule:: xarray.core.rolling_exp + +.. autosummary:: + :toctree: generated/ + + RollingExp + RollingExp.mean + RollingExp.sum + +Weighted objects +================ + +.. currentmodule:: xarray.core.weighted + +Dataset +------- + .. autosummary:: :toctree: generated/ - core.rolling.DataArrayCoarsen - core.rolling.DatasetCoarsen + DatasetWeighted + DatasetWeighted.mean + DatasetWeighted.sum + DatasetWeighted.std + DatasetWeighted.var + DatasetWeighted.sum_of_weights + DatasetWeighted.sum_of_squares + +DataArray +--------- + +.. autosummary:: + :toctree: generated/ + DataArrayWeighted + DataArrayWeighted.mean + DataArrayWeighted.sum + DataArrayWeighted.std + DataArrayWeighted.var + DataArrayWeighted.sum_of_weights + DataArrayWeighted.sum_of_squares Resample objects ================ -Resample objects also implement the GroupBy interface -(methods like ``map()``, ``reduce()``, ``mean()``, ``sum()``, etc.). +.. currentmodule:: xarray.core.resample + +Dataset +------- .. autosummary:: :toctree: generated/ - core.resample.DataArrayResample - core.resample.DataArrayResample.asfreq - core.resample.DataArrayResample.backfill - core.resample.DataArrayResample.interpolate - core.resample.DataArrayResample.nearest - core.resample.DataArrayResample.pad - core.resample.DatasetResample - core.resample.DatasetResample.asfreq - core.resample.DatasetResample.backfill - core.resample.DatasetResample.interpolate - core.resample.DatasetResample.nearest - core.resample.DatasetResample.pad + DatasetResample + DatasetResample.asfreq + DatasetResample.backfill + DatasetResample.interpolate + DatasetResample.nearest + DatasetResample.pad + DatasetResample.all + DatasetResample.any + DatasetResample.apply + DatasetResample.assign + DatasetResample.assign_coords + DatasetResample.bfill + DatasetResample.count + DatasetResample.ffill + DatasetResample.fillna + DatasetResample.first + DatasetResample.last + DatasetResample.map + DatasetResample.max + DatasetResample.mean + DatasetResample.median + DatasetResample.min + DatasetResample.prod + DatasetResample.quantile + DatasetResample.reduce + DatasetResample.std + DatasetResample.sum + DatasetResample.var + DatasetResample.where + DatasetResample.dims + DatasetResample.groups + + +DataArray +--------- + +.. autosummary:: + :toctree: generated/ + + DataArrayResample + DataArrayResample.asfreq + DataArrayResample.backfill + DataArrayResample.interpolate + DataArrayResample.nearest + DataArrayResample.pad + DataArrayResample.all + DataArrayResample.any + DataArrayResample.apply + DataArrayResample.assign_coords + DataArrayResample.bfill + DataArrayResample.count + DataArrayResample.ffill + DataArrayResample.fillna + DataArrayResample.first + DataArrayResample.last + DataArrayResample.map + DataArrayResample.max + DataArrayResample.mean + DataArrayResample.median + DataArrayResample.min + DataArrayResample.prod + DataArrayResample.quantile + DataArrayResample.reduce + DataArrayResample.std + DataArrayResample.sum + DataArrayResample.var + DataArrayResample.where + DataArrayResample.dims + DataArrayResample.groups Accessors ========= +.. currentmodule:: xarray + .. autosummary:: :toctree: generated/ diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 69151530c8a..06d9ea8ed40 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -32,6 +32,11 @@ Deprecations Bug fixes ~~~~~~~~~ +Documentation +~~~~~~~~~~~~~ + +- Significant improvements to :ref:`api`. By `Deepak Cherian `_. + Internal Changes ~~~~~~~~~~~~~~~~ From 3e05d6ed215a6e71d9bec5d9e25302f7295437c8 Mon Sep 17 00:00:00 2001 From: keewis Date: Wed, 3 Nov 2021 17:55:54 +0100 Subject: [PATCH 06/11] fix the detection of backend entrypoints (#5931) --- ci/requirements/py37-bare-minimum.yml | 1 + ci/requirements/py37-min-all-deps.yml | 1 + doc/whats-new.rst | 2 ++ xarray/backends/plugins.py | 10 +++------- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/ci/requirements/py37-bare-minimum.yml b/ci/requirements/py37-bare-minimum.yml index f9148d6dfd0..620b5057d50 100644 --- a/ci/requirements/py37-bare-minimum.yml +++ b/ci/requirements/py37-bare-minimum.yml @@ -13,3 +13,4 @@ dependencies: - numpy=1.18 - pandas=1.1 - typing_extensions=3.7 + - importlib-metadata=2.0 diff --git a/ci/requirements/py37-min-all-deps.yml b/ci/requirements/py37-min-all-deps.yml index 2d5a0f4e8d9..e62987dd31a 100644 --- a/ci/requirements/py37-min-all-deps.yml +++ b/ci/requirements/py37-min-all-deps.yml @@ -24,6 +24,7 @@ dependencies: - hdf5=1.10 - hypothesis - iris=2.4 + - importlib-metadata=2.0 - lxml=4.6 # Optional dep of pydap - matplotlib-base=3.3 - nc-time-axis=1.2 diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 06d9ea8ed40..be39cd387d8 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -31,6 +31,8 @@ Deprecations Bug fixes ~~~~~~~~~ +- Fix a regression in the detection of the backend entrypoints (:issue:`5930`, :pull:`5931`) + By `Justus Magin `_. Documentation ~~~~~~~~~~~~~ diff --git a/xarray/backends/plugins.py b/xarray/backends/plugins.py index b71ca7be55c..bcaee498b90 100644 --- a/xarray/backends/plugins.py +++ b/xarray/backends/plugins.py @@ -6,10 +6,10 @@ from .common import BACKEND_ENTRYPOINTS, BackendEntrypoint try: - from importlib.metadata import Distribution + from importlib.metadata import entry_points except ImportError: # if the fallback library is missing, we are doomed. - from importlib_metadata import Distribution # type: ignore[no-redef] + from importlib_metadata import entry_points # type: ignore[no-redef] STANDARD_BACKENDS_ORDER = ["netcdf4", "h5netcdf", "scipy"] @@ -99,11 +99,7 @@ def build_engines(entrypoints): @functools.lru_cache(maxsize=1) def list_engines(): - entrypoints = ( - entry_point - for entry_point in Distribution.from_name("xarray").entry_points - if entry_point.module == "xarray.backends" - ) + entrypoints = entry_points().get("xarray.backends", ()) return build_engines(entrypoints) From d2edee5df1eaad650c309daa260a7cea58258cce Mon Sep 17 00:00:00 2001 From: Bruno Pagani Date: Thu, 4 Nov 2021 14:12:45 +0400 Subject: [PATCH 07/11] Fix a missing @requires_zarr in tests (#5936) When zarr is not available, this test fails with `NameError: name 'zarr' is not defined`. --- xarray/tests/test_backends.py | 1 + 1 file changed, 1 insertion(+) diff --git a/xarray/tests/test_backends.py b/xarray/tests/test_backends.py index 4e9b98b02e9..b567e49c29f 100644 --- a/xarray/tests/test_backends.py +++ b/xarray/tests/test_backends.py @@ -2398,6 +2398,7 @@ def create_zarr_target(self): yield tmp +@requires_zarr @requires_fsspec def test_zarr_storage_options(): pytest.importorskip("aiobotocore") From c31e970bcf23d421000fa182bced34cdf1793735 Mon Sep 17 00:00:00 2001 From: Stephan Hoyer Date: Fri, 5 Nov 2021 02:36:03 -0700 Subject: [PATCH 08/11] Docs: fix URL for PTSA (#5935) --- doc/ecosystem.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ecosystem.rst b/doc/ecosystem.rst index 460541e91d7..1ced8913ce2 100644 --- a/doc/ecosystem.rst +++ b/doc/ecosystem.rst @@ -58,7 +58,7 @@ Machine Learning Other domains ~~~~~~~~~~~~~ -- `ptsa `_: EEG Time Series Analysis +- `ptsa `_: EEG Time Series Analysis - `pycalphad `_: Computational Thermodynamics in Python - `pyomeca `_: Python framework for biomechanical analysis From 12a216d632111fc6be39cdaa98335a9bb22f2c5d Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Fri, 5 Nov 2021 11:00:23 -0600 Subject: [PATCH 09/11] whats-new for 0.20.1 (#5943) --- doc/whats-new.rst | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index be39cd387d8..58cf5f5d998 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -17,17 +17,10 @@ What's New .. _whats-new.0.20.1: -v0.20.1 (*unreleased*) ----------------------- - -New Features -~~~~~~~~~~~~ - -Breaking changes -~~~~~~~~~~~~~~~~ +v0.20.1 (5 November 2021) +------------------------- -Deprecations -~~~~~~~~~~~~ +This is a bugfix release to fix :issue:`5930`. Bug fixes ~~~~~~~~~ @@ -39,9 +32,6 @@ Documentation - Significant improvements to :ref:`api`. By `Deepak Cherian `_. -Internal Changes -~~~~~~~~~~~~~~~~ - .. _whats-new.0.20.0: v0.20.0 (1 November 2021) From f469e220fc0999d62857d635f02bac37a0bb837e Mon Sep 17 00:00:00 2001 From: dcherian Date: Fri, 5 Nov 2021 11:06:23 -0600 Subject: [PATCH 10/11] whats-new dev --- doc/whats-new.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 58cf5f5d998..bcc40f4fd48 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -15,6 +15,35 @@ What's New np.random.seed(123456) +.. _whats-new.0.20.2: + +v0.20.2 (unreleased) +--------------------- + +New Features +~~~~~~~~~~~~ + + +Breaking changes +~~~~~~~~~~~~~~~~ + + +Deprecations +~~~~~~~~~~~~ + + +Bug fixes +~~~~~~~~~ + + +Documentation +~~~~~~~~~~~~~ + + +Internal Changes +~~~~~~~~~~~~~~~~ + + .. _whats-new.0.20.1: v0.20.1 (5 November 2021) From 1ecf91a4d19f17703795d8016b99fb7ab88ee175 Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Fri, 5 Nov 2021 12:22:44 -0600 Subject: [PATCH 11/11] Generator for groupby reductions (#5871) Co-authored-by: Maximilian Roos Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com> --- .pre-commit-config.yaml | 1 + doc/whats-new.rst | 5 + xarray/core/_reductions.py | 3739 ++++++++++++++++++++++++++++ xarray/core/arithmetic.py | 4 - xarray/core/groupby.py | 13 +- xarray/core/resample.py | 7 +- xarray/util/generate_reductions.py | 296 +++ 7 files changed, 4056 insertions(+), 9 deletions(-) create mode 100644 xarray/core/_reductions.py create mode 100644 xarray/util/generate_reductions.py diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 27f93c8e578..8c9b61a7364 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -21,6 +21,7 @@ repos: rev: v0.3.4 hooks: - id: blackdoc + exclude: "generate_reductions.py" - repo: https://gitlab.com/pycqa/flake8 rev: 3.9.2 hooks: diff --git a/doc/whats-new.rst b/doc/whats-new.rst index bcc40f4fd48..0128e70caed 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -39,6 +39,11 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Better examples in docstrings for groupby and resampling reductions (:pull:`5871`). + By `Deepak Cherian `_, + `Maximilian Roos `_, + `Jimmy Westling `_ . + Internal Changes ~~~~~~~~~~~~~~~~ diff --git a/xarray/core/_reductions.py b/xarray/core/_reductions.py new file mode 100644 index 00000000000..67fbbd482d0 --- /dev/null +++ b/xarray/core/_reductions.py @@ -0,0 +1,3739 @@ +"""Mixin classes with reduction operations.""" +# This file was generated using xarray.util.generate_reductions. Do not edit manually. + +import sys +from typing import Any, Callable, Hashable, Optional, Sequence, Union + +from . import duck_array_ops +from .types import T_DataArray, T_Dataset + +if sys.version_info >= (3, 8): + from typing import Protocol +else: + from typing_extensions import Protocol + + +class DatasetReduce(Protocol): + def reduce( + self, + func: Callable[..., Any], + dim: Union[None, Hashable, Sequence[Hashable]] = None, + axis: Union[None, int, Sequence[int]] = None, + keep_attrs: bool = None, + keepdims: bool = False, + **kwargs: Any, + ) -> T_Dataset: + ... + + +class DatasetGroupByReductions: + __slots__ = () + + def count( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``count`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``count``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``count`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``count`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").count() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) int64 1 2 2 + + See Also + -------- + numpy.count + Dataset.count + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.count, + dim=dim, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def all( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``all`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``all``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``all`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``all`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([True, True, True, True, True, False], dtype=bool), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").all() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) bool False True True + + See Also + -------- + numpy.all + Dataset.all + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.array_all, + dim=dim, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def any( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``any`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``any``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``any`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``any`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([True, True, True, True, True, False], dtype=bool), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").any() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) bool True True True + + See Also + -------- + numpy.any + Dataset.any + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.array_any, + dim=dim, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def max( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``max`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``max``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``max`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``max`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").max() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 1.0 2.0 3.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.groupby("labels").max(skipna=False) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 2.0 3.0 + + See Also + -------- + numpy.max + Dataset.max + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.max, + dim=dim, + skipna=skipna, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def min( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``min`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``min``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``min`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``min`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").min() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 1.0 2.0 1.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.groupby("labels").min(skipna=False) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 2.0 1.0 + + See Also + -------- + numpy.min + Dataset.min + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.min, + dim=dim, + skipna=skipna, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def mean( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``mean`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``mean``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``mean`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``mean`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").mean() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 1.0 2.0 2.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.groupby("labels").mean(skipna=False) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 2.0 2.0 + + See Also + -------- + numpy.mean + Dataset.mean + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.mean, + dim=dim, + skipna=skipna, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def prod( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + min_count: Optional[int] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``prod`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``prod``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``prod`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``prod`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").prod() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 1.0 4.0 3.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.groupby("labels").prod(skipna=False) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 4.0 3.0 + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> ds.groupby("labels").prod(skipna=True, min_count=2) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 4.0 3.0 + + See Also + -------- + numpy.prod + Dataset.prod + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.prod, + dim=dim, + skipna=skipna, + min_count=min_count, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def sum( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + min_count: Optional[int] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``sum`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``sum``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``sum`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``sum`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").sum() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 1.0 4.0 4.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.groupby("labels").sum(skipna=False) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 4.0 4.0 + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> ds.groupby("labels").sum(skipna=True, min_count=2) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 4.0 4.0 + + See Also + -------- + numpy.sum + Dataset.sum + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.sum, + dim=dim, + skipna=skipna, + min_count=min_count, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def std( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``std`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``std``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``std`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``std`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").std() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 0.0 0.0 1.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.groupby("labels").std(skipna=False) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 0.0 1.0 + + See Also + -------- + numpy.std + Dataset.std + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.std, + dim=dim, + skipna=skipna, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def var( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``var`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``var``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``var`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``var`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").var() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 0.0 0.0 1.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.groupby("labels").var(skipna=False) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 0.0 1.0 + + See Also + -------- + numpy.var + Dataset.var + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.var, + dim=dim, + skipna=skipna, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def median( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``median`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``median``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``median`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``median`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.groupby("labels").median() + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 1.0 2.0 2.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.groupby("labels").median(skipna=False) + + Dimensions: (labels: 3) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + Data variables: + da (labels) float64 nan 2.0 2.0 + + See Also + -------- + numpy.median + Dataset.median + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.median, + dim=dim, + skipna=skipna, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + +class DatasetResampleReductions: + __slots__ = () + + def count( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``count`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``count``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``count`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``count`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").count() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) int64 1 3 1 + + See Also + -------- + numpy.count + Dataset.count + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.count, + dim=dim, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def all( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``all`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``all``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``all`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``all`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([True, True, True, True, True, False], dtype=bool), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").all() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) bool True True False + + See Also + -------- + numpy.all + Dataset.all + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.array_all, + dim=dim, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def any( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``any`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``any``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``any`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``any`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([True, True, True, True, True, False], dtype=bool), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").any() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) bool True True True + + See Also + -------- + numpy.any + Dataset.any + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.array_any, + dim=dim, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def max( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``max`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``max``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``max`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``max`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").max() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 3.0 2.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.resample(time="3M").max(skipna=False) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 3.0 nan + + See Also + -------- + numpy.max + Dataset.max + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.max, + dim=dim, + skipna=skipna, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def min( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``min`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``min``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``min`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``min`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").min() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 1.0 2.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.resample(time="3M").min(skipna=False) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 1.0 nan + + See Also + -------- + numpy.min + Dataset.min + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.min, + dim=dim, + skipna=skipna, + numeric_only=False, + keep_attrs=keep_attrs, + **kwargs, + ) + + def mean( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``mean`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``mean``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``mean`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``mean`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").mean() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 2.0 2.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.resample(time="3M").mean(skipna=False) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 2.0 nan + + See Also + -------- + numpy.mean + Dataset.mean + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.mean, + dim=dim, + skipna=skipna, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def prod( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + min_count: Optional[int] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``prod`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``prod``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``prod`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``prod`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").prod() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 6.0 2.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.resample(time="3M").prod(skipna=False) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 6.0 nan + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> ds.resample(time="3M").prod(skipna=True, min_count=2) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 nan 6.0 nan + + See Also + -------- + numpy.prod + Dataset.prod + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.prod, + dim=dim, + skipna=skipna, + min_count=min_count, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def sum( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + min_count: Optional[int] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``sum`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``sum``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``sum`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``sum`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").sum() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 6.0 2.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.resample(time="3M").sum(skipna=False) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 6.0 nan + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> ds.resample(time="3M").sum(skipna=True, min_count=2) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 nan 6.0 nan + + See Also + -------- + numpy.sum + Dataset.sum + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.sum, + dim=dim, + skipna=skipna, + min_count=min_count, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def std( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``std`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``std``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``std`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``std`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").std() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 0.0 0.8165 0.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.resample(time="3M").std(skipna=False) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 0.0 0.8165 nan + + See Also + -------- + numpy.std + Dataset.std + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.std, + dim=dim, + skipna=skipna, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def var( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``var`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``var``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``var`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``var`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").var() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 0.0 0.6667 0.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.resample(time="3M").var(skipna=False) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 0.0 0.6667 nan + + See Also + -------- + numpy.var + Dataset.var + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.var, + dim=dim, + skipna=skipna, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + def median( + self: DatasetReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_Dataset: + """ + Reduce this Dataset's data by applying ``median`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``median``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``median`` on this object's data. + + Returns + ------- + reduced : Dataset + New Dataset with ``median`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> ds = xr.Dataset(dict(da=da)) + >>> ds + + Dimensions: (time: 6) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> ds.resample(time="3M").median() + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 2.0 2.0 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> ds.resample(time="3M").median(skipna=False) + + Dimensions: (time: 3) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + Data variables: + da (time) float64 1.0 2.0 nan + + See Also + -------- + numpy.median + Dataset.median + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.median, + dim=dim, + skipna=skipna, + numeric_only=True, + keep_attrs=keep_attrs, + **kwargs, + ) + + +class DataArrayReduce(Protocol): + def reduce( + self, + func: Callable[..., Any], + dim: Union[None, Hashable, Sequence[Hashable]] = None, + axis: Union[None, int, Sequence[int]] = None, + keep_attrs: bool = None, + keepdims: bool = False, + **kwargs: Any, + ) -> T_DataArray: + ... + + +class DataArrayGroupByReductions: + __slots__ = () + + def count( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``count`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``count``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``count`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``count`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").count() + + array([1, 2, 2]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.count + DataArray.count + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.count, + dim=dim, + keep_attrs=keep_attrs, + **kwargs, + ) + + def all( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``all`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``all``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``all`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``all`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([True, True, True, True, True, False], dtype=bool), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ True, True, True, True, True, False]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").all() + + array([False, True, True]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.all + DataArray.all + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.array_all, + dim=dim, + keep_attrs=keep_attrs, + **kwargs, + ) + + def any( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``any`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``any``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``any`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``any`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([True, True, True, True, True, False], dtype=bool), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ True, True, True, True, True, False]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").any() + + array([ True, True, True]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.any + DataArray.any + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.array_any, + dim=dim, + keep_attrs=keep_attrs, + **kwargs, + ) + + def max( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``max`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``max``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``max`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``max`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").max() + + array([1., 2., 3.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.groupby("labels").max(skipna=False) + + array([nan, 2., 3.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.max + DataArray.max + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.max, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def min( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``min`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``min``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``min`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``min`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").min() + + array([1., 2., 1.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.groupby("labels").min(skipna=False) + + array([nan, 2., 1.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.min + DataArray.min + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.min, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def mean( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``mean`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``mean``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``mean`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``mean`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").mean() + + array([1., 2., 2.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.groupby("labels").mean(skipna=False) + + array([nan, 2., 2.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.mean + DataArray.mean + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.mean, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def prod( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + min_count: Optional[int] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``prod`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``prod``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``prod`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``prod`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").prod() + + array([1., 4., 3.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.groupby("labels").prod(skipna=False) + + array([nan, 4., 3.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> da.groupby("labels").prod(skipna=True, min_count=2) + + array([nan, 4., 3.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.prod + DataArray.prod + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.prod, + dim=dim, + skipna=skipna, + min_count=min_count, + keep_attrs=keep_attrs, + **kwargs, + ) + + def sum( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + min_count: Optional[int] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``sum`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``sum``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``sum`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``sum`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").sum() + + array([1., 4., 4.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.groupby("labels").sum(skipna=False) + + array([nan, 4., 4.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> da.groupby("labels").sum(skipna=True, min_count=2) + + array([nan, 4., 4.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.sum + DataArray.sum + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.sum, + dim=dim, + skipna=skipna, + min_count=min_count, + keep_attrs=keep_attrs, + **kwargs, + ) + + def std( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``std`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``std``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``std`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``std`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").std() + + array([0., 0., 1.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.groupby("labels").std(skipna=False) + + array([nan, 0., 1.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.std + DataArray.std + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.std, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def var( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``var`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``var``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``var`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``var`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").var() + + array([0., 0., 1.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.groupby("labels").var(skipna=False) + + array([nan, 0., 1.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.var + DataArray.var + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.var, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def median( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``median`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``median``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``median`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``median`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.groupby("labels").median() + + array([1., 2., 2.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.groupby("labels").median(skipna=False) + + array([nan, 2., 2.]) + Coordinates: + * labels (labels) object 'a' 'b' 'c' + + See Also + -------- + numpy.median + DataArray.median + :ref:`groupby` + User guide on groupby operations. + """ + return self.reduce( + duck_array_ops.median, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + +class DataArrayResampleReductions: + __slots__ = () + + def count( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``count`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``count``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``count`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``count`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").count() + + array([1, 3, 1]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.count + DataArray.count + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.count, + dim=dim, + keep_attrs=keep_attrs, + **kwargs, + ) + + def all( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``all`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``all``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``all`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``all`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([True, True, True, True, True, False], dtype=bool), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ True, True, True, True, True, False]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").all() + + array([ True, True, False]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.all + DataArray.all + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.array_all, + dim=dim, + keep_attrs=keep_attrs, + **kwargs, + ) + + def any( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``any`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``any``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``any`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``any`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([True, True, True, True, True, False], dtype=bool), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ True, True, True, True, True, False]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").any() + + array([ True, True, True]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.any + DataArray.any + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.array_any, + dim=dim, + keep_attrs=keep_attrs, + **kwargs, + ) + + def max( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``max`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``max``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``max`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``max`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").max() + + array([1., 3., 2.]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.resample(time="3M").max(skipna=False) + + array([ 1., 3., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.max + DataArray.max + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.max, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def min( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``min`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``min``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``min`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``min`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").min() + + array([1., 1., 2.]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.resample(time="3M").min(skipna=False) + + array([ 1., 1., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.min + DataArray.min + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.min, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def mean( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``mean`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``mean``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``mean`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``mean`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").mean() + + array([1., 2., 2.]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.resample(time="3M").mean(skipna=False) + + array([ 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.mean + DataArray.mean + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.mean, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def prod( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + min_count: Optional[int] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``prod`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``prod``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``prod`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``prod`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").prod() + + array([1., 6., 2.]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.resample(time="3M").prod(skipna=False) + + array([ 1., 6., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> da.resample(time="3M").prod(skipna=True, min_count=2) + + array([nan, 6., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.prod + DataArray.prod + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.prod, + dim=dim, + skipna=skipna, + min_count=min_count, + keep_attrs=keep_attrs, + **kwargs, + ) + + def sum( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + min_count: Optional[int] = None, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``sum`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``sum``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array. + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``sum`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``sum`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").sum() + + array([1., 6., 2.]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.resample(time="3M").sum(skipna=False) + + array([ 1., 6., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> da.resample(time="3M").sum(skipna=True, min_count=2) + + array([nan, 6., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.sum + DataArray.sum + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.sum, + dim=dim, + skipna=skipna, + min_count=min_count, + keep_attrs=keep_attrs, + **kwargs, + ) + + def std( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``std`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``std``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``std`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``std`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").std() + + array([0. , 0.81649658, 0. ]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.resample(time="3M").std(skipna=False) + + array([0. , 0.81649658, nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.std + DataArray.std + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.std, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def var( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``var`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``var``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``var`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``var`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").var() + + array([0. , 0.66666667, 0. ]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.resample(time="3M").var(skipna=False) + + array([0. , 0.66666667, nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.var + DataArray.var + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.var, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) + + def median( + self: DataArrayReduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None, + skipna: bool = True, + keep_attrs: bool = None, + **kwargs, + ) -> T_DataArray: + """ + Reduce this DataArray's data by applying ``median`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``median``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. If ``None``, will reduce over all dimensions + present in the grouped variable. + skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64). + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``median`` on this object's data. + + Returns + ------- + reduced : DataArray + New DataArray with ``median`` applied to its data and the + indicated dimension(s) removed + + Examples + -------- + >>> da = xr.DataArray( + ... np.array([1, 2, 3, 1, 2, np.nan]), + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... ) + >>> da + + array([ 1., 2., 3., 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-02-28 ... 2001-06-30 + labels (time) >> da.resample(time="3M").median() + + array([1., 2., 2.]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + Use ``skipna`` to control whether NaNs are ignored. + + >>> da.resample(time="3M").median(skipna=False) + + array([ 1., 2., nan]) + Coordinates: + * time (time) datetime64[ns] 2001-01-31 2001-04-30 2001-07-31 + + See Also + -------- + numpy.median + DataArray.median + :ref:`resampling` + User guide on resampling operations. + """ + return self.reduce( + duck_array_ops.median, + dim=dim, + skipna=skipna, + keep_attrs=keep_attrs, + **kwargs, + ) diff --git a/xarray/core/arithmetic.py b/xarray/core/arithmetic.py index 27ec5ab8dd9..814e9a59877 100644 --- a/xarray/core/arithmetic.py +++ b/xarray/core/arithmetic.py @@ -128,8 +128,6 @@ class DataArrayArithmetic( class DataArrayGroupbyArithmetic( - ImplementsArrayReduce, - IncludeReduceMethods, SupportsArithmetic, DataArrayGroupByOpsMixin, ): @@ -137,8 +135,6 @@ class DataArrayGroupbyArithmetic( class DatasetGroupbyArithmetic( - ImplementsDatasetReduce, - IncludeReduceMethods, SupportsArithmetic, DatasetGroupByOpsMixin, ): diff --git a/xarray/core/groupby.py b/xarray/core/groupby.py index 1ca5de965d0..185b4ae5bec 100644 --- a/xarray/core/groupby.py +++ b/xarray/core/groupby.py @@ -5,6 +5,7 @@ import pandas as pd from . import dtypes, duck_array_ops, nputils, ops +from ._reductions import DataArrayGroupByReductions, DatasetGroupByReductions from .arithmetic import DataArrayGroupbyArithmetic, DatasetGroupbyArithmetic from .concat import concat from .formatting import format_array_flat @@ -712,7 +713,7 @@ def _maybe_reorder(xarray_obj, dim, positions): return xarray_obj[{dim: order}] -class DataArrayGroupBy(GroupBy, DataArrayGroupbyArithmetic): +class DataArrayGroupByBase(GroupBy, DataArrayGroupbyArithmetic): """GroupBy object specialized to grouping DataArray objects""" __slots__ = () @@ -877,7 +878,11 @@ def reduce_array(ar): return self.map(reduce_array, shortcut=shortcut) -class DatasetGroupBy(GroupBy, DatasetGroupbyArithmetic): +class DataArrayGroupBy(DataArrayGroupByBase, DataArrayGroupByReductions): + __slots__ = () + + +class DatasetGroupByBase(GroupBy, DatasetGroupbyArithmetic): __slots__ = () @@ -994,3 +999,7 @@ def assign(self, **kwargs): Dataset.assign """ return self.map(lambda ds: ds.assign(**kwargs)) + + +class DatasetGroupBy(DatasetGroupByBase, DatasetGroupByReductions): + __slots__ = () diff --git a/xarray/core/resample.py b/xarray/core/resample.py index c7749a7e5ca..e2f599e8b4e 100644 --- a/xarray/core/resample.py +++ b/xarray/core/resample.py @@ -1,6 +1,7 @@ import warnings -from .groupby import DataArrayGroupBy, DatasetGroupBy +from ._reductions import DataArrayResampleReductions, DatasetResampleReductions +from .groupby import DataArrayGroupByBase, DatasetGroupByBase RESAMPLE_DIM = "__resample_dim__" @@ -156,7 +157,7 @@ def _interpolate(self, kind="linear"): ) -class DataArrayResample(DataArrayGroupBy, Resample): +class DataArrayResample(DataArrayResampleReductions, DataArrayGroupByBase, Resample): """DataArrayGroupBy object specialized to time resampling operations over a specified dimension """ @@ -247,7 +248,7 @@ def apply(self, func, args=(), shortcut=None, **kwargs): return self.map(func=func, shortcut=shortcut, args=args, **kwargs) -class DatasetResample(DatasetGroupBy, Resample): +class DatasetResample(DatasetResampleReductions, DatasetGroupByBase, Resample): """DatasetGroupBy object specialized to resampling a specified dimension""" def __init__(self, *args, dim=None, resample_dim=None, **kwargs): diff --git a/xarray/util/generate_reductions.py b/xarray/util/generate_reductions.py new file mode 100644 index 00000000000..72449195d1e --- /dev/null +++ b/xarray/util/generate_reductions.py @@ -0,0 +1,296 @@ +"""Generate module and stub file for arithmetic operators of various xarray classes. + +For internal xarray development use only. + +Usage: + python xarray/util/generate_reductions.py > xarray/core/_reductions.py + pytest --doctest-modules xarray/core/_reductions.py --accept || true + pytest --doctest-modules xarray/core/_reductions.py --accept + +This requires [pytest-accept](https://github.com/max-sixty/pytest-accept). +The second run of pytest is deliberate, since the first will return an error +while replacing the doctests. + +""" + +import collections +import textwrap +from functools import partial +from typing import Callable, Optional + +MODULE_PREAMBLE = '''\ +"""Mixin classes with reduction operations.""" +# This file was generated using xarray.util.generate_reductions. Do not edit manually. + +import sys +from typing import Any, Callable, Hashable, Optional, Sequence, Union + +from . import duck_array_ops +from .types import T_DataArray, T_Dataset + +if sys.version_info >= (3, 8): + from typing import Protocol +else: + from typing_extensions import Protocol''' + +OBJ_PREAMBLE = """ + +class {obj}Reduce(Protocol): + def reduce( + self, + func: Callable[..., Any], + dim: Union[None, Hashable, Sequence[Hashable]] = None, + axis: Union[None, int, Sequence[int]] = None, + keep_attrs: bool = None, + keepdims: bool = False, + **kwargs: Any, + ) -> T_{obj}: + ...""" + + +CLASS_PREAMBLE = """ + +class {obj}{cls}Reductions: + __slots__ = ()""" + +_SKIPNA_DOCSTRING = """ +skipna : bool, optional + If True, skip missing values (as marked by NaN). By default, only + skips missing values for float dtypes; other dtypes either do not + have a sentinel missing value (int) or skipna=True has not been + implemented (object, datetime64 or timedelta64).""" + +_MINCOUNT_DOCSTRING = """ +min_count : int, default: None + The required number of valid values to perform the operation. If + fewer than min_count non-NA values are present the result will be + NA. Only used if skipna is set to True or defaults to True for the + array's dtype. Changed in version 0.17.0: if specified on an integer + array and skipna=True, the result will be a float array.""" + + +BOOL_REDUCE_METHODS = ["all", "any"] +NAN_REDUCE_METHODS = [ + "max", + "min", + "mean", + "prod", + "sum", + "std", + "var", + "median", +] +NAN_CUM_METHODS = ["cumsum", "cumprod"] +MIN_COUNT_METHODS = ["prod", "sum"] +NUMERIC_ONLY_METHODS = [ + "mean", + "std", + "var", + "sum", + "prod", + "median", + "cumsum", + "cumprod", +] + +TEMPLATE_REDUCTION = ''' + def {method}( + self: {obj}Reduce, + dim: Union[None, Hashable, Sequence[Hashable]] = None,{skip_na.kwarg}{min_count.kwarg} + keep_attrs: bool = None, + **kwargs, + ) -> T_{obj}: + """ + Reduce this {obj}'s data by applying ``{method}`` along some dimension(s). + + Parameters + ---------- + dim : hashable or iterable of hashable, optional + Name of dimension[s] along which to apply ``{method}``. For e.g. ``dim="x"`` + or ``dim=["x", "y"]``. {extra_dim}{extra_args}{skip_na.docs}{min_count.docs} + keep_attrs : bool, optional + If True, ``attrs`` will be copied from the original + object to the new one. If False (default), the new object will be + returned without attributes. + **kwargs : dict + Additional keyword arguments passed on to the appropriate array + function for calculating ``{method}`` on this object's data. + + Returns + ------- + reduced : {obj} + New {obj} with ``{method}`` applied to its data and the + indicated dimension(s) removed + + Examples + --------{example} + + See Also + -------- + numpy.{method} + {obj}.{method} + :ref:`{docref}` + User guide on {docref} operations. + """ + return self.reduce( + duck_array_ops.{array_method}, + dim=dim,{skip_na.call}{min_count.call}{numeric_only_call} + keep_attrs=keep_attrs, + **kwargs, + )''' + + +def generate_groupby_example(obj: str, cls: str, method: str): + """Generate examples for method.""" + dx = "ds" if obj == "Dataset" else "da" + if cls == "Resample": + calculation = f'{dx}.resample(time="3M").{method}' + elif cls == "GroupBy": + calculation = f'{dx}.groupby("labels").{method}' + else: + raise ValueError + + if method in BOOL_REDUCE_METHODS: + np_array = """ + ... np.array([True, True, True, True, True, False], dtype=bool),""" + + else: + np_array = """ + ... np.array([1, 2, 3, 1, 2, np.nan]),""" + + create_da = f""" + >>> da = xr.DataArray({np_array} + ... dims="time", + ... coords=dict( + ... time=("time", pd.date_range("01-01-2001", freq="M", periods=6)), + ... labels=("time", np.array(["a", "b", "c", "c", "b", "a"])), + ... ), + ... )""" + + if obj == "Dataset": + maybe_dataset = """ + >>> ds = xr.Dataset(dict(da=da)) + >>> ds""" + else: + maybe_dataset = """ + >>> da""" + + if method in NAN_REDUCE_METHODS: + maybe_skipna = f""" + + Use ``skipna`` to control whether NaNs are ignored. + + >>> {calculation}(skipna=False)""" + else: + maybe_skipna = "" + + if method in MIN_COUNT_METHODS: + maybe_mincount = f""" + + Specify ``min_count`` for finer control over when NaNs are ignored. + + >>> {calculation}(skipna=True, min_count=2)""" + else: + maybe_mincount = "" + + return f"""{create_da}{maybe_dataset} + + >>> {calculation}(){maybe_skipna}{maybe_mincount}""" + + +def generate_method( + obj: str, + docref: str, + method: str, + skipna: bool, + example_generator: Callable, + array_method: Optional[str] = None, +): + if not array_method: + array_method = method + + if obj == "Dataset": + if method in NUMERIC_ONLY_METHODS: + numeric_only_call = "\n numeric_only=True," + else: + numeric_only_call = "\n numeric_only=False," + else: + numeric_only_call = "" + + kwarg = collections.namedtuple("kwarg", "docs kwarg call") + if skipna: + skip_na = kwarg( + docs=textwrap.indent(_SKIPNA_DOCSTRING, " "), + kwarg="\n skipna: bool = True,", + call="\n skipna=skipna,", + ) + else: + skip_na = kwarg(docs="", kwarg="", call="") + + if method in MIN_COUNT_METHODS: + min_count = kwarg( + docs=textwrap.indent(_MINCOUNT_DOCSTRING, " "), + kwarg="\n min_count: Optional[int] = None,", + call="\n min_count=min_count,", + ) + else: + min_count = kwarg(docs="", kwarg="", call="") + + return TEMPLATE_REDUCTION.format( + obj=obj, + docref=docref, + method=method, + array_method=array_method, + extra_dim="""If ``None``, will reduce over all dimensions + present in the grouped variable.""", + extra_args="", + skip_na=skip_na, + min_count=min_count, + numeric_only_call=numeric_only_call, + example=example_generator(obj=obj, method=method), + ) + + +def render(obj: str, cls: str, docref: str, example_generator: Callable): + yield CLASS_PREAMBLE.format(obj=obj, cls=cls) + yield generate_method( + obj, + method="count", + docref=docref, + skipna=False, + example_generator=example_generator, + ) + for method in BOOL_REDUCE_METHODS: + yield generate_method( + obj, + method=method, + docref=docref, + skipna=False, + array_method=f"array_{method}", + example_generator=example_generator, + ) + for method in NAN_REDUCE_METHODS: + yield generate_method( + obj, + method=method, + docref=docref, + skipna=True, + example_generator=example_generator, + ) + + +if __name__ == "__main__": + print(MODULE_PREAMBLE) + for obj in ["Dataset", "DataArray"]: + print(OBJ_PREAMBLE.format(obj=obj)) + for cls, docref in ( + ("GroupBy", "groupby"), + ("Resample", "resampling"), + ): + for line in render( + obj=obj, + cls=cls, + docref=docref, + example_generator=partial(generate_groupby_example, cls=cls), + ): + print(line)