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.