`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.

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

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.

Functions¶

Fast conversion functions¶

Chandra.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.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.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.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.date_to_greta(date_in)¶

Chandra.Time.greta_to_date(date_in)¶

Classes¶

class Chandra.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

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.

time_attributes¶

class Chandra.Time.TimeStyle(name, ax3_fmt, ax3_sys, match_expr=None, match_func=<function <lambda> at 0x2b3ea8d3c938>, match_err=<type 'exceptions.AttributeError'>, postprocess=None, preprocess=None, dtype=None)¶

Bases: object

match(time)¶

Exceptions¶

class Chandra.Time.ChandraTimeError¶

Bases: exceptions.ValueError

Exception class for bad input values to Chandra.Time

args¶

message¶

`Chandra.Time`¶

Usage¶

Sequences of dates¶

Date arithmetic¶

Fast conversion functions¶

Input and output time system¶

Time attributes¶

Functions¶

Fast conversion functions¶

Other functions¶

Classes¶

Exceptions¶

Table Of Contents

Previous topic

Next topic

Navigation

Chandra.Time¶

Usage¶

Sequences of dates¶

Date arithmetic¶

Fast conversion functions¶

Input and output time system¶

Time attributes¶

Functions¶

Fast conversion functions¶

Other functions¶

Classes¶

Exceptions¶

Table Of Contents

Previous topic

Next topic

Quick search

Navigation

`Chandra.Time`¶