Documentation on tuple-type data in DataArrays

The Problem:

When you try to construct an xarray.DataArray with tuple-type data, it will fail with the following error:

>>> xr.DataArray((7,9,3), coords=[[1,2,3]], dims=['i'])

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
<ipython-input-17-11434cd9277e> in <module>
----> 1 xr.DataArray((7,9,3), coords=[[1,2,3]], dims=['i'])

~/Software/miniconda3/envs/pangeo/lib/python3.8/site-packages/xarray/core/dataarray.py in __init__(self, data, coords, dims, name, attrs, indexes, fastpath)
    341             data = _check_data_shape(data, coords, dims)
    342             data = as_compatible_data(data)
--> 343             coords, dims = _infer_coords_and_dims(data.shape, coords, dims)
    344             variable = Variable(dims, data, attrs, fastpath=True)
    345             indexes = dict(

~/Software/miniconda3/envs/pangeo/lib/python3.8/site-packages/xarray/core/dataarray.py in _infer_coords_and_dims(shape, coords, dims)
     92         and len(coords) != len(shape)
     93     ):
---> 94         raise ValueError(
     95             "coords is not dict-like, but it has %s items, "
     96             "which does not match the %s dimensions of the "

ValueError: coords is not dict-like, but it has 1 items, which does not match the 0 dimensions of the data

This error message is not helpful, nor does it direct the user to the solution to their problem (which is to just convert the tuple to a list). This is the first part of the problem.

If the user were to learn that the reason this happened was because tuple-type data is handled specially in xarray.core.variable.as_compatible_data and returned as a 0D NumPy array, they would still be confused because the documentation states:

The DataArray constructor takes:

• data: a multi-dimensional array of values (e.g., a numpy ndarray, Series, DataFrame or pandas.Panel)

suggesting that a list might not even be a valid type for data. So, upon further investigation, one finds that the xarray.DataArray.__init__ docstring says:

Parameters
        ----------
        data : array_like
            Values for this array. Must be an ``numpy.ndarray``, ndarray like,
            or castable to an ``ndarray``. If a self-described xarray or pandas
            object, attempts are made to use this array's metadata to fill in
            other unspecified arguments. A view of the array's data is used
            instead of a copy if possible.

which states that data must be castable to an ndarray. There are many ways of doing this, but a quick check shows that numpy.asarray((1,2,3)) and numpy.array((1,2,3)) both behave as you would expect. Thus, this confusion is the second part of the problem.

Acceptable Solutions:

1. I am not sure why tuple-type data are treated differently with xarray. I'd like to know why because I think the easiest solution to this problem would be to remove that special treatment from xarray.core.variable.as_compatible_data. But I am sure this special treatment was written for a good reason, so I won't suggest that solution unless other developers genuinely believe that this feature can be removed.

2. Assuming special treatment of tuple-type data is desirable, then I would propose that the documentation be improved to indicate to users what to expect. I think the documentation lacks an explanation of the tuple-type special treatment (and, perhaps, other special treatments?) and the docstrings need to be made consistent with the documentation.

Start by reading xarray.core.variable.as_compatible_data and the xarray.DataArray.init docstring to understand and explain the tuple handling. Update the relevant documentation and docstrings so tuple input behavior and accepted array-like data are consistent; done means users can understand the error and the list conversion workaround.