Data files

This chapter lists the file naming convention and give a brief description of the files that are included within an observation for the BAT, UVOT and XRT, as well as the files common to all instruments. The TDRSS messages and the different trend data type are also listed.

Filename convention

The Swift FITS science files are named according to the following convention:

 sw[obs_id]I[submodes]_[lev].ext

where

• sw is short for Swift;
• obs_id is an 11 digit sequence number that identifies the observation ;
• I is a single character identifying the instrument (x=XRT, u=UVOT, b=BAT, t=TAM) or subsystem (s=spacecraft, f=FoM, p=processing) ;
• [submodes] is a collection of two character string identifying either the data operating mode and other sub-parameters relevant to that mode, or the observing mode for how the data were collected;
• lev is a string indicating the stage of the processing. (this is omitted if the data telemetered had no further processing applied);
• ext identifies the type of data in the file, e.g. img for image file.

In addition, an index may be added to the filename to distinguish between files that would otherwise be identical named. This, for example, is used when splitting files that are too large in size, or when during calibration and verification the same TDRSS message type was sent multiple times.
While the XRT and UVOT follow always the above syntax, for the BAT there are exceptions, mainly for the data taken in survey mode.

Data content within an observation

This section lists the science data files included within the sequences that are archived. Currently within a sequence all Level 1 data files are available and some of the Level 2 files are present. The latter as well as Level 3 file can be derived using the Swift software starting from the Level 1 data. The file listing is given below, broken down by directory, together with the specific filenames.

/auxil

Unless otherwise indicated all file are in FITS format.

• File containing the attitude information.
  sw[obs-id]sat.fits

• File containing the orbit information.
  sw[obs-id]sao.fits

• File containing spacecraft engineering parameters.
  sw[obs-id]sen.fits

• Make filter file where the attitude and the instrument housekeeping (HK) paramaters are collected for use during screening.
  sw[obs-id]s.mkf

• File containing the UTCF timing correction for the observation.
  sw[obs-id]sti.mkf

• Catalog file listing all the files within the observation.
  sw[obs-id]pob.cat

• File containing the processing parameter file (ASCII).
  sw[obs-id]ppr.par

• File containing the 'job' parameter file (ASCII).
  sw[obs-id]pjb.par

• Two line element file used in the orbit derivation (ASCII).
  SWIFT_TLE_ARCHIVE.txt.

In 2007 two additional files describing attitudes are added in the auxil directory. These are :

• Processed attitude
  sw[obs-id]pat.fits

• UVOT attitude
  sw[obs-id]uat.fits

The first processed the sat attitude file to correct for attitude jumps, the second is derived using the UVOT data. They are not always present.

/log

The files in this directory are all in HTML format.

• File containing a summary of the availble information.
  sw[obs-id]psu.html

• File containing the list of files created during processing.
  sw[obs-id]pfi.html

• File containing the instrument (BAT) exposure report.
  sw[obs-id]bir.html

• File containing the instrument (UVOT) exposure report.
  sw[obs-id]uir.html

• File containing the instrument (XRT) exposure report.
  sw[obs-id]xir.html

• File containing the log of the processing.
  sw[obs-id]pjl.html

• File containing an index of the major steps during the processing.
  sw[obs-id]pin.html

• File containing the errors that occur during the processing.
  sw[obs-id]per.html

/bat

The BAT data are divided into five subdirectories, each containing the following files:

/event

• An event file containing the data obtained in Event mode. This mode is used when a burst is detected. The file contains data taken just before the burst occurs, the interval when the satellite slews to the new position and after the slew. The time interval typically includes data for 10 minutes (Level 1).
  The file is named sw[obs_id]bXXYYZZ_uf.evt, where XX is the mode set to 'ev' for event, YY is set to 'sh' to stand for short events, ZZ is set to 'sp' to indicate that the file contains data from both Slew and Pointing and 'uf' indicates that the data are unfiltered.
  

  Starting in 2007 the BAT uses the event mode more regularly also during the slews. The ending of the event mode not always end at the end of the slew boundary and some event data during the pointing are taken in event mode. The slew and pointing event mode data taken during normal observation, e.g. not trigger by a burst, are kept in separate files one for the slew and one for the pointing The filename is as above sw[obs_id]bXXYYZZ_uf.evt where the suffix ZZ is set to 'sl' for slew and 'po' for poiting. .

