Assorted improvements to Cube.intersection

[vsherratt]

🚀 Pull Request

Description

The first concern was that the documentation is not sufficiently specific. I think two key questions users will want answered when they read it are:

• For coordinates with bounds, how much of a cell must overlap with the range in order to be included?
• If requesting a full 0-360 degrees splits a cell, which side of the range does the cell go to?

From the code, it looks like the answers are, respectively:

• Essentially any overlap, unless a very small range is requested, in which case it might miss a cell - only bounds/points are checked, not the intersection as intervals.
• Lower, unless the requested range hits a cell bound exactly (only recently addressed, in Intersection bounds fix (replacement PR) #4059). This is always based on bounds, regardless of ignore_bounds, potentially taking a point out of the requested range (as in cube.intersection() returns points outside range due to bounds even when ignore_bounds is True #3698).

Instead of simply documenting those quirks, I've tried to fix them. I also introduced a threshold argument, so that the answer to "how much overlap" is "configurable" instead of "0".

---

Consult Iris pull request check list

• No whatsnew yet - mainly as I wasn't sure what category to put it under.

[wjbenfold]

https://scitools-iris.readthedocs.io/en/stable/developers_guide/documenting/whats_new_contributions.html (in case you've not seen it) has some advice on which What's new category to got for - and mentions that you can go for multiple. I'd suggest that maybe adding thresholdis a new feature, and no longer ignoring ignore_bounds is a bug fix?

[vsherratt]

Ah! Evidently I missed the "several categories may be used" part...

[wjbenfold]

Thanks for this PR, it's great to have new contributors and your changes are not only improvements, they're also significantly easier to understand.

I've popped some comments on specific lines, please let me know if anything isn't clear or if you disagree (you've definitely got more context than me on how this code is used so there may well be reasons I've missed).

[trexfeathers]

Excellent work @bsherratt and @wjbenfold, thanks so much for taking this on - a big improvement.

@wjbenfold has taken me through the changes and the conversation, and I'm happy to merge. But first @bsherratt please take a look my single comment to make sure you get the recognition you deserve (it helps nurture our community spirit!).