issues

WIP PR for https://github.com/pydata/xarray/issues/3324. Since either_dict_or_kwargs is called 57 times, I don't want to modify every function call without a preliminary review. My main question is if using locals() at the top of each function is considered acceptable. Of course, if locals() is called after some local variables are created, this code could raise an error when no conflict exists. But explicitly passing in the function argument names in all 57 functions seems brittle. I'd appreciate any thoughts on the PR before I modify all the functions and write some tests.

Over at https://github.com/pydata/xarray/pull/3352, we're working on a new page describing key Xarray terminology for https://github.com/pydata/xarray/issues/2410. Since it's already a big PR, and we may need to iterate on the definitions a few times, this issue is for extending the glossary once that PR is merged. Some terms are to add are: aligning, broadcasting, merging, concatenating, combining.

This arose as part of https://github.com/pydata/xarray/pull/3352. Xarray has important-to-understand name-matching rules for whether or not a coordinate array is a dimension coordinate or a non-dimension coordinate. To my knowledge, this is not in the documentation anywhere.

This is what I had, but we decided to remove it since it was overly complicated for a list of key terms; maybe it'll be helpful going forward:

Name matching rules: Xarray follows simple but important-to-understand name matching rules for dimensions and coordinates. Let arr be an array with an existing dimension x and assigned new coordinates new_coords. If new_coords is a list-like for e.g. [1, 2, 3] then they must be assigned a name that matches an existing dimension. For example, if arr.assign_coords({'x': [1, 2, 3]}).

However, if new_coords is a one-dimensional DataArray, then the rules are slightly more complex. In this case, if both new_coords's name and only dimension match any dimension name in arr.dims, it is assigned as a dimension coordinate to arr. If new_coords's name matches a name in arr.dims but its own dimension name does not, it is assigned as a non-dimension coordinate with name new_coords.dims[0] to arr. Otherwise, an exception is raised.

This is my attempt at closing https://github.com/pydata/xarray/issues/2410. I've borrowed a bit of text from that PR (thanks @horta), from https://github.com/pydata/xarray/issues/1295, and from the xarray docs. I avoided verbose examples—it makes quickly searching and reading the glossary difficult—and put most of the effort into explaining dimension vs non-dimension coordinates, which in my experience opens the door to true xarray enlightenment.

Corrections, comments, or suggestions for additional terminology welcome.

Often the xarray API supports either a dict or kwargs, and it seems like this should be consistent as often as possible. With assign_coords, this works as expected:

```python

dims = ["x", "y"] coords = {"fruit": ("x", ["apple", "banana"])} arr = xr.DataArray([[1,2,3],[4,5,6]], dims=dims, coords=coords) arr.assign_coords(color=("x", ["red", "yellow"])) <xarray.DataArray (x: 2, y: 3)> array([[1, 2, 3], [4, 5, 6]]) Coordinates: fruit (x) <U6 'apple' 'banana' color (x) <U6 'red' 'yellow' Dimensions without coordinates: x, y ```

Since assign_coords works with keyword arguments, I would expect it to also work with a dict, similar to sel, drop, etc. But it does not:

```python

arr.assign_coords({"color": ("x", ["red", "yellow"])}) *** TypeError: assign_coords() takes 1 positional argument but 2 were given ```

I assume this is related to https://github.com/pydata/xarray/issues/3297 or an associated issue. Basically, a file, complex.nc, is being added to doc/ after running make clean && make html. Would be nice to suppress this.

Given that many Xarray methods accept dict or keyword arguments, this may effect other methods. That said, here is a minimal example with sel.

Minimal example

If I want to select based on a dimension named method, I cannot because Xarray thinks method is the method argument to sel:

```python

da1 = xr.DataArray(range(3), dims=['method'], coords={'method': range(3)}) da1 <xarray.DataArray (method: 3)> array([0, 1, 2]) Coordinates: * method (method) int64 0 1 2 da1.sel(method=0) ... TypeError: method must be a string ```

And if the method dimension has string labels, this fails silently:

```python

da2 = xr.DataArray(range(3), dims=['method'], coords={'method': list('abc')}) da2.sel(method='a') <xarray.DataArray (method: 3)> array([0, 1, 2]) Coordinates: * method (method) <U1 'a' 'b' 'c' ```

Expected Output

I think raising a ValueError and providing a clarifying error message is the right call, but maybe the maintainers have a different opinion. At the very least, it seems like Xarray could note that the DataArray instance has a dimension that matches one of the function arguments and ask the user to use dict-like arguments if required.

I imagine a general error handling function could be written to check this for any function and DataArray pair.

• [x] Closes #3227.
• [x] No CI tests added, but I ran make clean and make html to confirm the temporary files are no longer permanently created. I also confirmed the :suppress: blocks weren't showing up in the built HTML.
• [x] No need to pass black . && mypy . && flake8.
• [x] Fully documented in whats-new.rst.

MCVE

Apologies if this has already been noted, but I can't find an open issue. When I create the docs from scratch, I see a couple temporary files and directories that appear to have been created by accident. If this is a legitimate issue, I'm happy to put together a PR.

Here is an MCVE:

```bash (xarray-docs) gwg:doc gwg$ make clean rm -rf _build/ rm -rf generated/ rm -rf auto_gallery/ (xarray-docs) gwg:doc gwg$ git status On branch master Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean (xarray-docs) gwg:doc gwg$ make html sphinx-build -b html -d _build/doctrees . _build/html'

...

Build finished. The HTML pages are in _build/html. (xarray-docs) gwg:doc gwg$ git status On branch master Your branch is up to date with 'origin/master'.

Untracked files: (use "git add <file>..." to include in what will be committed)

example-no-leap.nc
foo.zarr/
manipulated-example-data.nc
path/

nothing added to commit but untracked files present (use "git add" to track) ```

Expected Output

I would expect no files to be created by make html in the doc directory.

Problem Description

It's not clear this will happen and may result in some people (me!) accidentally committing these files with git commit -A.

Problem

assign_corods correctly disallows creating a new dimension when assigning list-like coords with a name that does not match an existing dimension. However, it does allow this operation if the value is scalar.

MCVE

Consider the following DataArray:

```python

coords = {"fruit": ("x", ["apple", "banana"])} arr = xr.DataArray([[1, 2, 3], [4, 5, 6]], dims=("x", "y"), coords=coords) arr <xarray.DataArray (x: 2, y: 3)> array([[1, 2, 3], [4, 5, 6]]) Coordinates: fruit (x) <U6 'apple' 'banana' Dimensions without coordinates: x, y ```

I can assign new coordinates to an existing dimension:

```python

arr.assign_coords(color=("x", ["red", "yellow"])) <xarray.DataArray (x: 2, y: 3)> array([[1, 2, 3], [4, 5, 6]]) Coordinates: fruit (x) <U6 'apple' 'banana' color (x) <U6 'red' 'yellow' Dimensions without coordinates: x, y ```

And I cannot (correctly) assign coordinates to a new (nonexistent) dimension:

```python

arr.assign_coords(color=["red", "yellow"]) ... ValueError: cannot add coordinates with new dimensions to a DataArray ```

The above fails because Xarray, in the absence of an explicit dimension, tries to assign the new coordinates to a color dimension which does not exist. So far so good. But why does this work?

```python

arr = arr.assign_coords(color="red") arr <xarray.DataArray (x: 2, y: 3)> array([[1, 2, 3], [4, 5, 6]]) Coordinates: fruit (x) <U6 'apple' 'banana' color <U3 'red' Dimensions without coordinates: x, y ```

I would expect this to fail because color is not a dimension. But these appear to be newly added coordinates without a dimension?

```python

arr.coords Coordinates: fruit (x) <U6 'apple' 'banana' color <U3 'red' ```

• Addresses issue https://github.com/pydata/xarray/issues/2910 and completes PR https://github.com/pydata/xarray/pull/3128.
• Passes black . and flake8.
• Documented in whats-new.rst and indexing.rst.

• [x] Closes https://github.com/pydata/xarray/issues/3231.
• [x] Added tests for Dataset and groupby. Do we also need tests for DataArray? I assumed not since the actual code is in common.py, but I can add more.
• [x] Passes black . && mypy . && flake8.
• [x] Fully documented, including whats-new.rst and new example in the docstring.

• [x] Closes #3176 by adding examples of set_index and raising an error with a more clear error message.
• [x] Added unit test for error message.
• [x] Passes black . and flake8.
• [x] Documented in whats-new.rst.

Problem Description

Docs for DataArray.set_index describe the main indexes argument as:

Mapping from names matching dimensions and values given by (lists of) the names of existing coordinates or variables to set as new (multi-)index.

This suggests that one can set a DataArray instance's coordinates by passing in a dimension and a list-like object of coordinates.

MCVE

```python In [1]: import numpy as np

In [2]: import xarray as xr

In [3]: arr = xr.DataArray(data=np.ones((2, 3)), dims=['x', 'y'])

In [4]: arr.dims Out[4]: ('x', 'y')

In [5]: arr.set_index({'x': range(2)}) KeyError
... 144 for n in var_names: --> 145 var = variables[n] 146 if (current_index_variable is not None and 147 var.dims != current_index_variable.dims):

KeyError: 0 ```

At first, I thought it might be because coords and _coords were not being set in this case:

```python In [18]: arr.coords Out[18]: Coordinates: empty

In [19]: arr._coords Out[19]: OrderedDict() ```

but even if I set the coordinates first and then try to re-index, it fails:

python In [20]: arr = xr.DataArray(data=np.ones((2, 3)), dims=['x', 'y'], coords={'x': range(2), 'y': range(3)}) In [21]: arr.set_index({'x': ['a', 'b', 'c']}) ... 144 for n in var_names: --> 145 var = variables[n] 146 if (current_index_variable is not None and 147 var.dims != current_index_variable.dims):

Expected Output

I expect my MCVE to work based on the documentation.

Problem Solution

My guess is that the issue is Xarray is using the merge_indexes function (see here) from the Dataset module, and there is no concept of a variable in a DataArray.

• This closes #2949. We return a shallow copy of Pandas indexes to ensure immutability.
• Added test_index_immutability in tests/test_dataarray.py.
• Amended whats-new.rst.

• Closes https://github.com/pydata/xarray/issues/2910.
• In tests/test_dataset, added test_drop_labels_by_keyword
• Added a utility function is_list_like.
• Documented in whats-new.rst and confirmed API docs built correctly.

I'm a new contributor working on a couple PRs for Xarray and wished I had a short checklist of things to do before pushing a commit. First, I think such an overview list is useful per se. Second, CI takes a while, and it's much faster to just run black . or to build the docs manually than it is easy wait for CI to fail.

Inspired by Scikit-learn's checklist. This is just a first draft; happy for suggestions or to add anything I'm missing.