• A file containing additional information derived from a ray-trancing program necessary to be generate respense file. This is present when the event data are generated because a burs has been detected. The file is named sw[obs_id]bXXYY.fits, where XX is the mode set to 'ev' for event, and YY is set to 'rt' for ray-tracing.

/rate

• A lightcurve file containing the 1 second data from the entire array in 4 energy bands.
  sw[obs_id]bXXYY.lc , where XX is the data mode set to 'rt' for rate and YY is '1s'.

• A lightcurve file containing the 64ms data from the entire array in 4 energy bands.
  sw[obs_id]bXXYY.lc , where XX is the data mode set to 'rt' for rate and YY is 'ms'.

• A lightcurve containing the 1.6 second data per quadrant (4 in total) in 4 energy bands.
  sw[obs_id]bXXYY.lc , where XX is the data mode set to 'rt' for rate and YY is 'qd'.

• A lightcurve histogram which records the maximum count rate per quadrant in 4 energy bands for various integration times (4ms, 8ms, 16ms, 32ms, 64ms). All data are stored in one file with 5 extensions, one for each of the integration times.
  sw[obs_id]bXXYY.lc , where XX is the data mode set to 'rt' for rate and YY is 'mc'

/masktag

• N lightcurves from the mask-tagged rate data mode obtained for sources that were simultaneously monitored (typically 3) within the large BAT FOV. The integration time is 1.6 sec (Level 1).
  sw[obs_id]bXX[target_id]_rw.lc , where XX is the data mode set to 'mt' for mask tagged and [target_id] is an 8 digit number identifing the target ID associated with the object that has been monitored (Level 1).

• N lightcurves from the mask-tagged rate data mode processed (Level 2). There should be one Level 2 lightcurve for any Level 1 file.
  sw[obs_id]bXX[target_id].lc , where XX is the data mode set to 'mt' for mask tagged and [target_id] is an 8 digit number identifing the target ID associated with the object that has been monitored.

NOTE: In some sequence there are a number of Level 1 superior of the Level 2. These excess of Level 1 lightcurves are to be considered not valid their content is already included in different files and they will be removed in subsequent data re-processing. .

/survey

• M survey files, one for each combination of gain and offset calculated on-board during an observation. This type of file is also known as a Detector Plane Histogram (DPH, Level 1).
  sw[obs_id]bXXYYoxxxxgzzz.dph, where XX is the data mode set to 'sv' for survey mode, YY indicates if the survey data are from after a burst ('ab') or pre-burst ('pb'), oxxxx and gzzzz are the offset and gain respectively.

/pulsar

• One file per observation for a given source containing 80-channel spectra folded on-board in 32 bins.
  sw[obs_id]bXX[target_id].fits , where XX is the data mode set to 'pl' for pulsar mode and [target_id] is an 8 digit number identifing the target ID associated with the object for which the folded spectra were calculated.

NOTE: Pulsar mode is not always running. From July 2006 in fact it seems beeing turned off.

/hk

• Housekeeping data containing the header information written in the Large Data Products telemetry format.
  sw[obs_id]bXX.hk , where XX is set to 'hd' to indicate the telemetry header.

• Housekeeping data containing the engineering parameters.
  sw[obs_id]bXX.hk , where XX is set to 'en' to indicate engineering.

• Housekeeping data containing information of the detector array panel.
  sw[obs_id]bXX.hk , where XX is set to 'dp' to indicate the detector panel.

• Housekeeping data containing the timestamps of the event packets.
  sw[obs_id]bXXYYZZ.hk , where XX is set to 'ev' to indicate the mode, YY is set to 'ts' to indicate time stamps, and ZZ is set to 'sp' to indicate that the file contains data from both Slew and Pointing.

