Fixed doctests and minor fixes.

pelson · pelson · commit 4f547eeb8d30 · 2014-11-21T13:42:11.000Z
diff --git a/docs/iris/src/userguide/merge_and_concat.rst b/docs/iris/src/userguide/merge_and_concat.rst
@@ -4,12 +4,12 @@
 Merge and Concatenate
 =====================
 
-We saw in the :doc:`loading_iris_cubes` section that Iris tries to load as few cubes as
+We saw in the :doc:`loading_iris_cubes` chapter 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 section describes the ``merge`` and ``concatenate`` processes; it explains
+This chapter 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.
 
@@ -32,12 +32,12 @@ sequential dimension coordinates*.
 
 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
+:meth:`~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.
 
 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
+:meth:`~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.
 
@@ -59,7 +59,7 @@ if the scalar coordinate sequences form an orthogonal basis.
 .. important::
 
     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.
+    other aspects of the input cubes must be consistent across all of the input cubes.
 
     The ``merge`` process will fail if these are not consistent. Such failures are
     covered in the :ref:`merge_concat_common_issues` section.
@@ -77,7 +77,7 @@ The :meth:`CubeList.merge <iris.cube.CubeList.merge>` method operates on a list
 of cubes and returns a new :class:`~iris.cube.CubeList` containing the cubes
 that have been merged.
 
-.. testsetup::
+.. testsetup:: merge
 
     import numpy as np
     import iris
@@ -96,7 +96,7 @@ variable called ``cubes``, 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:
 
-.. doctest::
+.. doctest:: merge
     :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> print cubes
@@ -166,7 +166,6 @@ into a single cube:
     cubes = iris.cube.CubeList([_xy_cube(1), _xy_cube(2), _xy_cube(3)])
     cubes[0].attributes['Conventions'] = 'CF-1.5'
 
-
 .. doctest:: merge_vs_merge_cube
     :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
@@ -177,9 +176,9 @@ into a single cube:
 
     >>> print cubes[0].attributes
     {'Conventions': 'CF-1.5'}
-    >>> print cubes[1]
+    >>> print cubes[1].attributes
     {}
-    >>> print cubes[2]
+    >>> print cubes[2].attributes
     {}
 
     >>> print cubes.merge()
@@ -220,7 +219,6 @@ load cubes from files without the ``merge`` process taking place. The return val
 :func:`iris.load_raw` is always a :class:`~iris.cube.CubeList` instance.
 
 
-
 Concatenate
 -----------
 
@@ -236,7 +234,7 @@ The order of the input cubes does not affect the ``concatenate`` process.
 .. important::
 
     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.
+    other aspects of the input cubes must be consistent across all of the input cubes.
 
     The ``concatenate`` process will fail if these are not consistent. Such failures are
     covered in the :ref:`merge_concat_common_issues` section.
@@ -258,7 +256,22 @@ Let's have a look at the :meth:`~iris.cube.CubeList.concatenate` method in opera
 In the example below we have three 3D (*x*, *y*, *t*) cubes whose ``t`` coordinates
 have sequentially increasing ranges.
 These cubes can be concatenated by combining the ``t`` coordinates of the input
-cubes to form a new cube with an extended ``t`` coordinate::
+cubes to form a new cube with an extended ``t`` coordinate:
+
+.. testsetup:: concatenate
+
+    import numpy as np
+    import iris
+    def _xyt_cube(t):
+        cube = iris.cube.Cube(np.arange(12 * len(t)).reshape(-1, 3, 4), 'air_temperature', units='kelvin')
+        cube.add_dim_coord(iris.coords.DimCoord(range(3), long_name='y'), 1)
+        cube.add_dim_coord(iris.coords.DimCoord(range(4), long_name='x'), 2)
+        cube.add_dim_coord(iris.coords.DimCoord(t, long_name='t'), 0)
+        return cube
+    cubes = iris.cube.CubeList([_xyt_cube(np.arange(31)), _xyt_cube(np.arange(28) + 31), _xyt_cube(np.arange(31) + 59)])
+
+.. doctest:: concatenate
+    :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> print cubes
     0: air_temperature / (kelvin)          (t: 31; y: 3; x: 4)
@@ -269,25 +282,6 @@ cubes to form a new cube with an extended ``t`` coordinate::
     0: air_temperature / (kelvin)          (t: 90; y: 3; x: 4)
 
 
-..
-
-    DOCTEST DISABLED TEMPORARILY
-    .. testsetup:: concatenate
-    
-        import numpy as np
-        import iris
-        def _xyt_cube(t):
-            cube = iris.cube.Cube(np.arange(12 * len(t)).reshape(-1, 3, 4), 'air_temperature', units='kelvin')
-            cube.add_dim_coord(iris.coords.DimCoord(range(3), long_name='y'), 1)
-            cube.add_dim_coord(iris.coords.DimCoord(range(4), long_name='x'), 2)
-            cube.add_dim_coord(iris.coords.DimCoord(t, long_name='t'), 0)
-            return cube
-        cubes = iris.cube.CubeList([_xyt_cube(range(31)), _xyt_cube(range(28)), _xyt_cube(range(31))])
-    
-    .. doctest:: concatenate
-        :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
-
-
 The following diagram illustrates what has taken place in this example:
 
 .. image:: concat.svg
@@ -317,8 +311,23 @@ from the earlier merge example.
 For the purposes of this example we'll add a *History* attribute to the first
 cube's :data:`~iris.cube.Cube.attributes` dictionary.
 Remember that the attributes *must* be consistent across all cubes in order to
-concatenate into a single cube::
+concatenate into a single cube:
 
+.. testsetup:: concatenate_vs_concatenate_cube
+
+    import numpy as np
+    import iris
+    def _xyt_cube(t):
+        cube = iris.cube.Cube(np.arange(12 * len(t)).reshape(-1, 3, 4), 'air_temperature', units='kelvin')
+        cube.add_dim_coord(iris.coords.DimCoord(range(3), long_name='y'), 1)
+        cube.add_dim_coord(iris.coords.DimCoord(range(4), long_name='x'), 2)
+        cube.add_dim_coord(iris.coords.DimCoord(t, long_name='t'), 0)
+        return cube
+    cubes = iris.cube.CubeList([_xyt_cube(np.arange(31)), _xyt_cube(np.arange(28) + 31), _xyt_cube(np.arange(31) + 59)])
+    cubes[0].attributes['History'] = 'Created 2010-06-30'
+
+.. doctest:: concatenate_vs_concatenate_cube
+    :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> print cubes
     0: air_temperature / (kelvin)          (t: 31; y: 3; x: 4)
@@ -331,8 +340,8 @@ concatenate into a single cube::
     {}
 
     >>> print cubes.concatenate()
-    0: air_temperature / (kelvin)          (t: 31; x: 10; y: 10)
-    1: air_temperature / (kelvin)          (t: 59; x: 10; y: 10)
+    0: air_temperature / (kelvin)          (t: 31; y: 3; x: 4)
+    1: air_temperature / (kelvin)          (t: 59; y: 3; x: 4)
     >>> print cubes.concatenate_cube()
     Traceback (most recent call last):
         ...
@@ -341,29 +350,6 @@ concatenate into a single cube::
       Cube metadata differs for phenomenon: air_temperature
 
 
-..
-
-    DOCTEST DISABLED TEMPORARILY
-
-    .. testsetup:: concatenate_vs_concatenate_cube
-    
-        import numpy as np
-        import iris
-        def _xyt_cube(t):
-            cube = iris.cube.Cube(np.arange(12 * len(t)).reshape(-1, 3, 4), 'air_temperature', units='kelvin')
-            cube.add_dim_coord(iris.coords.DimCoord(range(3), long_name='y'), 1)
-            cube.add_dim_coord(iris.coords.DimCoord(range(4), long_name='x'), 2)
-            cube.add_dim_coord(iris.coords.DimCoord(t, long_name='t'), 0)
-            return cube
-        cubes = iris.cube.CubeList([_xyt_cube(range(31)), _xyt_cube(range(28)), _xyt_cube(range(31))])
-        cubes[0].attributes['History'] = 'Created 2010-06-30'
-    
-    
-    .. doctest:: concatenate_vs_concatenate_cube
-        :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
-
-
-
 Note that :meth:`~iris.cube.CubeList.concatenate` returns two cubes here.
 All the cubes that can be concatenated have been. Any cubes that can't be concatenated are
 included unchanged in the returned :class:`~iris.cube.CubeList`.
@@ -379,22 +365,22 @@ single cube. An example of fixing an issue like this can be found in the
 Common issues with merge and concatenate
 ----------------------------------------
 
-The Iris algorithms that drive :meth:`merge <iris.cube.CubeList.merge>` and
-:meth:`concatenate <iris.cube.CubeList.concatenate>` are complex and depend
+The Iris algorithms that drive :meth:`~iris.cube.CubeList.merge` and
+:meth:`~iris.cube.CubeList.concatenate` are complex and depend
 on a number of different elements of the input cubes being consistent across
 all input cubes.
 If this consistency is not maintained then the
-:meth:`merge <iris.cube.CubeList.merge>` or
-:meth:`concatenate <iris.cube.CubeList.concatenate>` process can fail in a
+:meth:`~iris.cube.CubeList.merge` or
+:meth:`~iris.cube.CubeList.concatenate` process can fail in a
 seemingly arbitrary manner.
 
-The methods :meth:`merge_cube <iris.cube.CubeList.merge_cube>` and
-:meth:`concatenate_cube <iris.cube.CubeList.concatenate_cube>` 
+The methods :meth:`~iris.cube.CubeList.merge_cube` and
+:meth:`~iris.cube.CubeList.concatenate_cube` 
 were introduced to Iris to help you locate differences in input cubes
 that prevent the input cubes merging or concatenating.
 Nevertheless, certain difficulties with using
-:meth:`merge <iris.cube.CubeList.merge>` and
-:meth:`concatenate <iris.cube.CubeList.concatenate>` occur frequently.
+:meth:`~iris.cube.CubeList.merge` and
+:meth:`~iris.cube.CubeList.concatenate` occur frequently.
 This section describes these common difficulties, why they arise and
 what you can do to avoid them.
 
@@ -423,8 +409,7 @@ To demonstrate using :func:`~iris.experimental.equalise_cubes.equalise_attribute
 let's return to our non-merging list of input cubes from the merge_cube example
 from earlier.
 We'll call :func:`~iris.experimental.equalise_cubes.equalise_attributes` on the
-input cubes before merging the input cubes using :meth:`~iris.cube.CubeList.merge_cube`::
-
+input cubes before merging the input cubes using :meth:`~iris.cube.CubeList.merge_cube`:
 
 .. doctest:: merge_vs_merge_cube
     :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
@@ -437,9 +422,9 @@ input cubes before merging the input cubes using :meth:`~iris.cube.CubeList.merg
 
     >>> print cubes[0].attributes
     {'Conventions': 'CF-1.5'}
-    >>> print cubes[1]
+    >>> print cubes[1].attributes
     {}
-    >>> print cubes[2]
+    >>> print cubes[2].attributes
     {}
 
     >>> print cubes.merge_cube()
