Timespan¶
- class lsst.daf.butler.Timespan(begin: TimespanBound, end: TimespanBound, padInstantaneous: bool = True, _nsec: tuple[int, int] | None = None)¶
Bases:
BaseModel
A half-open time interval with nanosecond precision.
- Parameters:
- begin
astropy.time.Time
,Timespan.EMPTY
, orNone
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
, orNone
Maximum timestamp in the interval (exclusive).
None
indicates that the timespan has no upper bound. As withbegin
,Timespan.EMPTY
creates an empty timespan.- padInstantaneous
bool
, optional If
True
(default) andbegin == end
after discretization to integer nanoseconds, extendend
by one nanosecond to yield a finite-duration timespan. IfFalse
,begin == end
evaluates to the empty timespan.- _nsec
tuple
ofint
, optional Integer nanosecond representation, for internal use by
Timespan
andTimespanDatabaseRepresentation
implementation only. If provided, all other arguments are are ignored.
- begin
- Raises:
- TypeError
Raised if
begin
orend
has a type other thanastropy.time.Time
, and is notNone
orTimespan.EMPTY
.- ValueError
Raised if
begin
orend
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
ifpadInstantaneous
isFalse
), or with either bound set toTimespan.EMPTY
, is transformed into the empty timespan, with both bounds set toTimespan.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 wherecontains
does not implyoverlaps
.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 anyastropy.time.Time
value is always mapped to the exact same timespan bound, but ifpadInstantaneous
isTrue
, 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 fromTimespan.begin
andTimespan.end
are also guaranteed to round-trip exactly when used to construct otherTimespan
instances.Attributes Summary
Minimum timestamp in the interval, inclusive.
Maximum timestamp in the interval, exclusive.
Configuration for the model, should be a dictionary conforming to [
ConfigDict
][pydantic.config.ConfigDict].Metadata about the fields defined on the model, mapping of field names to [
FieldInfo
][pydantic.fields.FieldInfo].Methods Summary
contains
(other)Test if the supplied timespan is within this one.
difference
(other)Return the one or two timespans that cover the interval(s).
fromInstant
(time)Construct a timespan that approximates an instant in time.
from_day_obs
(day_obs[, offset])Construct a timespan for a 24-hour period based on the day of observation.
from_yaml
(loader, node)Convert YAML node into _SpecialTimespanBound.
intersection
(*args)Return a new
Timespan
that is contained by all of the given ones.isEmpty
()Test whether
self
is the empty timespan (bool
).Construct an empty timespan.
overlaps
(other)Test if the intersection of this Timespan with another is empty.
to_yaml
(dumper, timespan)Convert Timespan into YAML format.
Attributes Documentation
- EMPTY: ClassVar[_SpecialTimespanBound] = 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 isNone
. If the timespan is empty, this is the special valueTimespan.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 isNone
. If the timespan is empty, this is the special valueTimespan.EMPTY
.
- model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'description': 'A [begin, end) TAI timespan with bounds as integer nanoseconds since 1970-01-01 00:00:00.'}}¶
Configuration for the model, should be a dictionary conforming to [
ConfigDict
][pydantic.config.ConfigDict].
- model_fields: ClassVar[dict[str, FieldInfo]] = {'nsec': FieldInfo(annotation=tuple[int, int], required=True, frozen=True)}¶
Metadata about the fields defined on the model, mapping of field names to [
FieldInfo
][pydantic.fields.FieldInfo].This replaces
Model.__fields__
from Pydantic V1.
Methods Documentation
- contains(other: Time | Timespan) bool ¶
Test if the supplied timespan is within this one.
Tests whether the intersection of this timespan with another timespan or point is equal to the other one.
- Parameters:
- other
Timespan
orastropy.time.Time
Timespan or instant in time to relate to
self
.
- other
- Returns:
- overlaps
bool
The result of the contains test.
- overlaps
Notes
If
other
is empty,True
is always returned. In all other cases,self.contains(other)
beingTrue
implies thatself.overlaps(other)
is alsoTrue
.Testing whether an instantaneous
astropy.time.Time
value is contained in a timespan is not equivalent to testing a timespan constructed viaTimespan.fromInstant
, because Timespan cannot exactly represent zero-duration intervals. In particular,[a, b)
contains the timeb
, but not the timespan[b, b + 1ns)
that would be returned byTimespan.fromInstant(b)`
.
- difference(other: Timespan) Generator[Timespan, None, None] ¶
Return the one or two timespans that cover the interval(s).
The interval is defined as one that is in
self
but notother
.This is implemented as a generator because the result may be zero, one, or two
Timespan
objects, depending on the relationship between the operands.
- classmethod fromInstant(time: Time) Timespan ¶
Construct a timespan that approximates an instant in time.
This is done by constructing 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.
- time
- Returns:
- instant
Timespan
A
[time, time + 1ns)
timespan.
- instant
- classmethod from_day_obs(day_obs: int, offset: int = 0) Timespan ¶
Construct a timespan for a 24-hour period based on the day of observation.
- Parameters:
- Returns:
- day_span
Timespan
A timespan corresponding to a full day of observing.
- day_span
Notes
If the observing day is 20240229 and the offset is 12 hours the resulting time span will be 2024-02-29T12:00 to 2024-03-01T12:00.
- classmethod from_yaml(loader: SafeLoader, node: MappingNode) Timespan | None ¶
Convert YAML node into _SpecialTimespanBound.
- Parameters:
- loader
yaml.SafeLoader
Instance of YAML loader class.
- node
yaml.ScalarNode
YAML node.
- loader
- Returns:
- value
Timespan
Timespan instance, can be
None
.
- value
- intersection(*args: Timespan) Timespan ¶
Return a new
Timespan
that is contained by all of the given ones.
- classmethod makeEmpty() 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).
- empty
- overlaps(other: Timespan | Time) bool ¶
Test if the intersection of this Timespan with another is empty.
- Parameters:
- other
Timespan
orastropy.time.Time
Timespan or time to relate to
self
. If a single time, this is a synonym forcontains
.
- other
- Returns:
- overlaps
bool
The result of the overlap test.
- overlaps
Notes
If either
self
orother
is empty, the result is alwaysFalse
. In all other cases,self.contains(other)
beingTrue
implies thatself.overlaps(other)
is alsoTrue
.
- classmethod to_yaml(dumper: Dumper, timespan: Timespan) Any ¶
Convert Timespan into YAML format.
This produces a scalar node with a tag “!_SpecialTimespanBound” and value being a name of _SpecialTimespanBound enum.
- Parameters:
- dumper
yaml.Dumper
YAML dumper instance.
- timespan
Timespan
Data to be converted.
- dumper