• Housekeeping data containing additional telemetry information present in the event data.
  sw[obs_id]bXXYYZZ.hk , where XX is set to 'ev' to indicate the mode, YY is set to 'tl' to indicate general telemetry, and ZZ is set to 'sp' to indicate that the file contains data from both Slew and Pointing.

• Calibration file containing the gain and offset for the observation.
  sw[obs_id]bXXYY.hk, where XX is set to 'go' for gain and offset and YY is set to 'cb' for calibration.

• Calibration file containing the detector enabled during an observation.
  sw[obs_id]bXXYY.hk, where XX is set to 'de' for detector enable and YY to 'cb' for calibration.

• Calibration file containing the detector quality flags
  sw[obs_id]bXXYY.hk, where XX is set to 'dq' for detector quality flag and YY to 'cb' for calibration.

/uvot

The UVOT instrument is equipped with several filters. Data files include in their names a two character string used as a mnemonic for the filter. These are :

Filter             Filter 
----------------------------------
V          vv    |  White      wh
U          uu    |  VGRISM     gv
B          bb    |  UGRISM     gu
UVW1       w1    |  MAGNIFIER  mg
UVW2       w2    |  Blocked    bl
UVM2       m2    |

The UVOT data are divided into three subdirectories each containing the following files:

/event

The filename of the UVOT event files changed in June 2006. The description below includes both naming. With the next data re-processing the new naming convention wil be apply to al data.

• N event files, each containing data taken in Event mode for a specific filter and observing mode (Level 1).
  sw[obs_id]uXXYY_uf.evt , where XX is set to the filter mnemonic as listed in the table of the /uvot section, and YY indicates the observing mode. The UVOT collects data during the settling and pointing phases, for which YY is set to 'sd' and 'po', respectively. As for the BAT event file, 'uf' indicates that the data are unfiltered.
  

  After June 2006 the filename has been changed as :
  sw[obs_id]uXXYYZZ_uf.evt , where XX is set to the filter mnemonic as listed in the table of the /uvot section, YY is the hardware window used (see table below) and ZZ indicates the observing mode. The UVOT collects data during the settling and pointing phases, for which YY is set to 'sd' and 'po', respectively. As for the BAT event file, 'uf' indicates that the data are unfiltered.
  

• N event files, each containing the calibrated and screened data taken in Event mode for a specific filter and observing mode (Level 2) (as for feb 2007 these have not been generated):
  sw[obs_id]uXXYY_cl.evt , where XX is set to the filter mnemonic as listed in the table of the /uvot section, and YY indicates the observing mode. The UVOT collects data during the settling and pointing phases, for which YY is set to 'sd' and 'po', respectively. 'cl' indicates that the data have been cleaned.

  After June 2006 the filename has been changed as :
  sw[obs_id]uXXYYZZ_cl.evt , where XX is set to the filter mnemonic as listed in the table of the /uvot section, YY is the hardware window used (see table below) and ZZ indicates the observing mode. The UVOT collects data during the settling and pointing phases, for which YY is set to 'sd' and 'po', respectively. 'cl' indicates that the data have been cleaned.
  

The uvot hardware window sizes are:

Size               YY value
----------------------------------
0,0,128,128      |  w1
30,35,60,60      |  w2
41,46,38,38      |  w3
Unknown          |  wu

/image

• M files containing data taken in Image mode. There is one file per filter and each file can contain one or more extensions, one for each exposure. The coordinates in the file correspond to the raw detector coordinates (Level 1).
  sw[obs_id]uXX_rw.img , where XX is set to the filter mnemonic in the table of the /uvot section

• N files containing data taken in Image mode and Event mode transformed to sky cordinates. There is one file per filter and each file can contain one or more extensions, one for each exposure. (Level 2).
  sw[obs_id]uXX_sk.img , where XX is set to the filter mnemonic in the table of the /uvot section

