issues

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.

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 ```

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.

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' ```

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.