5.6 Working with TIME-TAG Data

STIS MAMA detectors can be used in ACCUM or TIME-TAG modes, as described in Chapter 11 of the STIS Instrument Handbook. In TIME-TAG mode, the position and detection time of every photon is recorded in an event list. Detection times are recorded with 125 microsecond precision, although events from bright sources may be buffered for as long as 128 milliseconds prior to assignment of a detection time.

For TIME-TAG datasets, the HST archive returns all normal data products and an event list in a file with a _tag suffix. The _tag file is a FITS file with two binary table extensions. The first FITS extension is the event list, a binary table named EVENTS, and contains four columns named TIME, AXIS1, AXIS2, and DETAXIS1. The second FITS extension is a binary table named GTI (good time intervals), and indicates time intervals when events could have been detected.

The TIME column in the EVENTS extension of a _tag file contains the time when each event was recorded, relative to the start time (MJD) of the exposure given in the TEXPSTRT keyword of the primary FITS header. Each relative time is stored as an integer number of 125 microsecond hardware clock ticks, but application of the column SCALE FACTOR converts relative times to seconds. Application of the column SCALE FACTOR is automatic when using astropy.table task to read _tag files.

The AXIS1 column in the EVENTS extension of a _tag file contains the pixel coordinate along the spectral axis where each event was recorded plus a correction term to remove Doppler shifts introduced by the orbital motion of HST. The correction term depends on optical element and the projected orbital velocity of HST, which varies over the course of an observation. In ACCUM mode, this Doppler compensation is applied during an observation, but in TIME-TAG mode raw positions are downlinked and Doppler compensation is applied during ground processing.

The AXIS2 column in the EVENTS extension of a _tag file contains the pixel coordinate along the spatial or cross-dispersion axis. No Doppler compensation is applied.

The DETAXIS1 column in the EVENTS extension of a _tag file contains the pixel coordinate along the spectral axis where each event was recorded with no correction for Doppler shifts introduced by the orbital motion of HST. In general, users are more likely to use AXIS1 coordinates than DETAXIS1 coordinates.

The GTI extension of a _tag file contains columns named START and STOP. There will be associated start and stop times for every uninterrupted observing interval during a planned exposure. For most datasets, there will be only one START and one STOP time encompassing all buffer dumps in an exposure. Multiple good time intervals are possible in some cases like if guide star lock is lost. Times in START and STOP are expressed in seconds beginning from the start time (MJD) of the exposure given in the TEXPSTRT keyword of the primary FITS header. Good time intervals can be examined as follows, where rootname must be replaced by the root name of the _tag file being examined:

>>> from astropy.table import Table
>>> ex_table = Table.read('rootname_tag.fits',hdu='GTI')
>>> print(ex_table)

5.6.1 Heliocentric and Barycentric Time Correction

TIME-TAG observations with STIS have a temporal resolution of 125 microseconds. The effects on observed times of both the orbital motion of Earth and HST may need to be corrected relative to the solar system barycenter. The IRAF odelaytime task creates a file of observation time events corrected for light delay from three sources: 1) general relativistic effects (up to 2 milliseconds), 2) displacement of the telescope from the center of the Earth (up to 20 milliseconds), and 3) displacement of Earth from the solar system barycenter (up to 500 sec). The inputs to odelaytime are the TIME-TAG data and the ephemeris files. For details regarding the odelaytime task and parameters, the reader is referred to STIS ISR 2000-02.

To find and retrieve the orbital ephemeris file(s) required for the odelaytime task, visit http://www.stsci.edu/~STIS/monitors/ephemeris_files.html and follow the instructions.

We note that with IRAF deprecation, odelaytime functionality has not yet been implemented in stistools.

5.6.2 Converting TIME-TAG Data to an Image

The stistools task inttag was developed to convert the TIME-TAG table (EVENTS tables) into one or more sub-exposures using a user specified time increment. The result is similar to the ACCUM mode data. The default start time here is the first value in the GTI table. The time increment value can be adjusted so that each sub-exposure has reasonable signal-to-noise. Details regarding the inttag task and its parameters can be found at https://stistools.readthedocs.io/en/latest/inttag.html. A fix to a bug when calculating uncertainties for the inttag sub-exposures is currently in development.

5.6.3 Echelle TIME-TAG Data

STIS echelle TIME-TAG data that are converted to images and calibrated will require longer processing and calibration time because they consist of many orders, especially if multiple sub-exposures are created with inttag. After converting the TIME-TAG data into an image and calibrating it, one can be used to extract wavelength dependent data for a single order from the _x1d file as shown in the example below:

>>> from astropy.table import Table
>>> from astropy.io import fits

>>> hdu = fits.open('o57904050_x1d.fits')
>>> sci_data = hdu['SCI'].data

>>> order_mask = sci_data['SPORDER'] == 116
>>> columns = ['WAVELENGTH','FLUX']
>>> order_column_data = [sci_data[column][order_mask][0] for column in columns]
>>> order_table = Table(order_column_data, names=columns)
>>> order_table.pprint()

>>> hdu.close()

5.6.4 Further TIME-TAG Data Analyses

Users who wish to further analyze TIME-TAG data are encouraged to consult the STIS ISR 2000-02. This ISR provides instructions on how to carry out various tasks such as converting TIME-TAG FITS data into a different format (QPOE) for timing analysis, merging separate event tables into a single table, and performing Doppler and spatial resolution corrections. We note, however, that many of the IRAF tools discussed in STIS ISR 2000-02 are now deprecated and not supported by STScI.