@@ -455,7 +440,11 @@ input cubes before merging the input cubes using :meth:`~iris.cube.CubeList.merg
     {}
 
     >>> print cubes.merge_cube()
-    0: air_temperature / (kelvin)          (z: 3; y: 4; x: 5)
+    air_temperature / (kelvin)          (z: 3; y: 4; x: 5)
+         Dimension coordinates:
+              z                           x     -     -
+              y                           -     x     -
+              x                           -     -     x
 
 
 **Incomplete Data**
@@ -495,21 +484,39 @@ scalar ``z`` coordinate with value 2 and the third has a scalar ``z``
 coordinate with value 1.
 The first and third cubes are thus identical.
 We will demonstrate the effect of merging the input cubes with ``unique=False``
-(duplicate cubes allowed) and ``unique=True`` (duplicate cubes not allowed)::
+(duplicate cubes allowed) and ``unique=True`` (duplicate cubes not allowed):
+
+.. testsetup:: merge_duplicate
+
+    import numpy as np
+    import iris
+    def _xy_cube(z):
+        cube = iris.cube.Cube(np.arange(20).reshape(4, 5), 'air_temperature', units='kelvin')
+        cube.add_dim_coord(iris.coords.DimCoord(range(4), long_name='y'), 0)
+        cube.add_dim_coord(iris.coords.DimCoord(range(5), long_name='x'), 1)
+        cube.add_aux_coord(iris.coords.DimCoord(z, long_name='z', units='meters'))
+        return cube
+    cubes = iris.cube.CubeList([_xy_cube(1), _xy_cube(2), _xy_cube(1)])
+
+.. doctest:: merge_duplicate
+    :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> 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)
+    0: air_temperature / (kelvin)          (y: 4; x: 5)
+    1: air_temperature / (kelvin)          (y: 4; x: 5)
+    2: air_temperature / (kelvin)          (y: 4; x: 5)
+
     >>> print cubes.merge(unique=False)
-    0: air_temperature / (kelvin)          (z: 2; x: 10; y: 10)
-    1: air_temperature / (kelvin)          (z: 2; x: 10; y: 10)
-    >>> print cubelist.merge()  # unique=True is the default.
+    0: air_temperature / (kelvin)          (z: 2; y: 4; x: 5)
+    1: air_temperature / (kelvin)          (z: 2; y: 4; x: 5)
+
+    >>> print cubes.merge()  # unique=True is the default.
     Traceback (most recent call last):
       ...
     iris.exceptions.DuplicateDataError: failed to merge into a single cube.
       Duplicate 'air_temperature' cube, with scalar coordinates z=Cell(point=1, bound=None)
 
+
 Notice how merging the input cubes with duplicate cubes allowed produces a result
 with **four** `z` coordinate values.
 Closer inspection of these two resultant cubes demonstrates that the
@@ -578,12 +585,33 @@ To demonstrate using :func:`~iris.util.unify_time_units`,
 let's adapt our list of input cubes from the ``concatenate_cube`` example from earlier.
 We'll give the input cubes unequal time coordinate units and call
 :func:`~iris.util.unify_time_units` on the input cubes before concatenating
-the input cubes using :meth:`~iris.cube.CubeList.concatenate_cube`::
+the input cubes using :meth:`~iris.cube.CubeList.concatenate_cube`:
+
+.. testsetup:: concatenate_time_units
+
+    import numpy as np
+    import iris
+    def _xyt_cube(t):
+        cube = iris.cube.Cube(np.arange(12 * len(t)).reshape(-1, 3, 4), 'air_temperature', units='kelvin')
+        cube.add_dim_coord(iris.coords.DimCoord(range(3), long_name='y'), 1)
+        cube.add_dim_coord(iris.coords.DimCoord(range(4), long_name='x'), 2)
+        cube.add_dim_coord(iris.coords.DimCoord(t, long_name='t'), 0)
+        return cube
+    cubes = iris.cube.CubeList([_xyt_cube(np.arange(31).astype(np.float64)),
+                                _xyt_cube(np.arange(28).astype(np.float64) + 31),
+                                _xyt_cube(np.arange(31).astype(np.float64) + 59)])
+    cubes[0].coord('t').units = 'days since 1990-02-15'
+    cubes[1].coord('t').units = 'days since 1970-01-01'
+    cubes[2].coord('t').units = 'days since 1970-01-01'
+
+.. doctest:: concatenate_time_units
+    :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> from iris.util import unify_time_units
     >>> print cubes
-    0: air_temperature / (kelvin)          (t: 10; x: 10; y: 10)
-    1: air_temperature / (kelvin)          (t: 10; x: 10; y: 10)
+    0: air_temperature / (kelvin)          (t: 31; y: 3; x: 4)
+    1: air_temperature / (kelvin)          (t: 28; y: 3; x: 4)
+    2: air_temperature / (kelvin)          (t: 31; y: 3; x: 4)
 
     >>> print cubes[0].coord('t').units
     days since 1990-02-15
@@ -592,8 +620,8 @@ the input cubes using :meth:`~iris.cube.CubeList.concatenate_cube`::
 
     >>> print cubes.concatenate_cube()
     Traceback (most recent call last):
-      ...
-    iris.exceptions.ConcatenateError: failed to concatenate into a single cube.
+     ...
+    ConcatenateError: failed to concatenate into a single cube.
       Dimension coordinates metadata differ: t != t
 
     >>> unify_time_units(cubes)
@@ -602,12 +630,11 @@ the input cubes using :meth:`~iris.cube.CubeList.concatenate_cube`::
     days since 1990-02-15
 
     >>> print cubes.concatenate_cube()
-    air_temperature / (kelvin)          (t: 20; x: 10; y: 10)
+    air_temperature / (kelvin)          (t: 90; y: 3; x: 4)
          Dimension coordinates:
-              t                           x      -      -
-              x                           -      x      -
-              y                           -      -      x
-
+              t                           x      -     -
+              y                           -      x     -
+              x                           -      -     x
 
 **Attributes Mismatch**
 
