Swift Getting Started Guide

Welcome Swift Science Users!

This brief Swift Getting Started Guide is intended to get scientists comfortable with data analysis. It points out the current status and limitations of Swift data and analysis, and alerts the new user to several useful sources of information. We will continue to make new documentation available, and improve the existing documentation in the near future.

Prerequisites

The Swift Web site (http://swift.gsfc.nasa.gov) contains a great deal of information for the science user. This includes background information on the mission and instruments, data analysis guidance, publications, and information about the Guest Investigator program. Please take a few moments to familiarize yourself with the Swift Web site by visiting the Guide to our Web Pages.

Also note that wherever you are on our Web site, you can always click on the "Swift Help/FAQ" link found in the top menu bar on every page. This link takes you to our Help Page where we have organized our help information into one easy-to-access list.

If you are brand new to Swift data analysis, you'll want to spend some time making sure that you are set up to run the Swift software tools with the best available calibration. Please get and install the following:

The Swift Software
The Swift CALDB
Swift Software Documentation

Go to the Swift Data Analysis Page and follow the links to software, calibration, and documentation, to retrieve the above. Please be sure to follow the instructions on the Software and CALDB Web pages.

Keeping track of Swift software status

Consult our Known Bugs List to get familiar with the limitations of the current software, and planned updates.

Asking for Help

If you need help and can't find the answer in our bug list, please consult the resources in our Swift Help/FAQ page. You'll find links to our Frequently Asked Questions (FAQ), recent Swift instrument info, and, if all else fails, a Feedback form for you to submit questions directly to the Swift Science Center staff. If you submit a question regarding a software problem, it will help us greatly if you include a screen dump of all your inputs to the tool, and the error message that resulted.

Show Me the Data!

You now have installed Swift software, and calibration data, and have gotten copies of the software guides for each of the three Swift instruments. Now it's time to begin getting familar with Swift data.

Quicklook Data

To access the Quicklook Data area, simply click on the "Quicklook Data" button at the top of this, (or any) Swift Web page. You will then be taken to the SDC Quicklook staging area. The data is organized into a table with columns for Sequence, Version, Object, Observed, Processed, and Comment. By clicking on the name of any column, you can resort the data to suit your needs.

Let's take a look at two particular lines in this table:

00103647000 | 006 | Burst | 2005-01-24T11:15:02 | 2005-01-26 | new data: moc2005-01-27T00:49:03
00103647001 | 050 | Burst | 2005-01-24T13:39:12 | 2005-01-30 | new data: moc2005-01-29T08:43:01

The sequence number is used to uniquely identify the data. The first eight digits identify the target and the last three digits distinguish different observations of the same target. In this case, the target ID is 00103647. You will find this keyword in the FITS files within this observation. The first observation, with last 3 digits of 000 is the data from the autonomous slew. The second observation, with last 3 digits of 001 is the data from the ground-commanded follow-up observations.

The version number is the second column and records the number of times data from this sequence has been processed by the pipeline. Data from the follow-up observation has been processed 50 times, while data from the autonomous slew observation has been processed only 6 times.

The object column identifies the object. Currently, the identier "Burst" is used whenever a BAT on-board trigger is detected which results in data being tagged with a new sequence number. NOTE: Since known, interesting sources can and do result in purposeful BAT triggers, you must examine the keywords in the BAT burst centriod TDRSS message (sw*bce.fits). This is described in more detail below.

The observed field is the UT date and time string associated with the first time in the file. These sequences are therefore observations of GRB 050124. The follow-up observations (001) began about 2.5 hours after the initial trigger.

The processed field records the date the sequence was last processed. The follow-up observations are longer than the initial burst observations, and new data continued to be received by the SDC, triggering new processings, for many more days than for the initial pointing associated with the autonomous slew.

The Comment field contains useful information about the sequence, and most often contains the Malindi pass time and date for the most recent data.

Using the table on the Quicklook area, you may now choose a burst of interest by clicking on the sequence number. We'll continue to examine target 103647 by first clicking on sequence 00103647000.

A brief overview of the rationale behind the Swift filenames and observation definitions may be found on the Swift Archive: Getting Started page.

Data Organization: An Overview

Once you have clicked on a sequence, you will be taken to a Web page which lists all files associated with this sequence, and a Java interface that allows you to preview the headers and data before downloading. All of the data, including housekeeping data and tdrss messages, is included on the page. There are also useful summary logs of the processing itself, and an instrument report for each instrument.

In general, the directories present for an observation are:

/auxil containing attitude and orbit information, the filter file, and overview information about the sequence;
/bat containing any BAT data for the sequence;
/log containing instrument reports and summaries;
/uvot containing any UVOT data for the sequence;
/xrt containing any XRT data for the sequence;
/tdrss containing any TDRSS data for the sequence;

The Software Users Guides for the three Swift instruments go into detail about the structure of the science files for BAT, XRT and UVOT.

Downloading Data to your Local Disk

For our sequence above, only BAT data is present. Choose some data to download to your local computer. To choose the entire contents of the /tdrss directory, check off the box to the left of /tdrss on the Quicklook page. Now click the "Download" button at the top or bottom of the page.

You will be asked to supply a local directory. Type in the location where you want the data to reside, then click "Download" again. A progress bar will show you the status of the download. Once this is complete, you can now analyze the data with the Swift tools on your computer.

TDRSS messages: Useful first steps

Is this a real burst? To find out if BAT identified the trigger source in its onboard catalog, consult the swNNNNNNNN000msbce.fits file. Here, NNNNNNNN is the target ID, and "ms" means the file is a TDRSS message, "b" identifies it as a BAT message, and "ce" means centriod.

Use the FTOOL "fdump" to browse the contents of the FITS file.

This message contains 4 relevant keywords to determine if the trigger is truly a GRB. Their values can be either True (T) or False (F). For our target:
```
	CATSRC  =                    F / Is this source in the BAT on-board Catalog?
	INTEREST=                    F / Is this interesting?
	GRBDETEC=                    T / Is a Gamma Ray Burst DETECted?
	POINTSRC=                    T / Is a POINT SouRCe found?
	
```
If the position of the trigger lines up with a position in the on-board source catalog, then CATSRC = T. NOTE: The on-board catalog contains a subset of known sources and is incomplete, particularly in the crowded galactic center region. Futher BAT TDRSS messages may arrive identifying the trigger to a known source after comparison with a ground catalog.

Helpful Hint: if you want to increase your confidence that a trigger is not a known source, put the BAT-determined source coordinates, BRA_OBJ and BDEC_OBJ into the Quick Archive Search. Use a search radius of 4 arcmin, and not the default search radius of 30 arcmin, and choose several high energy missions. If your search returns a known source near the BAT GRB coordinates, proceed with caution. You're probably not looking at a GRB.

If the trigger is a known source it will be ignored if it is not interesting (INTEREST=F). But it will be slewed to if INTEREST=Y.

GRBDEC=Y when BAT has concluded from the information onboard that the trigger is consistent with a GRB. Finally, POINTSRC=Y when a rate trigger results in an image being obtained by the onboard computer.
What does the light curve look like? The FITS-viewing FTOOL fv can be used to quickly examine the contents of any FITS file. We will use it here to get an overview of the BAT light curve for this burst.

At the command line, type:
my_computer>fv sw00103647000msb.lc &
This will invoke fv with the BAT TDRSS light curve. A GUI will appear. Click "PLOT" which brings up a second window.

Choose RELTIME, then click on the "X" axis button.
Choose TOT_RATE, then click on the "Y" axis button.
Choose TOT_RATE_ERR, then click on the "Y Error" button.

Now click "Go". The TDRSS BAT light curve will be displayed on your screen.

See if you can confirm this statement from GCN 2972:
"This is a high significance burst. The structure of the burst is double-peaked with a duration of ~4 seconds."

National Aeronautics and Space Administration

Goddard Space Flight Center