Document ways to reshape a DataArray

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

[shoyer]

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

[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…