Timespan¶

class lsst.daf.butler.Timespan(begin: Union[astropy.time.core.Time, lsst.daf.butler.core.timespan._SpecialTimespanBound, None], end: Union[astropy.time.core.Time, lsst.daf.butler.core.timespan._SpecialTimespanBound, None], padInstantaneous: bool = True, _nsec: Optional[Tuple[int, int]] = None)¶

Bases: object

A half-open time interval with nanosecond precision.

Parameters:

begin : astropy.time.Time, Timespan.EMPTY, or None: Minimum timestamp in the interval (inclusive). None indicates that the timespan has no lower bound. Timespan.EMPTY indicates that the timespan contains no times; if this is used as either bound, the other bound is ignored.
end : astropy.time.Time, SpecialTimespanBound, or None: Maximum timestamp in the interval (exclusive). None indicates that the timespan has no upper bound. As with begin, Timespan.EMPTY creates an empty timespan.
padInstantaneous : bool, optional: If True (default) and begin == end after discretization to integer nanoseconds, extend end by one nanosecond to yield a finite-duration timespan. If False, begin == end evaluates to the empty timespan.
_nsec : tuple of int, optional: Integer nanosecond representation, for internal use by Timespan and TimespanDatabaseRepresentation implementation only. If provided, all other arguments are are ignored.

Raises:

TypeError: Raised if begin or end has a type other than astropy.time.Time, and is not None or Timespan.EMPTY.
ValueError: Raised if begin or end exceeds the minimum or maximum times supported by this class.

Notes

Timespans are half-open intervals, i.e. [begin, end).

Any timespan with begin > end after nanosecond discretization (begin >= end if padInstantaneous is False), or with either bound set to Timespan.EMPTY, is transformed into the empty timespan, with both bounds set to Timespan.EMPTY. The empty timespan is equal to itself, and contained by all other timespans (including itself). It is also disjoint with all timespans (including itself), and hence does not overlap any timespan - this is the only case where contains does not imply overlaps.

Finite timespan bounds are represented internally as integer nanoseconds, and hence construction from astropy.time.Time (which has picosecond accuracy) can involve a loss of precision. This is of course deterministic, so any astropy.time.Time value is always mapped to the exact same timespan bound, but if padInstantaneous is True, timespans that are empty at full precision (begin > end, begin - end < 1ns) may be finite after discretization. In all other cases, the relationships between full-precision timespans should be preserved even if the values are not.

The astropy.time.Time bounds that can be obtained after construction from Timespan.begin and Timespan.end are also guaranteed to round-trip exactly when used to construct other Timespan instances.

Attributes Summary

`EMPTY`
`begin`	Minimum timestamp in the interval, inclusive.
`end`	Maximum timestamp in the interval, exclusive.

Methods Summary

`contains`(other, …)	Test whether the intersection of this timespan with another timespan or point is equal to the other one.
`difference`(other)	Return the one or two timespans that cover the interval(s) that are in `self` but not `other`.
`fromInstant`(time)	Construct a timespan that approximates an instant in time by a minimum-possible (1 ns) duration timespan.
`intersection`(*args)	Return a new `Timespan` that is contained by all of the given ones.
`isEmpty`()	Test whether `self` is the empty timespan (`bool`).
`makeEmpty`()	Construct an empty timespan.
`overlaps`(other)	Test whether the intersection of this Timespan with another is empty.

Attributes Documentation

EMPTY = 1¶

begin¶

Minimum timestamp in the interval, inclusive.

If this bound is finite, this is an astropy.time.Time instance. If the timespan is unbounded from below, this is None. If the timespan is empty, this is the special value Timespan.EMPTY.

end¶

Maximum timestamp in the interval, exclusive.

If this bound is finite, this is an astropy.time.Time instance. If the timespan is unbounded from above, this is None. If the timespan is empty, this is the special value Timespan.EMPTY.

Methods Documentation

contains(other: Union[astropy.time.core.Time, lsst.daf.butler.core.timespan.Timespan]) → bool¶

Test whether the intersection of this timespan with another timespan or point is equal to the other one.

Parameters:	other : `Timespan` or `astropy.time.Time`. Timespan or instant in time to relate to `self`.
Returns:	overlaps : `bool` The result of the contains test.

Notes

If other is empty, True is always returned. In all other cases, self.contains(other) being True implies that self.overlaps(other) is also True.

Testing whether an instantaneous astropy.time.Time value is contained in a timespan is not equivalent to testing a timespan constructed via Timespan.fromInstant, because Timespan cannot exactly represent zero-duration intervals. In particular, [a, b) contains the time b, but not the timespan [b, b + 1ns) that would be returned by Timespan.fromInstant(b)`.

difference(other: lsst.daf.butler.core.timespan.Timespan) → Generator[lsst.daf.butler.core.timespan.Timespan, None, None]¶

Return the one or two timespans that cover the interval(s) that are in self but not other.

This is implemented as a generator because the result may be zero, one, or two Timespan objects, depending on the relationship between the operands.

Parameters:	other : `Timespan` Timespan to subtract.
Yields:	result : `Timespan` A `Timespan` that is contained by `self` but does not overlap `other`. Guaranteed not to be empty.

classmethod fromInstant(time: astropy.time.core.Time) → lsst.daf.butler.core.timespan.Timespan¶

Construct a timespan that approximates an instant in time by a minimum-possible (1 ns) duration timespan.

This is equivalent to Timespan(time, time, padInstantaneous=True), but may be slightly more efficient.

Parameters:	time : `astropy.time.Time` Time to use for the lower bound.
Returns:	instant : `Timespan` A `[time, time + 1ns)` timespan.

intersection(*args) → lsst.daf.butler.core.timespan.Timespan¶

Return a new Timespan that is contained by all of the given ones.

Parameters:	*args All positional arguments are `Timespan` instances.
Returns:	intersection : `Timespan` The intersection timespan.

isEmpty() → bool¶: Test whether self is the empty timespan (bool).

classmethod makeEmpty() → lsst.daf.butler.core.timespan.Timespan¶

Construct an empty timespan.

Returns:	empty : `Timespan` A timespan that is contained by all timespans (including itself) and overlaps no other timespans (including itself).

overlaps(other: lsst.daf.butler.core.timespan.Timespan) → bool¶

Test whether the intersection of this Timespan with another is empty.

Parameters:	other : `Timespan` Timespan to relate to `self`.
Returns:	overlaps : `bool` The result of the overlap test.

Notes

If either self or other is empty, the result is always False. In all other cases, self.contains(other) being True implies that self.overlaps(other) is also True.

Navigation

Timespan¶