Expanded documentation

docs/dask.rst

@@ -123,6 +123,21 @@ While the :meth:`~spectral_cube.DaskSpectralCube.rechunk` method can be used wit
 the ``save_to_tmp_dir=True`` option, which then just adds the rechunking to the dask tree,
 doing so is unlikely to lead in performance gains.
 
+A common scenario for rechunking is if you plan to do mostly operations that
+collapse along the spectral axis, for example computing moment maps. In this
+case you can use::
+
+    >>> cube_new = cube.rechunk(chunks=(-1, 'auto', 'auto'), save_to_tmp_dir=True)  # doctest: +IGNORE_OUTPUT
+    [########################################] | 100% Completed |  0.1s
+
+which will rechunk the data into cubes that span the full spectral axis but will be
+chunked in the image plane. And a complementary case is if you plan to do operations
+to each image plane, such as spatial convolution, in which case you can divide the
+data into spectral chunks that span the whole of the image dimensions::
+
+    >>> cube_new = cube.rechunk(chunks=('auto', -1, -1), save_to_tmp_dir=True)  # doctest: +IGNORE_OUTPUT
+    [########################################] | 100% Completed |  0.1s
+
 Performance benefits of dask classes
 ------------------------------------
 

spectral_cube/dask_spectral_cube.py

@@ -322,12 +322,17 @@ def rechunk(self, chunks='auto', threshold=None, block_size_limit=None,
         """
         Rechunk the underlying dask array and return a new cube.
 
+        For more details about the parameters below, see the dask documentation
+        about `rechunking <https://docs.dask.org/en/latest/array-chunks.html>`_.
+
         Parameters
         ----------
         chunks:  int, tuple, dict or str, optional
-            The new block dimensions to create. -1 indicates the full size of the
-            corresponding dimension. Default is "auto" which automatically
-            determines chunk sizes.
+            The new block dimensions to create. -1 indicates the full size of
+            the corresponding dimension. Default is "auto" which automatically
+            determines chunk sizes. This can also be a tuple with a different
+            value along each dimension - for example if computing moment maps,
+            you could use e.g. ``chunks=(-1, 'auto', 'auto')``
         threshold: int, optional
             The graph growth factor under which we don't bother introducing an
             intermediate step.