Addition to pearsonr documentation

[MahatmaCane]

Possible clarification of broadcastability of cubes in iris.analysis.stats.pearsonr function, by request of internal user via AVD Support e-mail account

[MahatmaCane]

Ping @bjlittle - would you mind taking a look at this please?

[ajdawson]

I'm not sure this actually makes it clearer. I think the broadcasting rules are the same as for numpy arrays, so perhaps we could just link to their existing description? (http://docs.scipy.org/doc/numpy/user/basics.broadcasting.html)

[corinnebosley]

I think a link is a good idea. The user also suggested adding an example, which I always find helpful in docstrings.

[corinnebosley]

Also, if you look at the details for the failing tests, it shows that you need to change the date at the top of the altered module to 2016 instead of 2015, and shorten line 197 by 3 letters (or split it up so that neither lines exceed 79 letters). After you've changed these things, you should pass all the integration tests when you push.

[rcomer]

The broadcasting rules here come from those in cube multiplication, which are more flexible than numpy broadcasting. If the shapes don't match in a numpy-broadcasting sense, there is an attempt to rearrange the second cube. See this try-except loop in _binary_op_common for the relevant logic.

There is some discussion of broadcasting under Cube Maths in the Iris User Guide, but perhaps we'd benefit from an extra section there that spells out what does and doesn't work. Then we could link to there from the pearsonr doc and anywhere else that uses it (and only have to update in one place if/when cube broadcasting rules change).

The flaw in my suggestion is that there are some inconsistencies with broadcasting for different types of operations, which are proving difficult to disentangle - see #1911.