Work with @dkillick to improve the Merge & Concatenate introduction.

Author: pelson

docs/iris/src/userguide/merge_and_concat.rst

@@ -4,62 +4,85 @@
 Merge and Concatenate
 =====================
 
-Sometimes you need to combine multiple Iris cubes to form a single larger Iris cube. You can achieve this with :meth:`merge <iris.cube.CubeList.merge>` and :meth:`concatenate <iris.cube.CubeList.concatenate>`.
+We saw in the :doc:`loading_iris_cubes` section that Iris tries to load as few cubes as
+possible. This is done by collecting together multiple fields with a shared standard
+name (and other key metadata) into a single multidimensional cube. The processes that
+perform this behaviour in Iris are known as ``merge`` and ``concatenate``.
 
-This chapter of the user guide describes :meth:`merge <iris.cube.CubeList.merge>` and :meth:`concatenate <iris.cube.CubeList.concatenate>`.
-It outlines use cases for :meth:`merge <iris.cube.CubeList.merge>` and :meth:`concatenate <iris.cube.CubeList.concatenate>` and describes the differences between them.
-It also explains why some common issues occur and how to avoid these issues occurring.
+This section describes the ``merge`` and ``concatenate`` processes; it explains
+why common issues occur when using them and gives advice on how prevent these
+issues from occurring.
 
-The uses of :meth:`merge <iris.cube.CubeList.merge>` and :meth:`concatenate <iris.cube.CubeList.concatenate>` are as follows:
+Both ``merge`` and ``concatenate`` take multiple cubes as input and
+result in fewer cubes as output. The following diagram illustrates the two processes:
 
-    * **Merge:** stacks the instances of a common scalar coordinate on each of a series of input cubes. This makes a resultant cube with a new dimension coordinate created by merging these scalar coordinates.
-    * **Concatenate:** joins the instances of a common dimension coordinate from each of a series of input cubes. This makes a resultant cube with this dimension coordinate extended.
+    ||| -> MERGE -> |__|
+    
+    |_| |_| |_| -> CONCATENATE -> |___|
 
+There is one major difference between the ``merge`` and ``concatenate`` processes. 
+The ``merge`` process combines multiple input cubes into a
+single resultant cube with new dimensions created from the
+*scalar coordinate values* of the input cubes.
+The ``concatenate`` process process combines multiple input cubes into a
+single resultant cube with the same *number of dimensions* as the input cubes,
+but with the length of one or more dimensions extended by *joining together
+sequential dimension coordinates*.
 
-Merge
------
 
-:meth:`Merge <iris.cube.CubeList.merge>` stacks the instances of a common scalar coordinate on each of a series of input cubes.
-This makes a resultant cube with a new dimension coordinate created by merging these scalar coordinates.
-This has the following effects:
+Let's imagine 28 individual cubes representing the
+temperature at a location ``(y, x)``, one cube for each day of February. We can use
+:meth:`merge <iris.cube.CubeList.merge>` to combine the 28 ``(y, x)`` cubes into
+a single ``(t, y, x)`` cube, where the length of the ``t`` dimension is 28.
 
-    * A new dimension coordinate is formed from the series of scalar coordinates from the input cubes. Its data is composed of the scalar coordinates' data values.
-    * A single resultant cube is formed from the series of input cubes. It will have one more dimension (the new dimension coordinate described above) than the input cubes.
+Now imagine 12 individual cubes representing daily temperature at a time and
+location ``(t, y, x)``, one cube for each month in the year. We can use
+:meth:`concatenate <iris.cube.CubeList.concatenate>` to combine the 12
+``(t, y, x)`` cubes into a single ``(t, y, x)`` cube, where the length
+of the ``t`` dimension is now 365.
 
-.. note::
 
-    The data values in the series of scalar coordinates must describe a single monotonic series.
+Merge
+-----
 
-.. note::
+We've seen that the ``merge`` combines multiple input cubes into a
+single resultant cube with new dimensions created from the
+*scalar coordinate values* of the input cubes.
+
+In order to construct new coordinates for the new dimensions, the ``merge`` process requires input cubes
+with scalar coordinates that can be combined together into monotonic sequences.
+The order of the input cubes does not affect the ``merge`` process.
+
+The ``merge`` process can produce a cube that has more than one new dimension,
+if the scalar coordinate sequences form an orthogonal basis.
 
-    The order of the data values in the series of scalar coordinates does not affect the :meth:`merge <iris.cube.CubeList.merge>` process.
-    The data values in the series of scalar coordinates will be re-ordered into a montonically increasing series as part of the :meth:`merge <iris.cube.CubeList.merge>` process.
 
 .. warning::
 
-    The shape, metadata, attributes, coordinates, coordinates metadata, fill value and other aspects of your input cubes must be consistent across all the input cubes.
-    The :meth:`merge <iris.cube.CubeList.merge>` process will fail if they are not consistent. Such failures are covered in the common issues section towards the end of this chapter.
+    The shape, metadata, attributes, coordinates, coordinates metadata, fill value and
+    other aspects of the a cube must be consistent across all of the input cubes.
 
-Let's have a look at :meth:`merge <iris.cube.CubeList.merge>` in operation. In this example we have three lateral (*x*, *y*) cubes in an :class:`cubelist <iris.cube.CubeList>`, each with a scalar *z* coordinate of differing value.
-We can merge these cubes by stacking the scalar *z* coordinates to make a new *z* dimension coordinate::
+    The :meth:`merge <iris.cube.CubeList.merge>` process will fail if they are not
+    consistent. Such failures are covered in the common issues section towards the end of this chapter.
 
-    >>> print cubelist
+Let's have a look at :meth:`merge <iris.cube.CubeList.merge>` in operation. In this example we have
+three lateral (*x*, *y*) cubes in an :class:`cubelist <iris.cube.CubeList>`, each with a scalar *z*
+coordinate of differing value. We can merge these cubes by stacking the scalar *z* coordinates to
+make a new *z* dimension coordinate::
+
+    >>> print cubes
     0: air_temperature / (kelvin)          (x: 10; y: 10)
     1: air_temperature / (kelvin)          (x: 10; y: 10)
     2: air_temperature / (kelvin)          (x: 10; y: 10)
-    >>> print cubelist[0]
+    >>> print cubes.
     air_temperature / (kelvin)          (x: 10; y: 10)
          Dimension coordinates:
               x                           x      -
               y                           -      x
          Scalar coordinates:
               z: 1
-    print cubelist.merge()[0]  # Merge returns a cubelist.
-    air_temperature / (kelvin)          (z: 3; x: 10; y: 10)
-         Dimension coordinates:
-              z                           x     -      -
-              x                           -     x      -
-              y                           -     -      x
+    print cubes.merge()
+    0: air_temperature / (kelvin)          (z: 3; x: 10; y: 10)
 
 The following diagram illustrates how :meth:`merge <iris.cube.CubeList.merge>` works: