curryer.spicetime.convert¶

Convert between time formats (ttype).

Routine Listings¶

adapt: Convert from one time format to another. Maintains container type (e.g., scalar input returns a scalar, list input returns a list).
SpiceTime: Subclass of numpy’s ndarray that stores the data’s time format ttype, and facilitates converting to other time formats.

Examples

>>> utc = adapt([0, 1], from_='ugps', to='utc')
>>> print('Adapt API:
        {!r}
        type={}'.format(utc, type(utc)))
Adapt API:
        ['1980-01-06 00:00:00.000000', '1980-01-06 00:00:00.000001']
        type=<class 'list'>

>>> ugps = SpiceTime([0, 1], ttype='ugps')
>>> utc_arr = ugps.to_utc()
>>> print('SpiceTime API:
        {!r}'.format(utc_arr))
SpiceTime API:
        SpiceTime(['1980-01-06 00:00:00.000000', '1980-01-06 00:00:00.000001'],
      dtype='<U26', ttype='utc')

@author: Brandon Stone

Attributes¶

`conversions`
`TTYPE_TO_DTYPE`
`_py_to_spice_format`
`PY_TO_SPICE_FORMAT`

Classes¶

SpiceTime

SPICE Date and Time Conversions.

Functions¶

`adapt`(dt_val[, from_, to])	Convert between different date time formats.
`from_et`(dt_val)	Convert times from Ephemeris Time (SPICE; float64).
`from_ugps`(dt_val)	Convert times from GPS microseconds.
`from_gps`(dt_val)	Convert times from GPS seconds.
`from_tai`(dt_val)	Convert times from International Atomic Time seconds (1958).
`from_utc`(dt_val)	Convert times from UTC string(s) (ISO format).
`to_et`(dt_val)	Convert times to Ephemeris Time (SPICE; float64).
`to_ugps`(dt_val)	Convert times to GPS microseconds (int64).
`to_gps`(dt_val)
`to_tai`(dt_val)	Convert times to International Atomic Time seconds (1958; float64).
`to_utc`(dt_val[, date_format])	Convert times to UTC strings (ISO format).
`spice_strftime`(date_format)	Convert a Python datetime format string to an equivalent SPICE string.

Module Contents¶

curryer.spicetime.convert.adapt(dt_val, from_=None, to=None, **kwargs)¶

Convert between different date time formats.

Time Formats¶

etfloat64, seconds: Ephemeris time, seconds since J2000 in ET. Also called Barycentric Dynamical Time (TDB) in SPICE documentation. Most times are converted to and from ET.
ugpsint64, microseconds: GPS microseconds since 1980-01-06T00:00:00.0 UTC. Supports native (no SPICE) conversion to/from dt64 and epoch et al.
gpsfloat64, seconds: GPS seconds since 1980-01-06T00:00:00.0 UTC.
taifloat64, seconds: International Atomic Time, seconds since 1958-01-01T00:00:00.0 UTC. NOTE: Within the SPICE system “TAI” often represents the J2000 epoch, we deviate from that to support the standard 1958 epoch.
utcstr, ISO: Coordinated Universal Time (UTC), including leapseconds. The default input and output format is ISO. The output format can be specified with a Python-style datetime format string and the keyword date_format (e.g.,`date_format=’%Y-%d-%m’`). Some format keys are not supported.
isostr, ISO: Alias for utc.
dt64np.datetime64, ns: Numpy datetime64 type with nanosecond precision. Does not support leapseconds. Default is to round those times up to the nearest second. Set ceil_leapseconds=False to raise errors instead.
epochfloat64, days: Fractional days since an epoch without leapseconds. The epoch name is defined with from_epoch or to_epoch, depending on the direction. See sds_spice.spicetime.constants.EpochGpsDays. Typically results in a loss of microsecond precision. Leapseconds are accounted for when determining the day, but the fraction for days with leapseconds assumes 8.64e4 seconds per day (no leapsecond). Times within leapseconds are rounded up.
sorcefloat64, days: Fractional days since 2003-01-24. See epoch for details.
tctefloat64, days: Fractional days since 2013-11-18. See epoch for details.
tsisfloat64, days: Fractional days since 2017-12-14. See epoch for details.
tsis1float64, days: Alias for tsis. See tsis for details.
tsis2float64, days: Fractional days since 2017-12-14 (placeholder; launch TBD). See epoch for details.
ctimfloat64, days: Fractional days since 2022-07-02. See epoch for details.
gpsdfloat64, days: Fractional days since 1980-01-06. See epoch for details.
mjdfloat64, days: Fractional days since the Modified Julian epoch (1858-11-17). See epoch for details.
jdfloat64, days: Fractional days since the Julian epoch. See epoch for details. Least precision of all time formats.

param dt_val:: One or more time values to convert from one time format to another.
type dt_val:: scalar or list or tuple or numpy.ndarray of str or int or float
param from_:: Time format (ttype) of the input data dt_val. Default=’ugps’. Note: Either one or both of from_ or to must be specified.
type from_:: str, optional
param to:: Time format (ttype) to convert the input data dt_val, to. Default=’ugps’. Note: Either one or both of from_ or to must be specified.
type to:: str, optional
param **kwargs:: Passes extra keywords that are not None to the conversion functions that support them (e.g., “date_format” when to=”utc”).
returns:: The converted time(s). Each time value has the data type of output time format specified by to (e.g., str for “utc”). When converting multiple times, the output container matches the input dt_val.
rtype:: scalar or list or tuple or numpy.ndarray of str or int or float

curryer.spicetime.convert.from_et(dt_val)¶: Convert times from Ephemeris Time (SPICE; float64).

curryer.spicetime.convert.from_ugps(dt_val)¶: Convert times from GPS microseconds.

curryer.spicetime.convert.from_gps(dt_val)¶: Convert times from GPS seconds.

curryer.spicetime.convert.from_tai(dt_val)¶: Convert times from International Atomic Time seconds (1958).

curryer.spicetime.convert.from_utc(dt_val)¶: Convert times from UTC string(s) (ISO format).

curryer.spicetime.convert.to_et(dt_val)¶: Convert times to Ephemeris Time (SPICE; float64).

curryer.spicetime.convert.to_ugps(dt_val)¶: Convert times to GPS microseconds (int64).

curryer.spicetime.convert.to_gps(dt_val)¶

curryer.spicetime.convert.to_tai(dt_val)¶: Convert times to International Atomic Time seconds (1958; float64).

curryer.spicetime.convert.to_utc(dt_val, date_format=None)¶: Convert times to UTC strings (ISO format).

curryer.spicetime.convert.conversions¶

curryer.spicetime.convert.TTYPE_TO_DTYPE¶

class curryer.spicetime.convert.SpiceTime(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)¶

Bases: numpy.ndarray

SPICE Date and Time Conversions.

Time Formats¶

etfloat64, seconds: Ephemeris time, seconds since J2000 in ET. Also called Barycentric Dynamical Time (TDB) in SPICE documentation. All times are converted to and from ET.
ugpsint64, microseconds: GPS microseconds since 1980-01-06T00:00:00.0 UTC.
gpsfloat64, seconds: GPS seconds since 1980-01-06T00:00:00.0 UTC.
taifloat64, seconds: International Atomic Time, seconds since 1958-01-01T00:00:00.0 UTC. NOTE: Within the SPICE system “TAI” often represents the J2000 epoch, we deviate from that to support the standard 1958 epoch.
utcstr, ISO: Coordinated Universal Time (UTC), including leapseconds. The default input and output format is ISO. The output format can be specified with a Python-style datetime format string and the keyword date_format (e.g.,`date_format=’%Y-%d-%m’`). Some format keys are not supported.

ttype¶

Date time format (e.g., “ugps”). Read-only, unless None.

Type:: str

param in_arr:: Scalar or array of times.
type in_arr:: float
param ttype:: Supported format string specifying the input time format.
type ttype:: str

Examples

>>> st = SpiceTime('2016-05-09 14:49:17.371099', 'utc')
>>> print(repr(st))
SpiceTime('2016-05-09 14:49:17.371099',
      dtype='<U26', ttype='utc')

>>> print('Ephemeris Time: {}'.format(st.to_et()))
Ephemeris Time: 516077425.55644935

>>> print('uGPS: {}'.format(st.to_ugps()))
uGPS: 1146840574371099

>>> gps = st.to_gps()
>>> print(gps.ttype)
gps

>>> st = SpiceTime([0, 1], 'gps')
>>> print(st, st.ttype)
[ 0.  1.] gps

>>> print(st.to_utc('%S.%f'))
['00.000000' '01.000000']

Notes

Requires a leapsecond kernel to be loaded (automated by library).

__array_finalize__(obj)¶

Numpy’s replacement for “__init__”, supports construction, casting, and templates.

Notes

Three possible ways to create this subclass:

Explicit construction: arr = SpiceTime(np.arange(3), fmt=’et’)
type(obj) is ndarray; self is built in SpiceTime.__new__
View casting: arr = np.arange(3).view(SpiceTime)
type(obj) can be SpiceTime or another
New-from-template: arr = np.SpiceTime(arange(3))[1:]
type(obj) is SpiceTime

The optional method __array_prepare__ is similar, but before the values are calculated.

References

https://docs.scipy.org/doc/numpy/user/basics.subclassing.html

__array_prepare__(out_arr, context=None)¶: Numpy’s way of supporting subclassing from ufuncs (e.g., np.min(et_arr)). Allows viewing (ONLY) the output data structure and context (func & args) before the calculation.

__array_wrap__(out_arr, context=None)¶: Numpy’s way of supporting subclassing from ufuncs (e.g., np.min(et_arr)). Allows tweaking the output (out_arr), before final casting as SpiceTime.

__repr__()¶: String representation of the array with the time format ttype.

property ttype¶: Time format.

adapt(to, **kwargs)¶: Convert from the current time format to another.

to_et()¶: Convert times to Ephemeris Time (SPICE; float64).

to_ugps()¶: Convert times to GPS microseconds (int64).

to_gps()¶: Convert times to GPS seconds (float64).

to_tai()¶: Convert times to International Atomic Time seconds (1958; float64).

to_utc(date_format=None)¶: Convert times to UTC strings (ISO format).

curryer.spicetime.convert._py_to_spice_format¶

curryer.spicetime.convert.PY_TO_SPICE_FORMAT¶

curryer.spicetime.convert.spice_strftime(date_format)¶

Convert a Python datetime format string to an equivalent SPICE string.

Parameters:: date_format (str) – Python datetime format string (e.g., “%Y-%m-%d %H:%M:%S.%f”). NOTE: Does not support every Python format code. Formats with a non-none return in PY_TO_SPICE_FORMAT are supported.
Returns:: SPICE UTC format string.
Return type:: str

Examples

>>> py_format = '%Y-%m-%d %H:%M:%S.%f'
>>> print(spice_strftime(py_format))
'YYYY-MM-DD HR:MN:SC.######::RND ::UTC'

References

Python’s format string:: https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior
SPICE’s format string:: https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/timout_c.html#Particulars