• N files containing the exposure maps for the images included in the extension of the '_sk' files. There is one file for filter, and each file can contain one or more extensions one for each exposure.
  sw[obs_id]uXX_ex.img , where XX is set to the filter mnemonic in the table of the /uvot section

NOTE : The number of raw image file corresponds to the number of filters M used in Image mode only. If the same filter is used in Image and Event mode, the raw image file contains only the exposure taken in Image mode however the sky image contains both data taken in image and in event mode. The number N of sky and exposure files include data taken with filter in image or event mode (N > M).

/hk

• Housekeeping data containing the information written in the Event mode telemetry headers.
  sw[obs_id]uXX.hk , where XX is set to 'hd' to indicate the telemetry header.

• Housekeeping data containing the engineering parameters.
  sw[obs_id]uXX.hk , where XX is set to 'en' to indicate engineering.

• Housekeeping data containing information at the start of each exposure.
  sw[obs_id]uXX.hk , where XX is set to 'es' to indicate exposure start.

• Housekeeping data containing a report on the exposure.
  sw[obs_id]uXX.hk , where XX is set to 'er' to indicate exposure report.

• Housekeeping data containing a catalog of all exposure within the observation.
  sw[obs_id]uXX.hk , where XX is set to 'ct' for catalog.

• Aspect correction done on ground within the observation. Not always present
  sw[obs_id]uXX.hk , where XX is set to 'ac' for catalog.

• Aspect correction done on board (aspect following). Not always present
  sw[obs_id]uXX.hk , where XX is set to 'af' for catalog.

/xrt

Data from the XRT instrument are collected on-board via different read-out modes. Data files include in their names a two character string as the mnemonic for the modes. These are :

Modes
----------------------------------
Image                   im
Piled-up Photodiode     pu
Low-rate Photodiode     lr
Windowed Timing         wt 
Photon Counting         pc 
----------------------------------

The XRT data are divided into three subdirectories, each containing the following files:

/event

• N event files, each containing data taken with a specific read-out mode and observing mode combination (Level 1).
  sw[obs_id]uXXYYZZ_uf.evt , where XX is set to the read-out modes mnemonic as listed in the table of the /xrt section, YY indicates a submode of the read-out mode and ZZ the observing mode. In Photodiode (Low-rate and Piled-up), YY indicates whether or not the bias has been subtracted on-board, being set to 'b1' if the bias has been subtracted on-board, otherwise being set to 'b0'. In Photon Counting and Windowed Timing modes, YY instead gives the mnemonic for the fraction of the FOV exposed, according to the following table:

   ww  Windowed Timing   Photon counting 
  ---------------------------------------
   w1   100 columns      490x490 pixel   
   w2   200 columns      500x500 pixel  
   w3   300 columns      600x600 pixel  
   w4   400 columns      480X480 pixel
  

  The XRT collects data during the slew, settling and pointing phases, for which ZZ is set to 'sl', 'sd', and 'po', respectively. As for the BAT and UVOT, 'uf' indicates that the data are unfiltered.

• K event files, each containing the reconstructed events for Windowed Timing and Photodiode modes (Level 1a)
  sw[obs_id]uXXYYZZ_ufre.evt, where the submode specifications XX, YY and ZZ are identical to those for the unfiltered files, but with the level specification set to 'ufre' for unfiltered reconstructed. Processing is required to obtain the Level 2 (cleaned events)

• N event files, each containing data taken with a specific read-out mode and observing mode combination (Level 2).
  sw[obs_id]uXXYYZZ_cl.evt , where XX, YY and ZZ has the same meaning as above, and 'cl' indicates that the data have been cleaned.

/image

• File containing data taken in Image mode containing one or more extensions one for each exposure (Level 1).
  sw[obs_id]xXX_rw.img , where XX is set to 'im' to indicate image mode. In order to obtain a Level 2 data file user processing is required.

/hk

• Housekeeping data containing the information written in the telemetry header of the event packets.
  sw[obs_id]xXX.hk , where XX is set to 'hd' to indicate the telemetry header of the event packets.

