Cube concatenate.

[bjlittle]

This PR introduces experimental functionality to support the concatenation of two or more cubes over a common and already existing dimension. This is opposed to cube merge (aka cube stack as it's currently being rebranded as) which creates new cube dimensions based on mutually common scalar coordinates.

As mentioned previously, the cube concatenation functionality is experimental, hence the iris.x_concatenate namespace. This will change once cube concatenation is eventually adopted into the Iris core functionality.

Health warning ...
Due to limitations with the current Iris deferred loading mechanism, iris.x_concatenate.concatenate() will load the data payload of all your cubes. Heed this warning! This restriction will be relaxed in future revisions when the appropriate infrastructure is in place.

In a nutshell ...
The iris.x_concatenate.concatenate() function takes a list of cubes and returns the least number of largest possible cubes concatenated as many times necessary over common existing single dimensions ... yeah, like that helped clarify the matter! I think some examples might help here ...

E.g. The time-series cubes A(t:2, y:m, x:n), B(t:4, y:m, x:n), and C(t:6, y:m, x:n) are all geo-located but differ by non-overlapping time points over the first dimention. Thus concatenate([A, B, C]) will return the following concatenated cube (t:12, y:m, x:n) within an iris.cube.CubeList.

E.g. Building on the previous example, let its result be the cube named X. In addition to this we have the following sequence of time-series cubes D(t:2, y:m, x:p), E(t:4, y:m, x:p), F(t:6, y:m, x:p), which are co-located in latitude with cube X but not in longitude. Also,

• A and D share the same time points,
• B and E share the same time points, and
• C and F share the same time points.

Then concatenate([X, D, E, F]) will return the single concatenated cube (t:12, y:m, x:n+p). Indeed, concatenate([A, B, C, D, E, F]) will return exactly the same result. Naturally, if D, E and F are west of X, then we would get (t:12, y:m, x:p+n), if you know what I mean. Note that, the order of cubes in the list presented to concatenate() does not matter. So concatenate([F, E, D, C, B, A]) and concatenate([B, A, D, F, E, C]) or whatever, will all result in the same answer.

Cubes that have one or more anonymous dimension are ambiguous, and as such are considered incompatible with all other cubes. Therefore no cube can be concatenated with another cube that has at least one anonymous dimension.

As with cube merge (aka stack) concatenate() is strict and unforgiving. Cube metadata, dimensionality and coordinate metadata must match for two cubes to be considered compatible for concatenation. Beware lowly history entries in the attributes dictionary of a cube!

The important point is that concatenate() will discover the one common dimension and concatenate all compatible cubes into one cube. Only one degree of common dimensional freedom is permitted per concatenation, yet this can be any one single dimension, and concatenate() will exhaustively concatenate until there is no such commonality.

Note ...

• All code is PEP8 compliant, so I'll have no "Oh! that's a long line" comments thanks @rhattersley! 😈
• There's still a TODO list. See the iris.x_concatenate.py preamble.

[bjlittle]

Oops! The _output() function is a hang-over from debug/testing and should be nuked.

[bblay]

"already existing"...as opposed to what, non-existent? 😁
Is this qualification necessary?

[bjlittle]

My point was that concatenate deals with existing dimensions. Cube stack (or currently cube merge) generates new dimensions. Hence the reason for already existing.

Happy to reword if you think it's clumsy (which it is) to: Automatic concatenation of multiple cubes over one or more existing dimensions..

[bjlittle]

Done.

[esc24]

dimesion -> dimension

I also prefer "dimension(s)" to "dimension/s" to indicate the optional 's'

[bjlittle]

Done.