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.
`from_json`(json_str, universe, registry)	Convert a JSON string created by `to_json` and return something of the supplied class.
`from_simple`(simple, universe, registry)	Construct a new object from the data returned from the `to_simple` method.
`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.
`to_json`(minimal)	Convert this class to JSON form.
`to_simple`(minimal)	Convert this class to a simple python type suitable for serialization.

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.

classmethod from_json(json_str: str, universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = None) → SupportsSimple¶

Convert a JSON string created by to_json and return something of the supplied class.

Parameters:	json_str : `str` Representation of the dimensions in JSON format as created by `to_json()`. universe : `DimensionUniverse`, optional The special graph of all known dimensions. Passed directly to `from_simple()`. registry : `lsst.daf.butler.Registry`, optional Registry to use to convert simple name of a DatasetType to a full `DatasetType`. Passed directly to `from_simple()`.
Returns:	constructed : Any Newly-constructed object.

classmethod from_simple(simple: List[int], universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = None) → Timespan¶

Construct a new object from the data returned from the to_simple method.

Parameters:	simple : `list` of `int` The values returned by `to_simple()`. universe : `DimensionUniverse`, optional Unused. registry : `lsst.daf.butler.Registry`, optional Unused.
Returns:	result : `Timespan` Newly-constructed object.

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.

to_json(minimal: bool = False) → str¶

Convert this class to JSON form.

The class type is not recorded in the JSON so the JSON decoder must know which class is represented.

Parameters:	minimal : `bool`, optional Use minimal serialization. Requires Registry to convert back to a full type.
Returns:	json : `str` The class in JSON string format.

to_simple(minimal: bool = False) → List[int]¶

Convert this class to a simple python type suitable for serialization.

Parameters:	minimal : `bool`, optional Use minimal serialization. Has no effect on for this class.
Returns:	simple : `list` of `int` The internal span as integer nanoseconds.

Navigation

Timespan¶