Skip to content

Commit

Permalink
Add .cumulative to cumsum & cumprod docstrings (#9533)
Browse files Browse the repository at this point in the history 
* 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 <dcherian@users.noreply.github.com>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Deepak Cherian <dcherian@users.noreply.github.com>
  • Loading branch information
@max-sixty @pre-commit-ci @dcherian
3 people authored Oct 3, 2024
1 parent 8c1c31a commit e227c0b
Show file tree
Hide file tree
Showing 3 changed files with 111 additions and 10 deletions.
60 changes: 60 additions & 0 deletions xarray/core/_aggregations.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1069,13 +1069,18 @@ def cumsum(
numpy.cumsum
dask.array.cumsum
DataArray.cumsum
Dataset.cumulative
:ref:`agg`
User guide on reduction or aggregation operations.
Notes
-----
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -1162,13 +1167,18 @@ def cumprod(
numpy.cumprod
dask.array.cumprod
DataArray.cumprod
Dataset.cumulative
:ref:`agg`
User guide on reduction or aggregation operations.
Notes
-----
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -2175,13 +2185,18 @@ def cumsum(
numpy.cumsum
dask.array.cumsum
Dataset.cumsum
DataArray.cumulative
:ref:`agg`
User guide on reduction or aggregation operations.
Notes
-----
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -2264,13 +2279,18 @@ def cumprod(
numpy.cumprod
dask.array.cumprod
Dataset.cumprod
DataArray.cumulative
:ref:`agg`
User guide on reduction or aggregation operations.
Notes
-----
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -3644,6 +3664,7 @@ def cumsum(
numpy.cumsum
dask.array.cumsum
Dataset.cumsum
Dataset.cumulative
:ref:`groupby`
User guide on groupby operations.
Expand All @@ -3656,6 +3677,10 @@ def cumsum(
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -3743,6 +3768,7 @@ def cumprod(
numpy.cumprod
dask.array.cumprod
Dataset.cumprod
Dataset.cumulative
:ref:`groupby`
User guide on groupby operations.
Expand All @@ -3755,6 +3781,10 @@ def cumprod(
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -5132,6 +5162,7 @@ def cumsum(
numpy.cumsum
dask.array.cumsum
Dataset.cumsum
Dataset.cumulative
:ref:`resampling`
User guide on resampling operations.
Expand All @@ -5144,6 +5175,10 @@ def cumsum(
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -5231,6 +5266,7 @@ def cumprod(
numpy.cumprod
dask.array.cumprod
Dataset.cumprod
Dataset.cumulative
:ref:`resampling`
User guide on resampling operations.
Expand All @@ -5243,6 +5279,10 @@ def cumprod(
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -6520,6 +6560,7 @@ def cumsum(
numpy.cumsum
dask.array.cumsum
DataArray.cumsum
DataArray.cumulative
:ref:`groupby`
User guide on groupby operations.
Expand All @@ -6532,6 +6573,10 @@ def cumsum(
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -6615,6 +6660,7 @@ def cumprod(
numpy.cumprod
dask.array.cumprod
DataArray.cumprod
DataArray.cumulative
:ref:`groupby`
User guide on groupby operations.
Expand All @@ -6627,6 +6673,10 @@ def cumprod(
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -7900,6 +7950,7 @@ def cumsum(
numpy.cumsum
dask.array.cumsum
DataArray.cumsum
DataArray.cumulative
:ref:`resampling`
User guide on resampling operations.
Expand All @@ -7912,6 +7963,10 @@ def cumsum(
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down Expand Up @@ -7995,6 +8050,7 @@ def cumprod(
numpy.cumprod
dask.array.cumprod
DataArray.cumprod
DataArray.cumulative
:ref:`resampling`
User guide on resampling operations.
Expand All @@ -8007,6 +8063,10 @@ def cumprod(
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> da = xr.DataArray(
Expand Down
10 changes: 10 additions & 0 deletions xarray/namedarray/_aggregations.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -842,13 +842,18 @@ def cumsum(
dask.array.cumsum
Dataset.cumsum
DataArray.cumsum
NamedArray.cumulative
:ref:`agg`
User guide on reduction or aggregation operations.
Notes
-----
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> from xarray.namedarray.core import NamedArray
Expand Down Expand Up @@ -914,13 +919,18 @@ def cumprod(
dask.array.cumprod
Dataset.cumprod
DataArray.cumprod
NamedArray.cumulative
:ref:`agg`
User guide on reduction or aggregation operations.
Notes
-----
Non-numeric variables will be removed prior to reducing.
Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future.
Examples
--------
>>> from xarray.namedarray.core import NamedArray
Expand Down
51 changes: 41 additions & 10 deletions xarray/util/generate_aggregations.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
Usage:
python xarray/util/generate_aggregations.py
pytest --doctest-modules xarray/core/_aggregations.py --accept || true
pytest --doctest-modules xarray/core/_aggregations.py
pytest --doctest-modules xarray/{core,namedarray}/_aggregations.py --accept || true
pytest --doctest-modules xarray/{core,namedarray}/_aggregations.py
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
Expand All @@ -24,8 +24,8 @@
from __future__ import annotations
from collections.abc import Sequence
from typing import TYPE_CHECKING, Any, Callable
from collections.abc import Callable, Sequence
from typing import TYPE_CHECKING, Any
from xarray.core import duck_array_ops
from xarray.core.options import OPTIONS
Expand All @@ -45,8 +45,8 @@
from __future__ import annotations
from collections.abc import Sequence
from typing import Any, Callable
from collections.abc import Callable, Sequence
from typing import Any
from xarray.core import duck_array_ops
from xarray.core.types import Dims, Self
Expand Down Expand Up @@ -223,6 +223,9 @@ def {method}(
See the `flox documentation <https://flox.readthedocs.io>`_ for more."""
_FLOX_GROUPBY_NOTES = _FLOX_NOTES_TEMPLATE.format(kind="groupby")
_FLOX_RESAMPLE_NOTES = _FLOX_NOTES_TEMPLATE.format(kind="resampling")
_CUM_NOTES = """Note that the methods on the ``cumulative`` method are more performant (with numbagg installed)
and better supported. ``cumsum`` and ``cumprod`` may be deprecated
in the future."""

ExtraKwarg = collections.namedtuple("ExtraKwarg", "docs kwarg call example")
skipna = ExtraKwarg(
Expand Down Expand Up @@ -271,13 +274,17 @@ def __init__(
extra_kwargs=tuple(),
numeric_only=False,
see_also_modules=("numpy", "dask.array"),
see_also_methods=(),
min_flox_version=None,
additional_notes="",
):
self.name = name
self.extra_kwargs = extra_kwargs
self.numeric_only = numeric_only
self.see_also_modules = see_also_modules
self.see_also_methods = see_also_methods
self.min_flox_version = min_flox_version
self.additional_notes = additional_notes
if bool_reduce:
self.array_method = f"array_{name}"
self.np_example_array = """
Expand Down Expand Up @@ -315,7 +322,7 @@ def generate_methods(self):
for method in self.methods:
yield self.generate_method(method)

def generate_method(self, method):
def generate_method(self, method: Method):
has_kw_only = method.extra_kwargs or self.has_keep_attrs

template_kwargs = dict(
Expand Down Expand Up @@ -360,10 +367,17 @@ def generate_method(self, method):
if self.cls == ""
else (self.datastructure.name,)
)
see_also_methods = "\n".join(
see_also_methods_from_modules = (
" " * 8 + f"{mod}.{method.name}"
for mod in (method.see_also_modules + others)
)
see_also_methods_from_methods = (
" " * 8 + f"{self.datastructure.name}.{method}"
for method in method.see_also_methods
)
see_also_methods = "\n".join(
[*see_also_methods_from_modules, *see_also_methods_from_methods]
)
# Fixes broken links mentioned in #8055
yield TEMPLATE_SEE_ALSO.format(
**template_kwargs,
Expand All @@ -378,6 +392,11 @@ def generate_method(self, method):
notes += "\n\n"
notes += _NUMERIC_ONLY_NOTES

if method.additional_notes:
if notes != "":
notes += "\n\n"
notes += method.additional_notes

if notes != "":
yield TEMPLATE_NOTES.format(notes=textwrap.indent(notes, 8 * " "))

Expand Down Expand Up @@ -505,8 +524,20 @@ def generate_code(self, method, has_keep_attrs):
"median", extra_kwargs=(skipna,), numeric_only=True, min_flox_version="0.9.2"
),
# Cumulatives:
Method("cumsum", extra_kwargs=(skipna,), numeric_only=True),
Method("cumprod", extra_kwargs=(skipna,), numeric_only=True),
Method(
"cumsum",
extra_kwargs=(skipna,),
numeric_only=True,
see_also_methods=("cumulative",),
additional_notes=_CUM_NOTES,
),
Method(
"cumprod",
extra_kwargs=(skipna,),
numeric_only=True,
see_also_methods=("cumulative",),
additional_notes=_CUM_NOTES,
),
)


Expand Down

0 comments on commit e227c0b

Please sign in to comment.