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.

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

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.