chandra_time

Convert between various time formats relevant to Chandra.

chandra_time provides a simple interface to the C++ time conversion utility axTime3 (which itself is a wrapper for XTime) written by Arnold Rots. Chandra_time also supports some useful additional time formats.

Warning

The chandra_time package and DateTime class are deprecated. All new code should use the CxoTime class from cxotime.

Note

The Chandra.Time package is equivalent to the chandra_time and is provided for back-compatibility with legacy code.

The supported time formats are:

Format	Description	System
secs	Seconds since 1998-01-01T00:00:00 (float)	tt
numday	DDDD:hh:mm:ss.ss… Elapsed days and time	utc
relday	[+-]<float> Relative number of days from now	utc
jd	Julian Day	utc
mjd	Modified Julian Day = JD - 2400000.5	utc
date	YYYY:DDD:hh:mm:ss.ss..	utc
caldate	YYYYMonDD at hh:mm:ss.ss..	utc
fits	YYYY-MM-DDThh:mm:ss.ss..	tt
iso	YYYY-MM-DD hh:mm:ss.ss..	utc
unix	Unix time (since 1970.0)	utc
greta	YYYYDDD.hhmmss[sss]	utc
year_doy	YYYY:DDD	utc
mxDateTime	mx.DateTime object	utc
frac_year	YYYY.ffffff = date as a floating point year	utc
plotdate	Matplotlib plotdate (days since year 0)	utc
cxotime	CxoTime class object	varies

Each of these formats has an associated time system, which must be one of:

met	Mission Elapsed Time
tt	Terrestrial Time
tai	International Atomic Time
utc	Coordinated Universal Time

Usage

The normal usage is to create an object that allows conversion from one time format to another. Conversion takes place by examining the appropriate attribute. Unless the time format is specified or it is ambiguous (i.e. secs, jd, mjd, and unix), the time format is automatically determined. To specifically select a format use the ‘format’ option.:

>>> from chandra_time import DateTime
>>> t = DateTime('1999-07-23T23:56:00')
>>> print(t.date)
1999:204:23:54:55.816
>>> t.date
'1999:204:23:54:55.816'
>>> t.secs
49161360.0
>>> t.jd
2451383.496479352
>>> DateTime(t.jd + 1, format='jd').fits
'1999-07-24T23:56:00.056'
>>> DateTime(t.mjd + 1, format='mjd').caldate
'1999Jul24 at 23:54:55.820'
>>> u = DateTime(1125538824.0, format='unix')
>>> u.date
'2005:244:01:40:24.000'
>>> mxd = mx.DateTime.Parser.DateTimeFromString('1999-01-01 12:13:14')
>>> DateTime(mxd).fits
'1999-01-01T12:14:18.184'
>>> DateTime(mxd).date
'1999:001:12:13:14.000'
>>> DateTime(mxd).mxDateTime.strftime('%c')
'Fri Jan  1 12:13:14 1999'
>>> DateTime('2007122.01020340').date
'2007:122:01:02:03.400'

If no input time is supplied when creating the object then the current time is used.:

>>> DateTime().fits
'2009-11-14T18:24:14.504'

For convenience a DateTime object can be initialized from another DateTime object.

>>> t = DateTime()
>>> u = DateTime(t)

Sequences of dates

The input time can also be an iterable sequence (returns a list) or a numpy array (returns a numpy array with the same shape):

>>> import numpy
>>> DateTime([1,'2001:255',3]).date
['1997:365:23:58:57.816', '2001:255:12:00:00.000', '1997:365:23:58:59.816']
>>> DateTime(numpy.array([[1,2],[3,4]])).fits
array([['1998-01-01T00:00:01.000', '1998-01-01T00:00:02.000'],
       ['1998-01-01T00:00:03.000', '1998-01-01T00:00:04.000']],
      dtype='|S23')

Date arithmetic

DateTime objects support a limited arithmetic with a delta time expressed in days. One can add a delta time to a DateTime or subtract a delta time from a DateTime. It is also possible to subtract two DateTiem objects to get a delta time in days. If the DateTime holds a NumPy array or the delta times are NumPy arrays then the appropriate broadcasting will be done.

>>> d1 = DateTime('2011:200:00:00:00')
>>> d2 = d1 + 4.25
>>> d2.date
'2011:204:06:00:00.000'
>>> d2 - d1
4.25
>>> import numpy as np
>>> d3 = d1 + np.array([1,2,3])
>>> d3.date
array(['2011:201:00:00:00.000', '2011:202:00:00:00.000',
       '2011:203:00:00:00.000'],
      dtype='|S21')
>>> (d3 + 7).year_doy
array(['2011:208', '2011:209', '2011:210'],
      dtype='|S8')

Fast conversion functions

The DateTime class does full validation and format-detection of input values. In cases where this is not necessary a substantial improvement in speed (factor of 4 to 12) can be obtained using functions that skip the validation and format detection. See the documentation for date2secs(), secs2date(), and convert_vals().

>>> from chandra_time import date2secs, secs2date, convert_vals
>>> date2secs('2001:001:01:01:01')
94698125.18399999
>>> dates = secs2date([0, 1e8, 2e8])
>>> dates
array(['1997:365:23:58:56.816', '2001:062:09:45:35.816', '2004:124:19:32:15.816'],
      dtype='|S21')
>>> date2secs(dates)
array([  0.00000000e+00,   1.00000000e+08,   2.00000000e+08])
>>> convert_vals(dates, 'date', 'mjd')
array([ 50813.9992687 ,  51971.40666454,  53128.81407194])
>>> convert_vals(dates, 'date', 'secs')
array([  0.00000000e+00,   1.00000000e+08,   2.00000000e+08])

