Allow expand_dims() method to support inserting/broadcasting dimensions with size>1

[pletchm]

This pull request enhances the expand_dims method for both Dataset and DataArray objects to support inserting/broadcasting dimensions with size > 1. It corresponds to this issue #2710.

Changes:

1. dataset.expand_dims() method take dict like object where values represent length of dimensions or coordinates of dimesnsions
2. dataarray.expand_dims() method take dict like object where values represent length of dimensions or coordinates of dimesnsions
3. Add alternative option to passing a dict to the dim argument, which is now an optional kwarg, passing in each new dimension as its own kwarg
4. Add expand_dims enhancement from issue 2710 to whats-new.rst

Included:

• Tests added
• Fully documented, including whats-new.rst for all changes and api.rst for new API

What's new:

All of the old functionality is still there, so it shouldn't break anyone's existing code that uses it.

You can now pass a dim as a dict, where the keys are the new dimensions and the values are either integers (giving the length of the new dimensions) or iterables (giving the coordinates of the new dimensions).

import numpy as np
import xarray as xr
>>> original = xr.Dataset({'x': ('a', np.random.randn(3)),
'y': (['b', 'a'], np.random.randn(4, 3))},
coords={'a': np.linspace(0, 1, 3),
'b': np.linspace(0, 1, 4),
'c': np.linspace(0, 1, 5)},
attrs={'key': 'entry'})
>>> original
<xarray.Dataset>
Dimensions: (a: 3, b: 4, c: 5)
Coordinates:
* a (a) float64 0.0 0.5 1.0
* b (b) float64 0.0 0.3333 0.6667 1.0
* c (c) float64 0.0 0.25 0.5 0.75 1.0
Data variables:
x (a) float64 -1.556 0.2178 0.6319
y (b, a) float64 0.5273 0.6652 0.3418 1.858 ... -0.3519 0.8088 0.8753
Attributes:
key: entry
>>> original.expand_dims({"d": 4, "e": ["l", "m", "n"]})
<xarray.Dataset>
Dimensions: (a: 3, b: 4, c: 5, d: 4, e: 3)
Coordinates:
* e (e) <U1 'l' 'm' 'n'
* a (a) float64 0.0 0.5 1.0
* b (b) float64 0.0 0.3333 0.6667 1.0
* c (c) float64 0.0 0.25 0.5 0.75 1.0
Dimensions without coordinates: d
Data variables:
x (d, e, a) float64 -1.556 0.2178 0.6319 ... -1.556 0.2178 0.6319
y (d, e, b, a) float64 0.5273 0.6652 0.3418 ... -0.3519 0.8088 0.8753
Attributes:
key: entry

Or, equivalently, you can pass the new dimensions as kwargs instead of a dictionary.

original.expand_dims(d=4, e=["l", "m", "n"])

[pep8speaks]

Hello @pletchm! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2019-03-26 01:00:29 UTC

[fujiisoup]

Thanks for sending a PR. I also think it is a nice feature.
Some minor comments

[pletchm]

Hi @shoyer and @fujiisoup, I believe I've made all of the updates that you suggested in your comments. How is the PR looking now?
Thank you!

[pletchm]

@shoyer, dim_kwargs is no longer allowed to be used for python 3.5. Does anything else need to change in this PR?

[shoyer]

One small note, otherwise looks good to me!

[shoyer]

Thanks @pletchm!