• Housekeeping data containing the information written in the telemetry trailes of the Large Data Products format event mode files.
  sw[obs_id]xXX.hk , where XX is set to 'tr' to indicate trailers.

• Housekeeping data containing the engineering parameters.
  sw[obs_id]xXX.hk , where XX is set to 'en' to indicate engineering.

• Bias map for the Photon Counting data.
  sw[obs_id]xXX_rw.img , where XX is set to 'bf' to indicate bias frame.

TDRSS data

The TDRSS data consist of a number of files, corresponding to messages that are sent to the ground as soon as an on-board trigger occurs. Each instrument generates specific messages, the number of which depends on whether or not a position has been obtained. The filenaming convention for the TDRSS messages is the following

 sw[obs_id]msI[submodes].ext

where

• sw is short for Swift;
• obs_id is an 11-digit sequence number that identifies the observation ;
• I is a single character identifying the instrument (x=XRT, u=UVOT, b=BAT) or subsystem (s=spacecraft, f=FoM, p=processing) ;
• [submodes] is a collection of two character string identifying the data.
• ext identifies the type of data in the file, e.g. img for an image file.

The TDRSS files and their names are :

• File containing the BAT alert message.
  sw[obs_id]msbXX.fits , where XX is set to 'al' to indicate alert.

• File containing the BAT position.
  sw[obs_id]msbXX.fits , where XX is set to 'ce' to indicate centroid.

• File containing the message that a Position was not found on-board by the BAT.
  sw[obs_id]msbXX.fits , where XX is set to 'no' to indicate that no position was found.

• File containing the BAT lightcurve.
  sw[obs_id]msb.lc

• File containing the BAT attitude.
  sw[obs_id]msbat.hk

• File containing the BAT timestamp.
  sw[obs_id]msbevtssp.hk

• File containing the BAT telemetered events.
  sw[obs_id]msbevtlsp.hk

• File containing the BAT events.
  sw[obs_id]msbevshsp_uf.evt

• File containing the XRT centroid message.
  sw[obs_id]msxXX.fits , where XX is set to 'ce' to indicate centroid.

• File containing the message that a position was not found on-board by the XRT.
  sw[obs_id]msxXX.fits , where XX is set to 'no' to indicate that no position was found.

• File containing the raw XRT postage stamp image centered on the GRB sent on ground only if a position was successfully calculated.
  sw[obs_id]msxXX_rw.img , where XX is set to 'ps' to indicate postage stamp.

• File containing the sky XRT postage stamp image centered on the GRB sent on ground only if a position was successfully calculated.
  sw[obs_id]msxXX_sk.img , where XX is set to 'ps' to indicate postage stamp.

• File containing the XRT lightcurve.
  sw[obs_id]msx.lc

• File containing the raw XRT images full size from which the postage stamp is derived
  sw[obs_id]msxXX_rw.img , where XX is set to 'im' to indicate the XRT data mode

• File containing the sky XRT images full size from which the postage stamp is derived
  sw[obs_id]msxXX_sk.img , where XX is set to 'im' to indicate postage stamp.

• File containing the XRT spectrum, up to two spectra can be calculated on board.
  sw[obs_id]msxXX_rw.pha, where XX is set to 'lr' or 'wt' to indicate the XRT data mode. The spectra may need some ground processing.

• File containing the unfiltered event data recorded in PC mode taken soon after the burst. These data are a subset of the full dataset and it is used to derive the position if unsuccefull with the images
  sw[obs_id]msxXX_uf.evt , where XX is set to 'pc' to indicate the XRT data mode.

• File containing the cleaned event data recorded in PC mode taken soon after the burst. These data are a subset of the full dataset and it is used to derive the position if unsuccefull with the images
  sw[obs_id]msxXX_cl.evt , where XX is set to 'pc' to indicate the XRT data mode.

• File containing the UVOT finding chart.
  sw[obs_id]msuXX.img, where XX is set to 'fc' for finding chart.

