DOC: Added examples to docstrings of DataArray methods (#7123)

[DanielGoman]

Added examples to the docstring of the following methods:

DataArray.drop_vars()
DataArray.reindex_like()
DataArray.interp_like()

I will gradually edit this PR and add more examples to other methods.
I'll gladly accept feedback to improve upon my work :)

[TomNicholas]

Great, thank you @DanielGoman !

You might also be interested to look at this other recent PR which also added some examples to DataArra methods. #7088

[max-sixty]

Excellent @DanielGoman !

(not to use xarray to tout my personal projects — but re the doctest failures — running https://github.com/max-sixty/pytest-accept over them will auto-fix them, if that's helpful)

[DanielGoman]

Thanks for the advice @max-sixty!

I performed doctests on my machine inside a conda venv following the Contributing Guide using Python 3.9, and passed the them.

Yet, it doesn't pass the github tests. Any ideas as to why that might be?

[headtr1ck]

I performed doctests on my machine inside a conda venv following the Contributing Guide using Python 3.9, and passed the them.

Yet, it doesn't pass the github tests. Any ideas as to why that might be?

I assume you are on windows? Same always happens to me.

[DanielGoman]

I assume you are on windows? Same always happens to me.

Indeed I am.

Thank you very much, I just tried running the script in the same manner on WSL and that seems to give the expected output.
Any ideas about how to avoid this issue on Windows?

[headtr1ck]

Any ideas about how to avoid this issue on Windows?

I have not figured that out. Usually the difference is small enough to fix it by hand.

Maybe we could add a CI run that generates it and commits a correction if necessary, the same way we do it for black right now.

[DanielGoman]

I noticed that DataArray.interp_like takes an argument called kwargs, but not in the traditional manner which allows passing keyworded arguments (**kwargs).

If this is the intended behavior then I think kwargs is kind of a misleading name for this argument.

[headtr1ck]

I noticed that DataArray.interp_like takes an argument called kwargs, but not in the traditional manner which allows passing keyworded arguments (**kwargs).

If this is the intended behavior then I think kwargs is kind of a misleading name for this argument.

See #7130

[DanielGoman]

I'm trying to figure out how to add examples to DataArray.cumsum and DataArray.cumprod, but it's not so clear to me.

It seems like they have partially dynamic docstrings. I have found the following script in xarray/core/common.py:

    _cum_extra_args_docstring = dedent(
        """\
        dim : str or sequence of str, optional
            Dimension over which to apply `{name}`.
        axis : int or sequence of int, optional
            Axis over which to apply `{name}`. Only one of the 'dim'
            and 'axis' arguments can be supplied."""
    )

However, it is not clear to me where the rest of the docstring is located, nor where the docstrings of each function (cumsum, cumprod) are located.

I'd appreciate if anybody could direct me to the explanation of this design :)

[DanielGoman]

I'm running into an issue when trying to directly use the DataArray.reduce method.

At first I used DataArray.cumsum to see the expected behavior:

>>> data = np.arange(12).reshape(4,3)
>>> da = xr.DataArray(data=data, dims=['x', 'y'], coords={'x': [10, 20, 30, 40], 'y': [70, 80, 90]})
>>> da.cumsum(dim='x')
<xarray.DataArray (x: 4, y: 3)>
array([[ 0,  1,  2],
       [ 3,  5,  7],
       [ 9, 12, 15],
       [18, 22, 26]])
Coordinates:
  * x        (x) int64 10 20 30 40
  * y        (y) int64 70 80 90

When I'm trying to achieve the same result through DataArray.reduce I'm running into the following crash:

>>> func = xr.DataArray.cumsum
>>> da.reduce(func=func, dim='x')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/mnt/c/Users/GoMaN/Desktop/GoMaN/Projects/xarray/xarray/core/dataarray.py", line 3442, in reduce
    var = self.variable.reduce(func, dim, axis, keep_attrs, keepdims, **kwargs)
  File "/mnt/c/Users/GoMaN/Desktop/GoMaN/Projects/xarray/xarray/core/variable.py", line 1883, in reduce
    data = func(self.data, axis=axis, **kwargs)
  File "/mnt/c/Users/GoMaN/Desktop/GoMaN/Projects/xarray/xarray/core/common.py", line 63, in wrapped_func
    return self.reduce(
AttributeError: 'numpy.ndarray' object has no attribute 'reduce'

Am I using DataArray.reduce incorrectly?

Thanks in advance :)

[dcherian]

Thanks @DanielGoman This is a great contribution!

I merged in the main branch, which should give you all green checks

[dcherian]

cumsum will be a lot more work, see ongoing work in #7152 . Thanks for looking in to it.

[DanielGoman]

cumsum will be a lot more work, see ongoing work in #7152 . Thanks for looking in to it.

I see, thanks for the heads up :)

[dcherian]

RTD failure is real:

/home/docs/checkouts/readthedocs.org/user_builds/xray/checkouts/7123/xarray/core/dataarray.py:docstring of xarray.core.dataarray.DataArray.drop_vars:32: ERROR: Unexpected indentation.
/home/docs/checkouts/readthedocs.org/user_builds/xray/checkouts/7123/xarray/core/dataarray.py:docstring of xarray.core.dataarray.DataArray.drop_vars:35: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/xray/checkouts/7123/xarray/core/dataarray.py:docstring of xarray.core.dataarray.DataArray.drop_vars:37: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/xray/checkouts/7123/xarray/core/dataarray.py:docstring of xarray.core.dataarray.DataArray.drop_vars:43: ERROR: Unexpected indentation.
/home/docs/checkouts/readthedocs.org/user_builds/xray/checkouts/7123/xarray/core/dataarray.py:docstring of xarray.core.dataarray.DataArray.drop_vars:46: WARNING: Block quote ends without a blank line; unexpected unindent.

[DanielGoman]

RTD failure is real:

Well I just fixed the issue to that.

Correct me if I'm wrong, but before pushing my corrected version I pulled the latest version from the remote branch, which seems to contain changes that fail the CI.

[headtr1ck]

The QUANTILE_METHODS has been moved and renamed to core.types.QuantileMethods.
Probably something went wrong in the merge.

[headtr1ck]

Since the merge apparently failed, I took the freedom to rebase this from the current master.
Feel free to continue or we merge here :)

[Illviljan]

Thanks, @DanielGoman !