Update DataArray.rename + docu

[headtr1ck]

• Closes DataArray.rename docu missing renaming of dimensions #5458
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst

On the way, I have added the support for changing the name and dims/coords in the same rename call.

Also took the freedom to fix some unrelated typing problems.

[headtr1ck]

Mow you can also have the name of the DataArray in the rename dict.
The code got a bit more complicated, lots of if-branches are slight modifications of each other, probably simplifyable.

[headtr1ck]

Now that I think about it...
Is it common to have the DataArray being called the same as one of its dimensions/coordinates?
This might break some things.
So maybe better to revert the last commit that introduced this change?

[headtr1ck]

Now the behavior is the same as before with the only addition that one can rename the DataArray with a positional argument and its cords/dims via kwargs at the same time.

I have added further tests that are a bit more expressive than before.

Should be ready to merge now.

[max-sixty]

This seems like a nice improvement given the existing state.

I've found the effort to specialize methods (e.g. drop_var vs. drop_sel) has been good, and we might want to extend this principle. With the proposed code:

• renaming a coord on a DataArray is rename
• renaming a coord on a Dataset is rename_vars

...which is not ideal, though might be the best tradeoff.

WDYT @headtr1ck ? Or any other thoughts from others?

[keewis]

in pint-xarray we have the .pint.to method which uses a very similar concept, maybe it is worth copying that for rename?

[max-sixty]

in pint-xarray we have the .pint.to method which uses a very similar concept, maybe it is worth copying that for rename?

We do want it to be fluent though, so it can be directly on the DataArray, otherwise you can't do:

(
  da
  .rename(...)
  .sum(...)
)

[headtr1ck]

Honestly I am a big fan of functions that are called the same for DataArray and Dataset since this enables workflows on objects that could be either.

A rename_dims method sounds easy to implement.
The rename_vars does not sound extremely convincing for DataArray though. Should this rename the array and it's coords?

[keewis]

We do want it to be fluent though, so it can be directly on the DataArray, otherwise you can't do:

I was referring to the concept rather than the method. The idea is that you can refer to the DataArray by positional or by name, and the method takes either a single string or a dict mapping old names to new names, also with a kwargs version (the merging happens with either_dict_or_kwargs). That would mean these all do the same thing:

a = xr.DataArray([0, 1, 2], dims="x")
a.rename("new")
a.rename({None: "new"})  # None is the current name

b = xr.DataArray([0, 1, 2], dims="x", name="b")
b.rename("new")
b.rename(b="new")  # b is the current name

# with coords
c = xr.DataArray([0, 1, 2], dims="x", coords={"x": ["a", "b", "c"]}, name="c")
c.rename("new", x="y")
c.rename(c="new", x="y")
c.rename({"c": "new", "x": "y"})  # providing both the `dict` and the kwargs raises

[headtr1ck]

I will implement a rename_dims method, this should be trivial.

I am not sure about rename_vars: what should this method do with the name of the DataArray? Should it only rename coords or also the name?

[max-sixty]

@keewis v interesting suggestion — the object name as positional and vars as kwargs.

As I think was mentioned above, one choice is whether a kwarg with the name of the object renames the object. I would worry it's slightly ambiguous. And potentially not additive. WDYT?

a rename_dims method

This could be good. Would this also rename the coord associated with the dim?

[keewis]

Would this also rename the coord associated with the dim?

To decide that we probably need to figure out what the role of a dimension will be after the index refactor. Before the refactor, we needed to rename the dimension coordinate along with the dimension to keep the index, but now that indexes are independent of dimensions it might be fine not to do that.

[headtr1ck]

Ok I see. I hereby withdraw my comment that it will be trivial, haha.

[headtr1ck]

So, how about we leave the current implemention like it is (or merge this PR, it does not really change the core functionality).

And then open another issue on how to procede with rename in light of the index refactor?

[max-sixty]

Yes great, let's merge this.

And then open another issue on how to procede with rename in light of the index refactor?
Great!

---

Then two main options I see for synthesizing the vars issues:

• rename operates on DataArray as described in https://github.com/pydata/xarray/pull/6665#issuecomment-1150810485. Generally I'm less keen on "different types have different semantics", and here a positional arg would mean a DataArray rename, and kwarg would mean var rename. But it does work locally to DataArray quite well.
• rename only exists on DataArrays for the name of the DataArray, and we use rename_vars & rename_dims for both DataArrays & Datasets. So Dataset.rename is soft-deprecated.

[headtr1ck]

I have created #6704 and tried to copy a summary of this discussion.
Feel free to continue the discussion there :)

[Illviljan]

Thanks @headtr1ck !