• File containing the 'dark burst' UVOT image centered on the XRT position.
  sw[obs_id]msuXX_rw.img, where 'ni' is the identifier and 'rw' indicate that is raw coordinates.

• File containing the listing of the files included in the directory.
  sw[obs_id]mspob.cat

Trend data

For each of the instruments, the trend and monitoring data files are organized by type. The main purpose of these data is to monitor various aspects of the instrument during the mission. These data are listed in the following tables by instrument, together with their filenames and the directory names where they are located. These data arrive on a daily basis in the archive. In most cases, a file contains data for an entire observation, therefore these files are updated on a daily basis until all the data for the observation has arrived.

BAT

Table 4.1: List of BAT trend data

Trend Type description	Filename	Directory
Americium detector plane histogram	sw[obs_id]bamcbgXXXXoYYYY.dph	bamdph
Americium gain	sw[obs_id]bamcbgXXXXoYYYY.fits	bamgain
Scaled map diagnostic	sw[obs_id]bsmcb.fits	bscalemap
for burst alert
Detector Gain	sw[obs_id]bcbgXXXX.fits	bgain
Detector Offset	sw[obs_id]bcboYYYY.fits	boffset
Detector gain/Offset	sw[obs_id]bcbgXXXXoYYYY.fits	bgainoffs
Detector plane enable	swt[MET time]bdecb.fits	bdetflag
BAT commandables	sw[obs_id]bcdtb.fits	btbcommand
commanded table
BAT on board catalog	sw[obs_id]bcttb.fits	bcatalog
On board veto	sw[obs_id]bvttb.fits	btbveto
On board long trigger	sw[obs_id]blttb.fits	btblongtr
On board short trigger	sw[obs_id]bsttb.fits	btbshorttr
On board rate trigger	sw[obs_id]brttbrp.fits	btbratetr
On board image trigger	sw[obs_id]bittb.fits	btbimgtr
Trigger flux	sw[obs_id]bfxcb.fits	btrigflx
Shell Log	sw[obs_id]bshtb.fits	bshelllg

UVOT

Table 4.2: List of UVOT trend data

Trend Type description	Filename	Directory
Parameters for the compression	sw[obs_id]ucm.fits	ucompression
routine
Centroid	sw[obs_id]ucn.fits	ucentroid
Engennering monitor	sw[obs_id]umo.fits	umon

XRT

Table 4.3: List of XRT trend data

Trend Type description	Filename	Directory
Diagnostic mode data: Raw frame	sw[obs_id]xrf_rw.img	xrawmode
Bias for the Photon Counting	sw[obs_id]xbs_rw.img	xbiasmode
Tam images	sw[obs_id]xtm_rw.img	xtam
Calibration sources	sw[obs_id]xpc[ww]cb_uf.evt	xcal
ww is the window size

Others

In addition to the instrumental trend data, there are four other types of files with general trend data. These are :

• Clock offset table (ASCII). These files contain the measurements on-board of the clock offset compared with UTC. These files are not part of the data processing, but they are generated at the Mission Operation Center. The table is updated on a daily basis and the latest file always contains all the previous measurements. These files are located in the /clocklog directory.

• As Flown Timeline (ASCII). These files contain the timeline of what has observed. They are not part of the data processing but are generated at the Mission Operation Center. Each file contains a one day timeline and arrives at the archive one week later. These files are located in the /asflown directory.

• TDRSS diagnostic (FITS). In addition to the science TDRSS messages, there are messages that are used for diagnostics. All diagnostic messages within an observation are included in one file. As for the instrument trend files, they are updated daily until the observation is complete. These files are located in the /tdrssdiagnostic directory.

• Make filter file (FITS). This file is included within each observation directory but it is also included in the trend area so as to facilitate the instrument team's global studies of some parameters included in the mkf file. Each file corresponds to an observation. As for the other instrumental trend data, these files will change daily until an observation is completed. These files are located in the /mkfilter directory.