[fitswcs] Time WCS
William Pence
pence at tetra.gsfc.nasa.gov
Fri Feb 1 16:35:47 EST 2002
The recent postings on the FITSBITS newsgroup regarding the DATE-OBS keyword
and other time-related FITS keywords prompted me to dig out some notes I
wrote about 3 years ago on this subject. At the time I had some vague
thoughts that this might be useful when someone (not me!) writes the next
WCS paper in the series dealing with temporal coordinates. These notes are
mainly from the High Energy Astrophysics point of view, and no doubt do not
cover important time issues in other wavelength domains.
I'm posting these notes now in the hopes that any timing experts subscribing
to this fitswcs exploder will find them useful in developing a real paper
dealing with the time wcs. On the other hand, these ideas may be overly
simplistic, so I will certainly not be offended if others think this is all
rubbish, since I don't consider myself to be a time expert by any means.
-Bill Pence
---------------------------------------------------------------------------
Representations of Time Coordinates in FITS
-------------------------------------------
1. The first 4 characters of the CTYPEj WCS keyword specify the
coordinate type and will be 'TIME' for time axes.
2. The second 4 characters of the CTYPEj keyword specify the reference
frame of the time measurements. The same notation that is used for the
SPECSYS keyword in the spectral coordinate system will be used:
code location of time measurements
------- -----------------------------
-SAT on a moving satellite
-TOP at a fixed location on the earth
-GEO geocentric
-BAR barycentric
-HEL heliocentric
-LSR local standard of rest (kinematic)
-LSD local standard of rest (dynamic)
-GAL Galactocentric
-LGR local group
-SOU source reference frame
3. The time measurements will always be specified in the SI time unit
of seconds. The optional CUNITn keyword will always have a value of
's'.
4. The following time-related keywords are used by this convention:
A. Required keywords that define the time system:
MJDREF Modified Julian Date (JD - 2400000.5) at time = 0 in
the local time system
TIMESYS as defined in Appendix D of the FITS Standard: 'UTC', 'UT',
'TAI', 'AT', 'ET', 'TT', 'TDT', 'TDB', TCG', or 'TCB'
If CTYPEj = 'TIME-TOP' (topographic) then the following 3 keywords are
required to provide the positional information that is needed to perform
photon arrival time corrections:
OBS-LAT latitude of time assignment position
OBS-LONG longitude of time assignment position
OBS-ELEV altitude of time assignment position
B. Optional keywords defined in the FITS Standard or other WCS papers
for specifying the start and stop times of the observation.
DATE-OBS start date: 'yyyy-mm-dd', or 'yyyy-mm-ddThh:mm:ss.dd..'
TIME-OBS start time: 'hh:mm:ss.dd..'
DATE-END stop date: 'yyyy-mm-dd', or 'yyyy-mm-ddThh:mm:ss.dd..'
TIME-END stop time: 'hh:mm:ss.dd..'
MJD-OBS Modified Julian Date at the start of the observation
C. Optional keywords that define the start and stop of the observation
in the local time system.
TSTART local start time in units of seconds
TSTOP local stop time in units of seconds
In the case of FITS arrays, TSTART is the start time of the first
pixel, and TSTOP is the end time of the last pixel along the time
axis. If there is more than one time axis in an array (unlikely) or
more than one time column in a table, then TSTART and TSTOP will give
the values for the 'principal' time system. In the case of multiple
time columns, the TLMINn and TLMAXn keywords can be used to define the
unique start and stop times for each time column.
D. Optional keywords that define the exposure time of the observation:
TELAPSE equals TSTOP - TSTART
ONTIME total on-source exposure time; sum of GTIs
LIVETIME equals ONTIME corrected for instrumental 'dead time' effects
EXPOSURE equals LIVETIME corrected for any other effects (vignetting)
TIMEDEL gives the inherent time resolution in the data in seconds,
i.e., the smallest possible difference between successive
time measurements.
E. The following 2 keywords are new proposed standard WCS keywords
that can be used to describe the errors in the coordinates defined
by the other WCS keywords:
CRDERj random (or statistical) error in the coordinate (was TIERRELA).
CSYERj systematic error in the coordinate (was TIERABSO)
F. Other keywords (these may need more discussion)
TIMEPIXR (see 94apr20 OFWG minutes and 14 July 94 FITSBITS traffic).
value ranges from 0.0 (beginning of bin) to 1.0 (end of bin)
mCRVRn See 94Nov16 minutes of the OFWG: used in cases where a
vector column contains a light curve, and the start time of each
light curve is stored in another column ('TIME' typically).
5. Examples
A. A FITS primary array containing a 1-dimensional time series of
measurements, at equally spaced time intervals.
SIMPLE = T
BITPIX = 16 / Number of bits per data pixel
NAXIS = 1 / Number of data axes
NAXIS1 = 40 / Number of pixels in the time series
MJDREF = 48988.0 / MJD corresponding to clock start (1993.0)
TIMESYS = 'TT' / time scale specifier
CTYPE1 = 'TIME-HEL' / times are corrected to heliocentric system
CUNIT1 = 's' / times are always give in units of seconds
CRPIX1 = 0.5 / reference pixel: beginning of 1st pixel
CRVAL1 = 14026443.62 / local time at the reference pixel
CDELT1 = 16. / time increment between pixels
CRDER1 = 1.0E-9 / [s] Random error: Short-term clock
stability
CSYER1 = 1.0E-3 / [s] Absolute precision of clock correction
TSTART = 14026443.62 / [s] local time start
TSTOP = 14027083.62 / [s] local time stop
EXPOSURE= 640. / [s] exposure time
TIMEDEL = 16.0 / [s] Smallest time increment == CDELT
DATE-OBS= '12/06/93' / Date observations were made (dd/mm/yy)
TIME-OBS= '05:44:43' / Time observations were made (hh:mm:ss)
DATE-END= '13/06/93' / Date observations ended (dd/mm/yy)
TIME-END= '06:08:25' / Time observations ended (hh:mm:ss)
MJD-OBS = 4.91503430975635E+04 / MJD of data start time
END
B. A 'rate' table containing a binned light curve at equally spaced
intervals. This is similar to the previous example, except that each
measurement of the time series is given in a separate row of the
table. The WCS keywords are used in this case to assign times to each
row. (As far as I know the WCS keywords have never been used in this
way before). In general there could be other columns in the table
which give other attributes of each measurement (the error on the
measured value, or the flux measured at a differnet wavelength, for
example).
[Note added 1/2002: this use of the WCS keywords to
assign a time to each row of the table will probably be considered
illegal, and is probably not good practice even if it is legal.
This usage relies on the order of the rows being preserved. If
the rows are resorted, then the time coordinate is lost.]
XTENSION= 'BINTABLE' / binary table extension
BITPIX = 8 / 8-bit bytes
NAXIS = 2 / 2-dimensional binary table
NAXIS1 = 4 / width of table in bytes
NAXIS2 = 40 / number of rows in table
PCOUNT = 0 / size of special data area
GCOUNT = 1 / one data group (required keyword)
TFIELDS = 1 / number of fields in each row
TTYPE1 = 'RATE ' / column contains measured flux of object
TFORM1 = '1E ' / data format of field: 4-byte REAL
TUNIT1 = 'count/s ' / physical unit of field
EXTNAME = 'light-curve' / Name
MJDREF = 48988.0 / MJD corresponding to clock start (1993.0)
TIMESYS = 'TT' / time scale specifier
CTYPE2 = 'TIME-HEL' / times are corrected to heliocentric system
CUNIT2 = 's' / times are always give in units of seconds
CRPIX2 = 0.5 / reference point: beginning of 1st row
CRVAL2 = 14026443.62 / local time at the reference point
CDELT2 = 16. / time increment between rows in table
CRDER2 = 1.0E-9 / [s] Random error: Short-term clock
stability
CSYER2 = 1.0E-3 / [s] Absolute precision of clock correction
TSTART = 14026443.62 / [s] local time start
TSTOP = 14027083.62 / [s] local time stop
EXPOSURE= 640. / [s] exposure time
TIMEDEL = 16.0 / [s] Smallest time increment == CDELT
DATE-OBS= '12/06/93' / Date observations were made (dd/mm/yy)
TIME-OBS= '05:44:43' / Time observations were made (hh:mm:ss)
DATE-END= '13/06/93' / Date observations ended (dd/mm/yy)
TIME-END= '06:08:25' / Time observations ended (hh:mm:ss)
MJD-OBS = 4.91503430975635E+04 / MJD of data start time
END
C. An EVENTS list extension with a time column.
In this example the local time of each event is given directly in the
TIME column. The events are not necessary spaced at equal time
intervals. Other optional columns may exist in the table which give
other attributes of each event. Since it is not necessary to apply any
further TIME coordinate transformations when the times are expressed in
this form, the TCRPXj, TCRVLj, and TCDLTj WCS keywords will always have
the required values of 0.0, 0.0, and 1.0, respectively.
XTENSION= 'BINTABLE' / binary table extension
BITPIX = 8 / 8-bit bytes
NAXIS = 2 / 2-dimensional binary table
NAXIS1 = <n> / width of table in bytes
NAXIS2 = <n> / number of rows in table
PCOUNT = 0 / size of special data area
GCOUNT = 1 / one data group (required keyword)
TFIELDS = <n> / number of fields in each row
TYPE1 = 'TIME ' / label for field 1
TFORM1 = '1D ' / data format of field: 8-byte DOUBLE
TUNIT1 = 's ' / physical unit of TIME column
EXTNAME = 'EVENTS ' / Name of this table extension
MJDREF = 48988.0 / MJD corresponding to clock start (1993.0)
TIMESYS = 'TT' / time system
TCTYP1 = 'TIME-SAT' / Times measured at position of moving
satellite
TCUNI1 = 's ' / times are always give in units of seconds
TCRPX1 = 0.0 / zero point of the time axis (required
value)
TCRVL1 = 0.0 / local time at reference point (required
value)
TCDLT1 = 1.0 / unit scaling (required value)
TCRDE1 = 1.0E-09 / [s] Random error: Short-term clock
stability
TCSYE1 = 1.0E-03 / [s] Absolute precision of clock correction
TSTART = 14026443.62 / [s] local start time of the exposure
TSTOP = 14027083.62 / [s] local time stop
TELAPSE = 640. / [s] total elapsed time of the observation
ONTIME = 640. / [s] On-source time
LIVETIME= 640. / [s] live time
EXPOSURE= 640. / [s] exposure time
TIMEDEL = 0.08 / [s] Smallest time resolution
END
More information about the fitswcs
mailing list