CDFepoch

class cdflib.epochs.CDFepoch[source][source]

Bases: object

Convert between CDF-based epochs, np.datetime64, and Unix time.

There are three (3) epoch data types in CDF:

1. CDF_EPOCH is milliseconds since Year 0 represented as a single double (float in Python), 2. CDF_EPOCH16 is picoseconds since Year 0 represented as 2-doubles (complex in Python), and 3. CDF_TIME_TT2000 (TT2000 as short) is nanoseconds since J2000 with leap seconds, represented by an 8-byte integer (int in Python).

In Numpy, they are np.float64, np.complex128 and np.int64, respectively. All these epoch values can come from from CDF.varget function.

Example

>>> import cdflib
# Convert to an epoch
>>> epoch = cdflib.cdfepoch.compute_epoch([2017,1,1,1,1,1,111])
# Convert from an epoch
>>> time = cdflib.cdfepoch.to_datetime(epoch)  # Or pass epochs via CDF.varget.

Attributes Summary

DAYinNanoSecs

DEFAULT_TT2000_PADVALUE

FILLED_TT2000_VALUE

HOURinNanoSecs

J2000LeapSeconds

J2000Since0AD12h

J2000Since0AD12hMilsec

J2000Since0AD12hSec

JDY17070922

JDY22920411

JulianDateJ2000_12h

LTS

MINUTEinNanoSecs

MJDbase

NDAT

NERA1

NST

SECinNanoSecs

SECinNanoSecsD

T12hinNanoSecs

csv_row

currentDay

currentJDay

currentLeapSeconds

dT

dTinNanoSecs

increment

lsfile

lsreader

month_Token

r

release

row

version

Methods Summary

breakdown(epochs)

returns:

1D if scalar input, 2D otherwise.

breakdown_epoch(epochs)

Calculate date and time from epochs

breakdown_epoch16(epochs)

Calculate date and time from epochs

breakdown_tt2000(tt2000)

Breaks down the epoch(s) into UTC components.

compute(datetimes)

Computes the provided date/time components into CDF epoch value(s).

compute_epoch(dates)

compute_epoch16(datetimes)

compute_tt2000(datetimes)

encode(epochs[, iso_8601])

Converts one or more epochs into UTC strings.

encode_epoch(epochs[, iso_8601])

encode_epoch16(epochs[, iso_8601])

encode_tt2000(tt2000[, iso_8601])

epochrange_epoch(epochs[, starttime, endtime])

epochrange_epoch16(epochs[, starttime, endtime])

epochrange_tt2000(epochs[, starttime, endtime])

findepochrange(epochs[, starttime, endtime])

Finds the record range within the start and end time from values of a CDF epoch data type.

parse(value)

Parses the provided date/time string(s) into CDF epoch value(s).

to_datetime(cdf_time)

Converts CDF epoch argument to numpy.datetime64.

unixtime(cdf_time)

Converts CDF epoch argument into seconds after 1970-01-01.

Attributes Documentation

