html_url,issue_url,id,node_id,user,created_at,updated_at,author_association,body,reactions,performed_via_github_app,issue
https://github.com/pydata/xarray/pull/4108#issuecomment-762894414,https://api.github.com/repos/pydata/xarray/issues/4108,762894414,MDEyOklzc3VlQ29tbWVudDc2Mjg5NDQxNA==,2448579,2021-01-19T14:56:22Z,2021-01-19T14:57:45Z,MEMBER,"> I wonder if it would be better to first ""reorganize"" all of the existing functions

I fully agree. However the bug in #4107 is that an invalid xarray object is created (`_assert_internal_invariants` fails), so I think we should merge a solution even before cleaning up the API.

EDIT: @keewis shall we copy your comment to a new issue?","{""total_count"": 1, ""+1"": 1, ""-1"": 0, ""laugh"": 0, ""hooray"": 0, ""confused"": 0, ""heart"": 0, ""rocket"": 0, ""eyes"": 0}",,626625818
https://github.com/pydata/xarray/pull/4108#issuecomment-761907785,https://api.github.com/repos/pydata/xarray/issues/4108,761907785,MDEyOklzc3VlQ29tbWVudDc2MTkwNzc4NQ==,14808389,2021-01-18T00:22:57Z,2021-01-18T00:23:50Z,MEMBER,"I wonder if it would be better to first ""reorganize"" all of the existing functions: we currently have `rename` (and `Dataset.rename_dims` / `Dataset.rename_vars`), `set_coords`, `reset_coords`, `set_index`, `reset_index` and `swap_dims`, which overlap partially. For example, the code sample from #4417 works if instead of
```python
ds = ds.rename(b='x')
ds = ds.set_coords('x')
```
we use
```python
ds = ds.set_index(x=""b"")
```
and something similar for the code sample in #4107.

I believe we currently have these use cases (not sure if that list is complete, though):
- rename a `DataArray` → `rename`
- rename a existing variable to a name that is not yet in the object → `rename` / `Dataset.rename_vars` / `Dataset.rename_dirs`
- convert a data variable to a coordinate (not a dimension coordinate) → `set_coords`
- convert a coordinate (not a dimension coordinate) to a data variable → `reset_coords`
- swap a existing dimension coordinate with a coordinate (which may not exist) and rename the dimension → `swap_dims`
- use a existing coordinate / data variable as a dimension coordinate (do not rename the dimension) → `set_index`
- stop using a coordinate as dimension coordinate and append `_` to its name (do not rename the dimension) → `reset_index`
- use two existing coordinates / data variables as a MultiIndex → `set_index`
- stop using a MultiIndex as a dimension coordinate and use its levels as coordinates → `reset_index`

Sometimes, some of these can be emulated by combinations of others, for example:
```python
# x is a dimension without coordinates
assert_identical(ds.set_index({""x"": ""b""}), ds.swap_dims({""x"": ""b""}).rename({""b"": ""x""}))
assert_identical(ds.swap_dims({""x"": ""b""}), ds.set_index({""x"": ""b""}).rename({""x"": ""b""}))
```
and, with this PR:
```python
assert_identical(ds.set_index({""x"": ""b""}), ds.set_coords(""b"").rename({""b"": ""x""}))
assert_identical(ds.swap_dims({""x"": ""b""}), ds.rename({""b"": ""x""}))
```
which means that it would increase the overlap of `rename`, `set_index`, and `swap_dims`.

In any case I think we should add a guide which explains which method to pick in which situation (or extend `howdoi`).","{""total_count"": 0, ""+1"": 0, ""-1"": 0, ""laugh"": 0, ""hooray"": 0, ""confused"": 0, ""heart"": 0, ""rocket"": 0, ""eyes"": 0}",,626625818