HST Data Handbook for COS

5.4 Working with TIME-TAG Data

---

COS detectors can be used in ACCUM or TIME-TAG modes, as described in Chapter 5 of the COS Instrument Handbook. In TIME-TAG mode, the position and detection time of every photon is recorded in an events list. Detection times are recorded with 32 millisecond precision, although events may be buffered for as long as 32 milliseconds prior to assignment of a detection time.

For TIME-TAG datasets, the HST archive returns a raw events list in a file with a _rawtag suffix. The _rawtag file is a FITS file with two binary table extensions. The first extension contains the events list and the last extension a list of good time intervals, indicating time intervals when events are valid.

An events list in a _rawtag file is a FITS binary table extension named EVENTS, containing four columns named TIME, RAWX, RAWY, and PHA. Note only FUV data will include the PHA columns in the _rawtag files.

The TIME in the events extension contains the time when each event was recorded, relative to the start time (MJD) of the exposure given in the EXPSTART keyword of the primary FITS header.

In TIME-TAG the RAWX column contains the pixel coordinate along the spectral axis where each event was recorded. Corrections to remove Doppler shifts introduced by the orbital motion of HST are applied by calcos and placed in the corrtag file. The correction 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 on orbit during an observation and is included in the RAWX column, but in TIME-TAG mode the uncorrected positions are downlinked and Doppler compensation is applied during ground processing. The RAWY column contains the pixel coordinate along the spatial, or cross-dispersion, axis. No Doppler compensation is applied. The PHA column (for FUV data only) contains the pulse height amplitude for each event as an integer on a 5-bit scale.

After all EVENTS extensions in a _rawtag file, there will be one final binary table extension named GTI, containing 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, however - for example, if guide star lock is lost. Times in START and STOP are expressed in seconds since the start time (MJD) of the exposure given in the EXPSTaRT keyword of the primary FITS header. The exposure start time (JD) is also provided in the EXPSTaRTj keyword of the primary FITS header. The start time is also provided in the In IRAF, good time intervals can be examined using the tprint task in the tables package:

cl> tprint rootname_rawtag.fits[GTI]

where rootname must be replaced by the rootname of the _rawtag file being examined.

Useful IRAF tasks for analyzing and manipulating data taken in the TIME-TAG observing mode are listed in Table 5.3.

Table 5.3: Useful IRAF Tasks for Reducing TIME-TAG Data

Task	Purpose
tpar, tprint	Read the value for table header keywords
sgraph	Display the 1-D spectrum
tomultispec	Convert x1d spectrum into IRAF .imh spectrum
splot	Display an IRAF .imh spectrum
splice	Splice spectra together

5.4.1 Displaying TIME-TAG Data in DS9

To view a TIME-TAG file (_rawtag_(a,b) in the FUV, _rawtag in the NUV), open ds9, then choose `open' from the menu bar at the top. The image will load but, save for a few pixels registering a value of 1, the remaining pixels will be zero.

Once the image is loaded, go to the menu item `bin' and open the pull-down menu from that. From that pulldown menu you can choose the size of the image to view - generally you should make it as big as possible: 8192X8192 pixels for FUV data, 1024X1024 pixels for NUV.

NOTE: for the instructions below, the changes will not take effect until you click on the `Apply' button.

Now choose `Binning Parameters' from the `bin' pulldown menu. This will open a new window with the binning parameters listed. You will notice right away that the Bin Columns are listed as TIME and RAWX. These are what is currently being displayed by ds9 (which is why the image looks so strange when initially loaded). However, what you really want is RAWX vs. RAWY, so change that in the pulldown menu under Bin Columns.

You can also set the blocking size of the image in the `Binning Parameters' window - just type in `2' in the Block field next to RAWX. By blocking this way along the dispersion direction, you can now see virtually all of the 16384 pixels along the dispersion direction. If you are looking at NUV data, then no additional blocking is needed - just leave the blocksize as 1, but choose the image size as 1024 pixels from the `bin' pulldown menu.

Spectroscopic Data:

Next, from the `Binning Parameters' window choose the part of the spectrum to be centered on the middle of the dispersion direction by clicking on the button marked `center of data'. Now press `Apply' on the binning parameters window to update the ds9 display.

The spectrum should now be displayed, with the dispersion direction running from left to right. To better see the data, choose `scale' under the main ds9 menu bar, and from that pulldown menu choose a square root stretch and min/max range. You can now pan your cursor over the image, while holding the right button down on your cursor, until the contrast looks just right. If you would like to smooth the data a bit (this can be useful for bringing out fainter features and increasing signal to noise along the display), choose the `Analysis' menu item under the main ds9 menu bar and select `smooth parameters'. A dialogue box will open, and from there you can set the number of pixels to smooth. Finally, you can also click on the `Color' item on the ds9 menu bar and choose `invert color map' to get an inverted color map.

You can also load a _corrtag_(a,b) table in ds9, but in this case the appropriate columns to display are XCORR and YCORR. Otherwise, the same ds9 commands apply as for _rawtag files. For both TIME-TAG and ACCUM spectroscopic data the _flt and _counts spectral images will load as simple 2-D images in ds9.

Imaging Data:

For both TIME-TAG and ACCUM imaging data The _flt and _counts images will load as simple 2-D images in ds9.

TIME-TAG Animation:

You can assign events registered during each time interval to a separate image in ds9, thereby creating a sequence of images which can be played as an animation. This can be useful in verifying the occurrence of lamp flashes in TAGFLASH data, in searching for the appearance of bursts in raw data, and so on. To bin the images in time, set up the image as described above - with RAWX and RAWY chosen in the `Binning Parameters' dialogue box. At the bottom of the `Binning Parameters' box is a parameter called `Bin 3rd Column'. Set the value of this parameter to TIME. Next, choose the number of bins you would like to divide the event file into under the `Depth' parameter. Setting this value to 10, for example, will create 10 separate images, with the first one showing all events registered during the first (EXPTIME/10) seconds, the next one showing all events registered between (EXPTIME/10) and (2*EXPTIME/10) seconds, the next showing all events registered between (2*EXPTIME/10) and (3*EXPTIME/10), and so on up to EXPTIME. The `Min' and `Max' parameters let you choose the range of values in time to display - usually this is pre-set to 0 and EXPTIME, and can be left unchanged to bin the entire image as above. Select `Apply' to do the binning.

Note that some time will be required to create the sequence of images, and that binning the events in time in ds9 is very memory intensive, and that it is easy to make ds9 crash if EXPTIME is large (for example >1000 seconds) and the number of bins in `Depth' is set to a large value (for example 30). It is best to start with a small value for `Depth' that works, then increase the value if needed.

After the binning is done, a new dialogue box will appear called `Data Cube'. Numbered from left to right will be the enumeration of the bins (in the example above from 1 to 10), along with a slider underneath. Click on `Play' in that window to start the animation - it will play each of the binned images sequentially in the ds9 window. Again, the spacing between each of the bins will be (EXPTIME/10) in seconds, or (EXPTIME/Nbin), where Nbin is the number of bins.

In the animation, it should be possible to see the TAGFLASH spectrum appear and disappear as the sequence progresses. Obviously the sequence will show the flashes only if the keyword TAGFLASH=auto or TAGFLASH="uniformly Spaced" is in the header of the event file.

To exit from the animation, close the `Data Cube' window, and then set the `Depth' parameter in the `Binning Parameters' dialogue box to zero, and click `Apply'. That will reset the image in ds9 to show all of the data again.

It is possible to bin in other parameters as well, such as PHA. The logic is the same as above.

5.4.2 Manipulating TIME-TAG Data for Variability

Users may wish to process only sub intervals of TIME-TAG events, to look for variability in the data. One way to do this would be to divide an exposure up into several sub-exposures before re-processing.

If the following example is used for TAGFLASH data users are warned to be wary of splitting the lamp flashes between sub-exposures. Inappropriately sub-dividing TAGFLASH data could adversely affect the wavelength calibration in the final products.

For example, to split the exposure, l61h9002r_rawtag.fits, into two equally spaced sub-exposures use the task tcopy.

cl> tcopy "l61h9002r_rawtag.fits[1][r:time=0:60]" / l61h90021_rawtag.fits cl> tcopy "l61h9002r_rawtag.fits[2]" / l61h90021_rawtag.fits cl> hedit l61h90021_rawtag.fits[0] rootname l61h90021 cl> hedit l61h90021_rawtag.fits[1] exptime=60 cl> hedit l61h90021_rawtag.fits[0] filename / l61h90021_rawtag.fits cl> tcopy "l61h9002r_rawtag.fits[1][r:time=60:]" / l61h90022_rawtag.fits cl> tcopy "l61h9002r_rawtag.fits[2]" / l61h90022_rawtag.fits cl> hedit l61h90022_rawtag.fits[0] rootname l61h90022 cl> hedit l61h90022_rawtag.fits[1] exptime 60 cl> hedit l61h90022_rawtag.fits[0] filename l61h90022_rawtag.fits

Next, the two sub-exposures should be reprocessed through calcos. To reprocess the data, a new association file should be created to input to calcos. The original exposure, l61h9002r_rawtag.fits, is a member of association, l61h90010_asn.fits. To list the members of this association use the task tprint:

cl> tprint l61hh90010_asn.fits prdata=yes # row MEMNAME MEMTYPE MEMPRSNT 1 l61h9002r EXP-FP yes 2 l61h7006r EXP-AWAVE yes 3 L61H90010 PROD-FP yes

Then, a new association file should be created and edited by using the IRAF commands copy and tedit:

cl> tcopy l61h90010_asn.fits l61h9001A_asn.fits cl> tedit l61h9001A_asn.fits

In tedit, manually change the MEMNAME of row 1 to "L61H90021". Then, insert a new row after row 1 with MEMNAME=L61H90022, MEMTYPE=EXP-FP, and MEMPRSNT=yes. Finally, change the MEMNAME of the last row to "L61H9001A". Exit tedit by typing Control-D, then q.

The resulting association file should have the following content:

cl> tprint l61hh0101_asn.fits # row MEMNAME MEMTYPE MEMPRSNT 1 L61H90021 EXP-FP yes 2 l61H90022 EXP-FP yes 3 L61H7006R EXP-AWAVE yes 4 L61H9001A PROD-FP yes

Theses three files could then be reprocessed by calcos using the following command in IRAF:

cl> calcos l61h9001A_asn.fits

The resulting calibrated extracted spectra:

• l61h90021_x1d.fits
• l61h90022_x1d.fits

would each contain the calibrated sub-exposure information from l61h9002r_rawtag.fits and could be used to search for any variability in the data.