Document ways to reshape a DataArray

[dimitryx2017]

Code Sample, a copy-pastable example if possible

A "Minimal, Complete and Verifiable Example" will make it much easier for maintainers to help you:
http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports

# Your code here

def xr_reshape(A, dim, newdims, coords):
    """ Reshape DataArray A to convert its dimension dim into sub-dimensions given by
    newdims and the corresponding coords.
    Example: Ar = xr_reshape(A, 'time', ['year', 'month'], [(2017, 2018), np.arange(12)]) """


    # Create a pandas MultiIndex from these labels
    ind = pd.MultiIndex.from_product(coords, names=newdims)

    # Replace the time index in the DataArray by this new index,
    A1 = A.copy()

    A1.coords[dim] = ind

    # Convert multiindex to individual dims using DataArray.unstack().
    # This changes dimension order! The new dimensions are at the end.
    A1 = A1.unstack(dim)

    # Permute to restore dimensions
    i = A.dims.index(dim)
    dims = list(A1.dims)

    for d in newdims[::-1]:
        dims.insert(i, d)

    for d in newdims:
        _ = dims.pop(-1)


    return A1.transpose(*dims)

Problem description

[this should explain why the current behavior is a problem and why the expected output is a better solution.]

It would be great to have the above function as a DataArray's method.

Expected Output

A reshaped DataArray. In the example in the function comment it would correspond to an array like

In[1] Ar.dims
Out[1]: ('year', 'month', 'lat', 'lon')

Output of xr.show_versions()

# Paste the output here xr.show_versions() here

INSTALLED VERSIONS

commit: None
python: 3.6.3.final.0
python-bits: 64
OS: Linux
OS-release: 3.10.0-693.5.2.el7.x86_64
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: None
LANG: fr_FR.UTF-8
LOCALE: fr_FR.UTF-8
xarray: 0.10.4
pandas: 0.23.0
numpy: 1.13.3
scipy: 0.19.1
netCDF4: 1.3.1
h5netcdf: None
h5py: 2.7.0
Nio: None
zarr: None
bottleneck: 1.2.1
cyordereddict: None
dask: 0.15.3
distributed: 1.19.1
matplotlib: 2.1.0
cartopy: 0.16.0
seaborn: 0.8.1
setuptools: 36.5.0.post20170921
pip: 18.0
conda: 4.4.7
pytest: 3.2.1
IPython: 6.1.0
sphinx: 1.6.3

[fujiisoup]

Thanks for raising an issue, @dimitryx2017.
I like this idea.

We usually have methods rather than function.
Any idea about the API?

We usually use a keyword argument.
I'm thinking something like
Ar.reshape(time=(('year', (2017, 2018)), ('month', np.arange(12))),
but it looks a little long...

[shoyer]

Can you give an more specific example use-case, e.g., before/after?

[dopplershift]

So I ran into this working with a climate scientist the other day. The use case we had was given some model output that had data like:

<xarray.DataArray 'NBP' (time: 1932, lat: 192, lon: 288)>
[106831872 values with dtype=float32]
Coordinates:
  * lat      (lat) float32 -90.0 -89.057594 -88.11518 ... 89.057594 90.0
  * lon      (lon) float32 0.0 1.25 2.5 3.75 5.0 ... 355.0 356.25 357.5 358.75
  * time     (time) object 1850-02-01 00:00:00 ... 2011-01-01 00:00:00

we wanted to reshape to turn time into two dimensions ("year", "month"). This was to facilitate looking at the max and min as a function of "month", take the difference, and then average over "year". Is there a way to do this already that I'm not aware of?

[shoyer]

This can be done with a MultiIndex and unstack(), but yes right now it's definitely an awkward API.

[rabernat]

This was to facilitate looking at the max and min as a function of "month", take the difference, and then average over "year"

What about

gb = ds.groupby('time.year')
gb.max(dim='time') - gb.min(dim='time')