issue_comments

One thing to make sure is if dim is already a scalar coordinate, it should be promoted to a 1D coordinate consisting of a single value.

Looks good to me. I would just make the default axis=None and indicate that that means "insert all new dimension in order at the start of the result arrays".

OK. I totally agree with you.

The API now I propose is

```Python def expand_dims(self, dim=None, axis=0): """Return a new object with an additional axis (or axes) inserted at the corresponding position in the array shape.

    Parameters
    ----------
    dim : str, list of strs, tuple of strs, or None
        Name(s) of new dimension.
        If a list (or tuple) of strings is passed, multiple axes are inserted.
        In this case, axis argument should be 0 or same length of integers indicating new axes positions.
    axis : integer, list of integers or tuple of integers
        Axis position(s) where new axis is to be inserted (position(s) on the result array).
        If a list (or tuple) of integers is passed, multiple axes are inserted.
        In this case, dim arguments should be None or same length list.

    Returns
    -------
    expanded : same type as caller
        This object, but with an additional dimension.

    Raises
    -------
    ValueError:
           If the length of axis and dim are different.
           If the axis is a list containing identical integers
           If axis is invalid (larger than the original dimension+1)

```

Do you think it is confusing if this method automatically detects the positional argument, i.e. if string is passed then it should be the axis name and an integer should be axis position.

Yes, I think this would be too confusing. Function arguments should do one thing.

What would da.expand_dims(axis=0) even do? Insert a new dimension with an auto-generated name like dim_0? That seems not very useful to me.

I guess that the reason that numpy doesn't support multiple axes insertion is it brings additional ambugousity to the new axes positions;

I think we could clarify this is by saying that axis indicates axis positions on the result array, not the input array, rather than corresponding to repeated application of expand_dims. So da.expand_dims(dim=['x' ,'y'], axis=[2, 1]) indicates that axis 2 on the result should be x and axis 1 should be y.

I would switch the order of the method arguments.

I agree this. Do you think it is confusing if this method automatically detects the positional argument, i.e. if string is passed then it should be the axis name and an integer should be axis position.

I think that numpy-like API is most user-friendly, as like TensorFlow imitates them. I like to support da.expand_dims(0) if it is not confusing for users who don't care the axes order.

We might also consider supporting inserting multiple axes at once

I guess that the reason that numpy doesn't support multiple axes insertion is it brings additional ambugousity to the new axes positions; e.g. da.expand_dims([2,1]) could behave python da.expand_dims(2) da.expand_dims(1) or python da.expand_dims(1) da.expand_dims(2) the results differ. (It does not matter if user only specifies the labels or the list is in order.)

I hesitate this option actually.

@fujiisoup I like your proposed API, but I would switch the order of the method arguments. That way, users who don't care about axis position can use a positional argument.

We might also consider supporting inserting multiple axes at once, e.g., by passing a list/tuple to dim/axis. This would be easy to add later, though.

Yes. How about the following? (I assume this is a method of xr.DataArray.)

```Python def expand_dims(self, axis=0, dim=None): """Return a new object with an additional dimension inserted at the corresponding position in the array shape.

    Parameters
    ----------
    axis : integer
        Position (amongst axes) where new axis is to be inserted.
    dim : str or None
        Name of new dimension.

    Returns
    -------
    expanded : same type as caller
        This object, but with an additional dimension.

```

I consider 2 types users; first type users always take care of the dimension order and the other just consider the dimension labels. The first type users may specify the new axis position as axis argument. The other may just pass the new dimension name regardless of its position, in which case the new dimension will be appended as the first dimension.

This API is similar to that of np.expand_dims and I believe its behavior is intuitive.

Can you propose what the API should look like?