DAYinNanoSecs = 86400000000000[source]
DEFAULT_TT2000_PADVALUE = -9223372036854775807[source]
FILLED_TT2000_VALUE = -9223372036854775808[source]
HOURinNanoSecs = 3600000000000[source]
J2000LeapSeconds = 32.0[source]
J2000Since0AD12h = 730485[source]
J2000Since0AD12hMilsec = 63113904000000.0[source]
J2000Since0AD12hSec = 63113904000.0[source]
JDY17070922 = 2344793[source]
JDY22920411 = 2558297[source]
JulianDateJ2000_12h = 2451545[source]
LTS = [[1960, 1, 1, 1.417818, 37300.0, 0.001296], [1961, 1, 1, 1.422818, 37300.0, 0.001296], [1961, 8, 1, 1.372818, 37300.0, 0.001296], [1962, 1, 1, 1.845858, 37665.0, 0.0011232], [1963, 11, 1, 1.945858, 37665.0, 0.0011232], [1964, 1, 1, 3.24013, 38761.0, 0.001296], [1964, 4, 1, 3.34013, 38761.0, 0.001296], [1964, 9, 1, 3.44013, 38761.0, 0.001296], [1965, 1, 1, 3.54013, 38761.0, 0.001296], [1965, 3, 1, 3.64013, 38761.0, 0.001296], [1965, 7, 1, 3.74013, 38761.0, 0.001296], [1965, 9, 1, 3.84013, 38761.0, 0.001296], [1966, 1, 1, 4.31317, 39126.0, 0.002592], [1968, 2, 1, 4.21317, 39126.0, 0.002592], [1972, 1, 1, 10.0, 0.0, 0.0], [1972, 7, 1, 11.0, 0.0, 0.0], [1973, 1, 1, 12.0, 0.0, 0.0], [1974, 1, 1, 13.0, 0.0, 0.0], [1975, 1, 1, 14.0, 0.0, 0.0], [1976, 1, 1, 15.0, 0.0, 0.0], [1977, 1, 1, 16.0, 0.0, 0.0], [1978, 1, 1, 17.0, 0.0, 0.0], [1979, 1, 1, 18.0, 0.0, 0.0], [1980, 1, 1, 19.0, 0.0, 0.0], [1981, 7, 1, 20.0, 0.0, 0.0], [1982, 7, 1, 21.0, 0.0, 0.0], [1983, 7, 1, 22.0, 0.0, 0.0], [1985, 7, 1, 23.0, 0.0, 0.0], [1988, 1, 1, 24.0, 0.0, 0.0], [1990, 1, 1, 25.0, 0.0, 0.0], [1991, 1, 1, 26.0, 0.0, 0.0], [1992, 7, 1, 27.0, 0.0, 0.0], [1993, 7, 1, 28.0, 0.0, 0.0], [1994, 7, 1, 29.0, 0.0, 0.0], [1996, 1, 1, 30.0, 0.0, 0.0], [1997, 7, 1, 31.0, 0.0, 0.0], [1999, 1, 1, 32.0, 0.0, 0.0], [2006, 1, 1, 33.0, 0.0, 0.0], [2009, 1, 1, 34.0, 0.0, 0.0], [2012, 7, 1, 35.0, 0.0, 0.0], [2015, 7, 1, 36.0, 0.0, 0.0], [2017, 1, 1, 37.0, 0.0, 0.0]][source]
MINUTEinNanoSecs = 60000000000[source]
MJDbase = 2400000.5[source]
NDAT = 42[source]
NERA1 = 14[source]
NST: List[int] | None = None[source]
SECinNanoSecs = 1000000000[source]
SECinNanoSecsD = 1000000000.0[source]
T12hinNanoSecs = 43200000000000[source]
csv_row = ['2017', '1', '1', '37.0', '0.0', '0.0'][source]
currentDay = -1[source]
currentJDay = -1[source]
currentLeapSeconds: float = -1[source]
dT = 32.184[source]
dTinNanoSecs = 32184000000[source]
increment = 0[source]
lsfile = <_io.TextIOWrapper name='/home/docs/checkouts/readthedocs.org/user_builds/cdf-lib/envs/latest/lib/python3.9/site-packages/cdflib/CDFLeapSeconds.txt' mode='r' encoding='UTF-8'>[source]
lsreader = <_csv.reader object>[source]
month_Token = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][source]
r = '0.0'[source]
release = 7[source]
row: List[int | float] = [2017, 1, 1, 37.0, 0.0, 0.0][source]
version = 3[source]

Methods Documentation

static breakdown(epochs)[source][source]
Returns:

1D if scalar input, 2D otherwise.

Return type:

np.ndarray

Parameters:

epochs (int | int64 | float | float64 | complex | complex128 | List[int] | List[int64] | List[float] | List[float64] | List[complex] | List[complex128] | ndarray[Any, dtype[_ScalarType_co]]) –

static breakdown_epoch(epochs)[source][source]

Calculate date and time from epochs

Parameters:

epochs (int, float, or array-like) – Single, list, tuple, or np.array of epoch values

Returns:

components – List or array of date and time values. The last axis contains (in order): year, month, day, hour, minute, second, and millisecond

Return type:

list

Notes

If a bad epoch (-1.0e31) is supplied, a fill date of 9999-12-31 23:59:59 and 999 ms is returned.

static breakdown_epoch16(epochs)[source][source]

Calculate date and time from epochs

Parameters:

epochs (array-like) – Single, list, tuple, or np.array of epoch values

Returns:

components – List or array of date and time values. The last axis contains (in order): year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, and picosecond

Return type:

ndarray

Notes

If a bad epoch (-1.0e31 for the real and imaginary components) is supplied, a fill date of 9999-12-31 23:59:59 and 999 ms, 999 us, 999 ns, and 999 ps is returned

static breakdown_tt2000(tt2000)[source][source]

Breaks down the epoch(s) into UTC components.

For CDF_EPOCH:

they are 7 date/time components: year, month, day, hour, minute, second, and millisecond

For CDF_EPOCH16:

they are 10 date/time components: year, month, day, hour, minute, second, and millisecond, microsecond, nanosecond, and picosecond.

For TT2000:

they are 9 date/time components: year, month, day, hour, minute, second, millisecond, microsecond, nanosecond.

Parameters:

tt2000 (int | int64 | List[int] | ndarray[Any, dtype[int64]]) –

Return type:

ndarray

static compute(datetimes)[source][source]

Computes the provided date/time components into CDF epoch value(s).

For CDF_EPOCH:

For computing into CDF_EPOCH value, each date/time elements should have exactly seven (7) components, as year, month, day, hour, minute, second and millisecond, in a list. For example: [[2017,1,1,1,1,1,111],[2017,2,2,2,2,2,222]] Or, call function compute_epoch directly, instead, with at least three (3) first (up to seven) components. The last component, if not the 7th, can be a float that can have a fraction of the unit.

For CDF_EPOCH16:

They should have exactly ten (10) components, as year, month, day, hour, minute, second, millisecond, microsecond, nanosecond and picosecond, in a list. For example: [[2017,1,1,1,1,1,123,456,789,999],[2017,2,2,2,2,2,987,654,321,999]] Or, call function compute_epoch directly, instead, with at least three (3) first (up to ten) components. The last component, if not the 10th, can be a float that can have a fraction of the unit.