Input and output time system

Currently the object-oriented interface does not allow you to adjust the input or output time system. If you really need to do this, use the package function convert():

>>> import chandra_time
>>> chandra_time.convert(53614.0,
...                      fmt_in='mjd',
...                      sys_in='tt',
...                      fmt_out='caldate',
...                      sys_out='tai')
'2005Aug31 at 23:59:27.816'

The convert() routine will guess fmt_in and supply a default for sys_in if not specified. As for DateTime() the input time can be a sequence or numpy array.

Time attributes

A DateTime object has additional attributes year, mon, day, hour, min, sec, yday, and wday. These provide the year, month (1-12), day of month (1-31), hour (0-23), minute (0-59), second (0-60), day of year (1-366), and day of week (0-6, where 0 is Monday).

These are all referenced to UTC time.

Date when hour, minutes, seconds not provided

A date like 2020:001 will be taken as 2020:001:00:00:00 since version 4.0. Before 4.0, 2020:001 was 2020:001:12:00:00. To get the pre-4.0 behavior use the following code:

from chandra_time import use_noon_day_start

# Set to use 12:00:00 globally from now on.
use_noon_day_start()

Note

You should do this globally once in your code at the beginning. There is no way to revert to using 00:00:00 after calling use_noon_day_start. This impacts all code using DateTime, not just the calls from your script.

Functions

Fast conversion functions

chandra_time.Time.convert_vals(vals, format_in, format_out)

Convert vals from the input format_in to the output format format_out. This does no input validation and thus runs much faster than the corresponding DateTime() conversion. Be careful because invalid inputs can give unpredictable results.

The input vals can be a single (scalar) value, a Python list or a numpy array. The output data type is specified with dtype which must be a valid numpy dtype.

The input and output format should be one of the following DateTime format names: ‘secs’, ‘date’, ‘jd’, ‘mjd’, ‘fits’, ‘caldate’.

The function returns the converted time as either a scalar or a numpy array, depending on the input vals.

Parameters

• vals – input values (scalar, list, array)

• fmt_in – input format (e.g. ‘secs’, ‘date’, ‘jd’, ..)

• fmt_out – output format (e.g. ‘secs’, ‘date’, ‘jd’, ..)

Returns

converted values as either scalar or numpy array

chandra_time.Time.date2secs(dates)

Convert dates from the date system (e.g. ‘2011:001:12:23:45.001’) to the secs system (CXC seconds). This does no input validation and thus runs much faster than the corresponding DateTime(dates).secs conversion. Be careful because invalid inputs can give unpredictable results.

The input dates can be a single (scalar) value, a Python list or a numpy array. The shape of the output matches the shape of the input.

Parameters

dates – input dates (scalar, list, array of strings)

Returns

converted times as either scalar or numpy array (float)

chandra_time.Time.secs2date(times)

Convert times from the secs system (CXC seconds) to the date system (e.g. ‘2011:001:12:23:45.001’). This does no input validation and thus runs much faster than the corresponding DateTime(times).date conversion. Be careful because invalid inputs can give unpredictable results.

The input times can be a single (scalar) value, a Python list or a numpy array. The shape of the output matches the shape of the input.

Parameters

times – input times (scalar, list, array of floats)

Returns

converted dates as either scalar or numpy array (string)

Other functions

chandra_time.Time.convert(time_in, sys_in=None, fmt_in=None, sys_out=None, fmt_out='secs')

Base routine to convert from/to any format.

chandra_time.Time.date_to_greta(date_in)

chandra_time.Time.greta_to_date(date_in)

Classes

class chandra_time.Time.DateTime(time_in=None, format=None)

Bases: object

DateTime - Convert between various time formats

The supported time formats are:

Format	Description	System
secs	Seconds since 1998-01-01T00:00:00 (float)	tt
numday	DDDD:hh:mm:ss.ss… Elapsed days and time	utc
relday	[+-]<float> Relative number of days from now	utc
jd	Julian Day	utc
mjd	Modified Julian Day = JD - 2400000.5	utc
date	YYYY:DDD:hh:mm:ss.ss..	utc
caldate	YYYYMonDD at hh:mm:ss.ss..	utc
fits	YYYY-MM-DDThh:mm:ss.ss..	tt
iso	YYYY-MM-DD hh:mm:ss.ss..	utc
unix	Unix time (since 1970.0)	utc
greta	YYYYDDD.hhmmss[sss]	utc
year_doy	YYYY:DDD	utc
mxDateTime	mx.DateTime object	utc
frac_year	YYYY.ffffff = date as a floating point year	utc
plotdate	Matplotlib plotdate (days since 0001-01-01)	utc

Each of these formats has an associated time system, which must be one of:

met	Mission Elapsed Time
tt	Terrestrial Time
tai	International Atomic Time
utc	Coordinated Universal Time

Parameters

• time_in – input time (current time if not supplied)

• format – format of input time ()

Returns

DateTime object

property cxotime

Convert to CxoTime, bypassing the normal conversion pathway since it does not quite fit in.

day

day_end()

Return a new DateTime object corresponding to the end of the day.

day_start()

Return a new DateTime object corresponding to the start of the day.

hour

min

mon

sec

property time_attributes

wday

yday

year

class chandra_time.Time.TimeStyle(name, ax3_fmt, ax3_sys, match_expr=None, match_func=<function TimeStyle.<lambda>>, match_err=<class 'AttributeError'>, postprocess=None, preprocess=None, dtype=None)

Bases: object

match(time)

Exceptions

class chandra_time.Time.ChandraTimeError

Bases: ValueError

Exception class for bad input values to chandra_time

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.