Skip to content

Commit e227c0b

Browse files
max-sixtypre-commit-ci[bot]dcherian
authored
Add .cumulative to cumsum & cumprod docstrings (#9533)
* Remove doctests so we can work with it * Add generated docstrings * Add generated doctest outputs * Update docs for running generations * add named array generations * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * . * Update xarray/util/generate_aggregations.py Co-authored-by: Deepak Cherian <[email protected]> --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Deepak Cherian <[email protected]>
1 parent 8c1c31a commit e227c0b

File tree

3 files changed

+111
-10
lines changed

3 files changed

+111
-10
lines changed

‎xarray/core/_aggregations.py‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1069,13 +1069,18 @@ def cumsum(
10691069
numpy.cumsum
10701070
dask.array.cumsum
10711071
DataArray.cumsum
1072+
Dataset.cumulative
10721073
:ref:`agg`
10731074
User guide on reduction or aggregation operations.
10741075
10751076
Notes
10761077
-----
10771078
Non-numeric variables will be removed prior to reducing.
10781079
1080+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
1081+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
1082+
in the future.
1083+
10791084
Examples
10801085
--------
10811086
>>> da = xr.DataArray(
@@ -1162,13 +1167,18 @@ def cumprod(
11621167
numpy.cumprod
11631168
dask.array.cumprod
11641169
DataArray.cumprod
1170+
Dataset.cumulative
11651171
:ref:`agg`
11661172
User guide on reduction or aggregation operations.
11671173
11681174
Notes
11691175
-----
11701176
Non-numeric variables will be removed prior to reducing.
11711177
1178+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
1179+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
1180+
in the future.
1181+
11721182
Examples
11731183
--------
11741184
>>> da = xr.DataArray(
@@ -2175,13 +2185,18 @@ def cumsum(
21752185
numpy.cumsum
21762186
dask.array.cumsum
21772187
Dataset.cumsum
2188+
DataArray.cumulative
21782189
:ref:`agg`
21792190
User guide on reduction or aggregation operations.
21802191
21812192
Notes
21822193
-----
21832194
Non-numeric variables will be removed prior to reducing.
21842195
2196+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
2197+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
2198+
in the future.
2199+
21852200
Examples
21862201
--------
21872202
>>> da = xr.DataArray(
@@ -2264,13 +2279,18 @@ def cumprod(
22642279
numpy.cumprod
22652280
dask.array.cumprod
22662281
Dataset.cumprod
2282+
DataArray.cumulative
22672283
:ref:`agg`
22682284
User guide on reduction or aggregation operations.
22692285
22702286
Notes
22712287
-----
22722288
Non-numeric variables will be removed prior to reducing.
22732289
2290+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
2291+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
2292+
in the future.
2293+
22742294
Examples
22752295
--------
22762296
>>> da = xr.DataArray(
@@ -3644,6 +3664,7 @@ def cumsum(
36443664
numpy.cumsum
36453665
dask.array.cumsum
36463666
Dataset.cumsum
3667+
Dataset.cumulative
36473668
:ref:`groupby`
36483669
User guide on groupby operations.
36493670
@@ -3656,6 +3677,10 @@ def cumsum(
36563677
36573678
Non-numeric variables will be removed prior to reducing.
36583679
3680+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
3681+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
3682+
in the future.
3683+
36593684
Examples
36603685
--------
36613686
>>> da = xr.DataArray(
@@ -3743,6 +3768,7 @@ def cumprod(
37433768
numpy.cumprod
37443769
dask.array.cumprod
37453770
Dataset.cumprod
3771+
Dataset.cumulative
37463772
:ref:`groupby`
37473773
User guide on groupby operations.
37483774
@@ -3755,6 +3781,10 @@ def cumprod(
37553781
37563782
Non-numeric variables will be removed prior to reducing.
37573783
3784+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
3785+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
3786+
in the future.
3787+
37583788
Examples
37593789
--------
37603790
>>> da = xr.DataArray(
@@ -5132,6 +5162,7 @@ def cumsum(
51325162
numpy.cumsum
51335163
dask.array.cumsum
51345164
Dataset.cumsum
5165+
Dataset.cumulative
51355166
:ref:`resampling`
51365167
User guide on resampling operations.
51375168
@@ -5144,6 +5175,10 @@ def cumsum(
51445175
51455176
Non-numeric variables will be removed prior to reducing.
51465177
5178+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
5179+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
5180+
in the future.
5181+
51475182
Examples
51485183
--------
51495184
>>> da = xr.DataArray(
@@ -5231,6 +5266,7 @@ def cumprod(
52315266
numpy.cumprod
52325267
dask.array.cumprod
52335268
Dataset.cumprod
5269+
Dataset.cumulative
52345270
:ref:`resampling`
52355271
User guide on resampling operations.
52365272
@@ -5243,6 +5279,10 @@ def cumprod(
52435279
52445280
Non-numeric variables will be removed prior to reducing.
52455281
5282+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
5283+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
5284+
in the future.
5285+
52465286
Examples
52475287
--------
52485288
>>> da = xr.DataArray(
@@ -6520,6 +6560,7 @@ def cumsum(
65206560
numpy.cumsum
65216561
dask.array.cumsum
65226562
DataArray.cumsum
6563+
DataArray.cumulative
65236564
:ref:`groupby`
65246565
User guide on groupby operations.
65256566
@@ -6532,6 +6573,10 @@ def cumsum(
65326573
65336574
Non-numeric variables will be removed prior to reducing.
65346575
6576+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
6577+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
6578+
in the future.
6579+
65356580
Examples
65366581
--------
65376582
>>> da = xr.DataArray(
@@ -6615,6 +6660,7 @@ def cumprod(
66156660
numpy.cumprod
66166661
dask.array.cumprod
66176662
DataArray.cumprod
6663+
DataArray.cumulative
66186664
:ref:`groupby`
66196665
User guide on groupby operations.
66206666
@@ -6627,6 +6673,10 @@ def cumprod(
66276673
66286674
Non-numeric variables will be removed prior to reducing.
66296675
6676+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
6677+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
6678+
in the future.
6679+
66306680
Examples
66316681
--------
66326682
>>> da = xr.DataArray(
@@ -7900,6 +7950,7 @@ def cumsum(
79007950
numpy.cumsum
79017951
dask.array.cumsum
79027952
DataArray.cumsum
7953+
DataArray.cumulative
79037954
:ref:`resampling`
79047955
User guide on resampling operations.
79057956
@@ -7912,6 +7963,10 @@ def cumsum(
79127963
79137964
Non-numeric variables will be removed prior to reducing.
79147965
7966+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
7967+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
7968+
in the future.
7969+
79157970
Examples
79167971
--------
79177972
>>> da = xr.DataArray(
@@ -7995,6 +8050,7 @@ def cumprod(
79958050
numpy.cumprod
79968051
dask.array.cumprod
79978052
DataArray.cumprod
8053+
DataArray.cumulative
79988054
:ref:`resampling`
79998055
User guide on resampling operations.
80008056
@@ -8007,6 +8063,10 @@ def cumprod(
80078063
80088064
Non-numeric variables will be removed prior to reducing.
80098065
8066+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
8067+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
8068+
in the future.
8069+
80108070
Examples
80118071
--------
80128072
>>> da = xr.DataArray(

‎xarray/namedarray/_aggregations.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -842,13 +842,18 @@ def cumsum(
842842
dask.array.cumsum
843843
Dataset.cumsum
844844
DataArray.cumsum
845+
NamedArray.cumulative
845846
:ref:`agg`
846847
User guide on reduction or aggregation operations.
847848
848849
Notes
849850
-----
850851
Non-numeric variables will be removed prior to reducing.
851852
853+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
854+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
855+
in the future.
856+
852857
Examples
853858
--------
854859
>>> from xarray.namedarray.core import NamedArray
@@ -914,13 +919,18 @@ def cumprod(
914919
dask.array.cumprod
915920
Dataset.cumprod
916921
DataArray.cumprod
922+
NamedArray.cumulative
917923
:ref:`agg`
918924
User guide on reduction or aggregation operations.
919925
920926
Notes
921927
-----
922928
Non-numeric variables will be removed prior to reducing.
923929
930+
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
931+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
932+
in the future.
933+
924934
Examples
925935
--------
926936
>>> from xarray.namedarray.core import NamedArray

‎xarray/util/generate_aggregations.py‎

Lines changed: 41 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
55
Usage:
66
python xarray/util/generate_aggregations.py
7-
pytest --doctest-modules xarray/core/_aggregations.py --accept || true
8-
pytest --doctest-modules xarray/core/_aggregations.py
7+
pytest --doctest-modules xarray/{core,namedarray}/_aggregations.py --accept || true
8+
pytest --doctest-modules xarray/{core,namedarray}/_aggregations.py
99
1010
This requires [pytest-accept](https://github.com/max-sixty/pytest-accept).
1111
The second run of pytest is deliberate, since the first will return an error
@@ -24,8 +24,8 @@
2424
2525
from __future__ import annotations
2626
27-
from collections.abc import Sequence
28-
from typing import TYPE_CHECKING, Any, Callable
27+
from collections.abc import Callable, Sequence
28+
from typing import TYPE_CHECKING, Any
2929
3030
from xarray.core import duck_array_ops
3131
from xarray.core.options import OPTIONS
@@ -45,8 +45,8 @@
4545
4646
from __future__ import annotations
4747
48-
from collections.abc import Sequence
49-
from typing import Any, Callable
48+
from collections.abc import Callable, Sequence
49+
from typing import Any
5050
5151
from xarray.core import duck_array_ops
5252
from xarray.core.types import Dims, Self
@@ -223,6 +223,9 @@ def {method}(
223223
See the `flox documentation <https://flox.readthedocs.io>`_ for more."""
224224
_FLOX_GROUPBY_NOTES = _FLOX_NOTES_TEMPLATE.format(kind="groupby")
225225
_FLOX_RESAMPLE_NOTES = _FLOX_NOTES_TEMPLATE.format(kind="resampling")
226+
_CUM_NOTES = """Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
227+
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
228+
in the future."""
226229

227230
ExtraKwarg = collections.namedtuple("ExtraKwarg", "docs kwarg call example")
228231
skipna = ExtraKwarg(
@@ -271,13 +274,17 @@ def __init__(
271274
extra_kwargs=tuple(),
272275
numeric_only=False,
273276
see_also_modules=("numpy", "dask.array"),
277+
see_also_methods=(),
274278
min_flox_version=None,
279+
additional_notes="",
275280
):
276281
self.name = name
277282
self.extra_kwargs = extra_kwargs
278283
self.numeric_only = numeric_only
279284
self.see_also_modules = see_also_modules
285+
self.see_also_methods = see_also_methods
280286
self.min_flox_version = min_flox_version
287+
self.additional_notes = additional_notes
281288
if bool_reduce:
282289
self.array_method = f"array_{name}"
283290
self.np_example_array = """
@@ -315,7 +322,7 @@ def generate_methods(self):
315322
for method in self.methods:
316323
yield self.generate_method(method)
317324

318-
def generate_method(self, method):
325+
def generate_method(self, method: Method):
319326
has_kw_only = method.extra_kwargs or self.has_keep_attrs
320327

321328
template_kwargs = dict(
@@ -360,10 +367,17 @@ def generate_method(self, method):
360367
if self.cls == ""
361368
else (self.datastructure.name,)
362369
)
363-
see_also_methods = "\n".join(
370+
see_also_methods_from_modules = (
364371
" " * 8 + f"{mod}.{method.name}"
365372
for mod in (method.see_also_modules + others)
366373
)
374+
see_also_methods_from_methods = (
375+
" " * 8 + f"{self.datastructure.name}.{method}"
376+
for method in method.see_also_methods
377+
)
378+
see_also_methods = "\n".join(
379+
[*see_also_methods_from_modules, *see_also_methods_from_methods]
380+
)
367381
# Fixes broken links mentioned in #8055
368382
yield TEMPLATE_SEE_ALSO.format(
369383
**template_kwargs,
@@ -378,6 +392,11 @@ def generate_method(self, method):
378392
notes += "\n\n"
379393
notes += _NUMERIC_ONLY_NOTES
380394

395+
if method.additional_notes:
396+
if notes != "":
397+
notes += "\n\n"
398+
notes += method.additional_notes
399+
381400
if notes != "":
382401
yield TEMPLATE_NOTES.format(notes=textwrap.indent(notes, 8 * " "))
383402

@@ -505,8 +524,20 @@ def generate_code(self, method, has_keep_attrs):
505524
"median", extra_kwargs=(skipna,), numeric_only=True, min_flox_version="0.9.2"
506525
),
507526
# Cumulatives:
508-
Method("cumsum", extra_kwargs=(skipna,), numeric_only=True),
509-
Method("cumprod", extra_kwargs=(skipna,), numeric_only=True),
527+
Method(
528+
"cumsum",
529+
extra_kwargs=(skipna,),
530+
numeric_only=True,
531+
see_also_methods=("cumulative",),
532+
additional_notes=_CUM_NOTES,
533+
),
534+
Method(
535+
"cumprod",
536+
extra_kwargs=(skipna,),
537+
numeric_only=True,
538+
see_also_methods=("cumulative",),
539+
additional_notes=_CUM_NOTES,
540+
),
510541
)
511542

512543

0 commit comments

Comments
 (0)