For TT2000:

Each TT2000 typed date/time should have exactly nine (9) components, as year, month, day, hour, minute, second, millisecond, microsecond, and nanosecond, in a list. For example: [[2017,1,1,1,1,1,123,456,789],[2017,2,2,2,2,2,987,654,321]] Or, call function compute_tt2000 directly, instead, with at least three (3) first (up to nine) components. The last component, if not the 9th, can be a float that can have a fraction of the unit.

Parameters:

datetimes (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

Return type:

float | complex | ndarray[Any, dtype[_ScalarType_co]]

static compute_epoch(dates)[source][source]
Parameters:

dates (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

Return type:

float | ndarray[Any, dtype[_ScalarType_co]]

static compute_epoch16(datetimes)[source][source]
Parameters:

datetimes (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

Return type:

complex | ndarray[Any, dtype[complex128]]

static compute_tt2000(datetimes)[source][source]
Parameters:

datetimes (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

Return type:

int | ndarray[Any, dtype[int64]]

static encode(epochs, iso_8601=True)[source][source]

Converts one or more epochs into UTC strings. The input epoch format is deduced from the argument type.

Parameters:

  • epochs (int, float, list, complex) – One or more ECD epochs in one of three formats: 1. CDF_EPOCH: The input should be either a float or list of floats (in numpy, a np.float64 or a np.ndarray of np.float64) 2. CDF_EPOCH16: The input should be either a complex or list of complex(in numpy, a np.complex128 or a np.ndarray of np.complex128) 3. TT2000: The input should be either a int or list of ints (in numpy, a np.int64 or a np.ndarray of np.int64)

  • iso_8601 (bool) – The return time format. If ISO 8601 is True, the format is, for example, 2008-02-02T06:08:10.10.012014016, otherwise the format is 02-Feb-2008 06:08:10.012.014.016.

Return type:

str | List[str]

static encode_epoch(epochs, iso_8601=True)[source][source]
Parameters:
Return type:

str | List[str]

static encode_epoch16(epochs, iso_8601=True)[source][source]
Parameters:
Return type:

str | List[str]

static encode_tt2000(tt2000, iso_8601=True)[source][source]
Parameters:
Return type:

str | List[str]

static epochrange_epoch(epochs, starttime=None, endtime=None)[source][source]
Parameters:
Return type:

ndarray

static epochrange_epoch16(epochs, starttime=None, endtime=None)[source][source]
Parameters:
Return type:

ndarray | None

static epochrange_tt2000(epochs, starttime=None, endtime=None)[source][source]
Parameters:
Return type:

ndarray[Any, dtype[_ScalarType_co]]

static findepochrange(epochs, starttime=None, endtime=None)[source][source]

Finds the record range within the start and end time from values of a CDF epoch data type. It returns a list of record numbers. If the start time is not provided, then it is assumed to be the minimum possible value. If the end time is not provided, then the maximum possible value is assumed. The epoch is assumed to be in the chronological order. The start and end times should have the proper number of date/time components, corresponding to the epoch’s data type.

The start/end times should be in either be in epoch units, or in the list format described in “compute_epoch/epoch16/tt2000” section.

Parameters:
Return type:

ndarray

static parse(value)[source][source]

Parses the provided date/time string(s) into CDF epoch value(s).

For CDF_EPOCH:

The string has to be in the form of ‘dd-mmm-yyyy hh:mm:ss.xxx’ or ‘yyyy-mm-ddThh:mm:ss.xxx’ (in iso_8601). The string is the output from encode function.

For CDF_EPOCH16:

The string has to be in the form of ‘dd-mmm-yyyy hh:mm:ss.mmm.uuu.nnn.ppp’ or ‘yyyy-mm-ddThh:mm:ss.mmmuuunnnppp’ (in iso_8601). The string is the output from encode function.

For TT2000:

The string has to be in the form of ‘dd-mmm-yyyy hh:mm:ss.mmm.uuu.nnn’ or ‘yyyy-mm-ddThh:mm:ss.mmmuuunnn’ (in iso_8601). The string is the output from encode function.

Parameters:

value (str | Tuple[str, ...] | List[str]) –

Return type:

ndarray

classmethod to_datetime(cdf_time)[source][source]

Converts CDF epoch argument to numpy.datetime64. This method converts a scalar, or array-like. Precision is only kept to the nearest microsecond.

Parameters:

cdf_time (int | int64 | float | float64 | complex | complex128 | List[int] | List[int64] | List[float] | List[float64] | List[complex] | List[complex128] | ndarray[Any, dtype[_ScalarType_co]]) –

Return type:

ndarray[Any, dtype[datetime64]]

static unixtime(cdf_time)[source][source]

Converts CDF epoch argument into seconds after 1970-01-01. This method converts a scalar, or array-like. Precision is only kept to the nearest microsecond.

Parameters:

cdf_time (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

Return type:

float | ndarray[Any, dtype[_ScalarType_co]]