fcollections.time

Time conversion utilities, Period definition and operations.

Functions

fuse_successive_periods(periods)	Fuse multiple successive periods.
periods_envelop(periods)	Envelop of a list of periods.
periods_holes(periods)	Give a simplified complement of the input periods.
numpy_to_fractional_julian_day(timestamp[, ...])	Converts a numpy datetime to fractional julian day.
numpy_to_julian_day(timestamp[, reference])	Converts a numpy datetime to julian day as a tuple (day, hour, seconds).
julian_day_to_numpy(julian_day[, reference])	Converts a julian (day, hour, seconds) to a numpy datetime.
fractional_julian_day_to_numpy(fractional_day)	Converts a fractional julian day to a numpy datetime.
times_holes(times, sampling)

Classes

Period(start, stop[, include_start, ...])	Period representation.
ISODuration([years, months, weeks, days, ...])	ISO8601 duration.

class fcollections.time.ISODuration(years: int = 0, months: int = 0, weeks: int = 0, days: int = 0, hours: int = 0, minutes: int = 0, seconds: float = 0.0)

Bases: object

ISO8601 duration.

Because years and months cannot be directly converted to seconds without using a calendar, numpy and datetime modules do not handle them in their respective timedelta classes. This class stores the duration code - including years, months and weeks - naively, without trying to convert to seconds

See also

fcollections.core.FileNameFieldISODuration

Field that can encode and decode an duration code following the ISO8601 convention

days: int = 0

Days.

hours: int = 0

Hours.

minutes: int = 0

Minutes.

months: int = 0

Months.

seconds: float = 0.0

Seconds.

weeks: int = 0

Weeks.

years: int = 0

Years.

class fcollections.time.Period(start: datetime64, stop: datetime64, include_start: bool = True, include_stop: bool = True)

Bases: object

Period representation.

property center: datetime64

include_start: bool = True

Inclusive (True) or strict (False) start selection.

include_stop: bool = True

Inclusive (True) or strict (False) end selection.

intersection(other: datetime64 | Period) → datetime64 | Period | None

Intersection of two periods.

Parameters:

other – Second period or time to intersect with the current period. In case a time is given and there is an intersection, this time is returned.

Returns:

The intersecting Period or time, or None if there is no intersection

intersects(times: datetime64 | Period, include_time: bool = True) → bool

Check if the period intersects with another periods or time.

In case a time is given, it checks if it is contained in the period.

Parameters:

• times – The period or time to intersect with the period

• include_time – Set this to False to ignore the period bounds for the time/period intersection

Returns:

True if there is an intersection, False otherwise

start: datetime64

Date representing the start of the period.

stop: datetime64

Date representing the end of the period.

union(other: Period) → Period

Union of two periods.

Parameters:

other – Second period to combine with the current period

Returns:

A Period that encompasses both periods

fcollections.time.fractional_julian_day_to_numpy(fractional_day: float, reference: datetime64 = CNES_DATE_REFERENCE) → datetime64

Converts a fractional julian day to a numpy datetime.

Parameters:

• julian_day – Julian day given as a floating point number. The integral part is directly interpreted as the number of days since the reference. The fractional part must be converted to hour, minutes and seconds before building the numpy timestamp

• reference – Reference for the julian days (defaults to 1950-01-01)

Returns:

Numpy datetime64 matching the fractional julian day, with a microseconds precision

Return type:

timestamp

fcollections.time.fuse_successive_periods(periods: List[Period]) → Iterable[Period]

Fuse multiple successive periods.

It is expected that the periods are already sorted and do not overlap. The main use case is to have a succession of daily periods that we need to fuse [1st may, 2nd may[ | [2nd may, 3rd may[ -> [1st may, 3rd may[

Parameters:

periods – List of periods to fuse

Return type:

Iterable of fused periods

fcollections.time.julian_day_to_numpy(julian_day: tuple[int, int, float], reference: datetime64 = CNES_DATE_REFERENCE) → datetime64

Converts a julian (day, hour, seconds) to a numpy datetime.

Parameters:

• julian_day – Julian day given as a tuple (day, hour, seconds), where seconds can be a floating point number

• reference – Reference for the julian days (defaults to 1950-01-01)

Returns:

Numpy datetime64 matching the julian day, with a microseconds precision

Return type:

timestamp

fcollections.time.numpy_to_fractional_julian_day(timestamp: datetime64, reference: datetime64 = CNES_DATE_REFERENCE) → float

Converts a numpy datetime to fractional julian day.

Parameters:

• timestamp – timestamp given as a numpy datetime

• reference – Reference for the julian days (defaults to 1950-01-01)

Returns:

Julian day given as a floating point number. The integral part is directly interpreted as the number of days since the reference. The fractional part is the combination of the hours, minutes and seconds from the numpy timestamp. The fractional part has a microsecond precision

Return type:

julian_day

fcollections.time.numpy_to_julian_day(timestamp: datetime64, reference: datetime64 = CNES_DATE_REFERENCE) → tuple[int, int, float]

Converts a numpy datetime to julian day as a tuple (day, hour, seconds).

Parameters:

• timestamp – timestamp given as a numpy datetime

• reference – Reference for the julian days (defaults to 1950-01-01)

Returns:

Julian day given as a tuple (day, hour, seconds), where seconds can be a floating point number

Return type:

julian_day

fcollections.time.periods_envelop(periods: Iterable[Period]) → Period

Envelop of a list of periods.

Parameters:

periods – List of periods for which we want the encompassing interval

Returns:

The Period envelop

fcollections.time.periods_holes(periods: List[Period]) → Generator[Period, None, None]

Give a simplified complement of the input periods.

The input periods should not overlap, else this implementation will fail to return the expected complement.

[1st may, 2nd may[, [3rd may, 4th may], [5th may, 7th may] -> [2nd may, 3rd may[, ]4th may, 5th may[

Parameters:

periods – List of periods for which we want the holes

Returns:

A period Generator representing the holes in the periods list

fcollections.time.times_holes(times: np_t.NDArray[np.datetime64], sampling: np.timedelta64) → tp.Generator[Period, None, None]