Behaviour of Iris.Constraint when time coordinate has bounds information.

[Chris Roberts]

I am looking at some monthly data and am confused by the default behaviour of iris.Constraint when coordinates have bounds information as well as points values. In the following example, the months before and after my constraint period are being let through.

dtmin = datetime.datetime(2000,1,1,0,0,0)
dtmax = datetime.datetime(2001,1,1,0,0,0)
tu = cube.coord('time').units
dtrange = iris.Constraint(time = lambda t: tu.date2num(dtmin) <= t <= tu.date2num(dtmax))
cube = cube.extract(dtrange)

print tu.num2date(cube.coord('time').points.min())
>1999-12-16 12:00:00

print tu.num2date(cube.coord('time').points.max())
> 2001-01-16 12:00:00

If I remove the bounds information from the coordinate, this problem goes away. Bizarrely, if I use "<" instead of "<=", I get the opposite problem and lose Jan and Dec 2000. I have a workaround for this, which involves adding an auxiliary coordinate with no bounds information. However, it also worries me that this behaviour may also be affecting extract operations using geographical constraints.

What should be the default behaviour of iris.Constraint?
Is there a way to specify the point/bound that the constraint should be applied to?

Thanks,
Chris

[Phil Elson]

From memory, you can specify the point or bound constraint in the lambda function with:

dtrange = iris.Constraint(time = lambda t: t.bound is not None and tu.date2num(dtmin) <= t.bound <= tu.date2num(dtmax))

Notice how you should check that the coordinate is bounded (if that is what you want) otherwise this will fail as soon as a time coordinate arrives which does not have bounds.

This is possible because the actual object that is being put to the function, named t in your case, is a Cell instance. There is a note on cell comparison here: http://scitools.org.uk/iris/docs/latest/iris/iris/coords.html?highlight=cell#iris.coords.Cell . In particular it states:

Notes on cell comparison:

Cells are compared in two ways, depending on whether they are compared to another Cell, or to a number/string.

Cell-Cell comparison is defined to produce a strict ordering. If two cells are not exactly equal (i.e. including whether they both define bounds or not) then they will have a consistent relative order.

Cell-number and Cell-string comparison is defined to support Constraint matching. The number/string will equal the Cell if, and only if, it is within the Cell (including on the boundary). The relative comparisons (lt, le, ..) are defined to be consistent with this interpretation. So for a given value n and Cell cell, only one of the following can be true:

n < cell

n == cell

n > cell

Similarly, n <= cell implies either n < cell or n == cell. And n >= cell implies either n > cell or n == cell.

HTH

[Chris Roberts]

Thanks Phil - I think the simple solution to my problem is to explicitly make the comparison using the point (or bounds) values as required:

trange = iris.Constraint(time = lambda t: tmin <= t.point <= tmax)

As ever, the solution is straightforward once you what to do. In this case, I needed to know that the lambda function is operating on a Cell instance and that cells are compared in a specific way. However, I am finding it hard work to navigate the iris documentation without being pointed to the correct solution by someone else. Is there a plan to make the documentation easier to follow for those of us who are not yet completely familiar with object oriented design (and the documentation of classes that have a a lot of inherited functionality)? Alternatively, will the number of examples be beefed-up?

Thanks,
Chris

[Matthew Mizielinski]

I've just hit this problem myself, but in a slightly different context; extracting a region from a cube in which the spatial coordinate bounds have been generated through guess_bounds and gaining unexpected cells .

While I can see the logic and can just about follow the explanation linked to by Phil, the location of this information needs to be dramatically improved - this should be made crystal clear in the user guide with plenty of examples (including something in the gallery).

As with most things in Iris the functionality is there and generally works well when you find out how to use it, but the documentation is grossly inadequate in some areas - we NEED more and better examples and a suitable user guide.

If core developer time cannot be made available for improving the documentation, it may be worth contriving some way for the user community to add to or comment on the documentation.

[esc24]

I feel that good documentation is vital, but we are devoting time to improve it. We've recently seen new gallery examples, bugfixes to the userguide and reference docs. Take a look at the recent list of pull requests that have been merged. That said, we know it could be better and would welcome any help users can offer. However, I don't think there is a need to contrive anything. Iris is an open source project and the same mechanism for contributing to the source code applies to the documentation. Contributions to the documentation are very welcome. I'd love to see github issues highlighting errors or even better Pull Requests fixing those errors in the reference documentation, adding to the userguide or adding new examples to the gallery.

[Damien Irving]

I figure this must be a pretty common issue, since CMIP5 data files (for instance) include time axis bounds.

This solution of using t.point works for defining a constraint between an upper and lower time, but what about for this kind of usage (which is common in the online user guide)?

time_constraint = iris.Constraint(time=iris.time.PartialDateTime(month=6))

Is there an elegant way to make this type of time constraint work for files that contain time axis bounds?