Browse Swift Archive Interface Swift Interface Help Browse Help

Main sections of this help document:


Introduction

This interface provides access to the database tables that facilitate searches of the Swift archive. There are (or will be soon) five tables available listed in the "Observation logs" part of the form. The first, Master log (swiftmastr), allows users to browse all the observations taken with Swift. Three tables, one for each instrument (BAT Log or swiftbalog, XRT Log or swiftxrlog, and UVOT Log or swiftuvlog), contain the different instrument settings within an observation, and the last, TDRSS Log (swifttdrss), allows users to browse the TDRSS messages which have been sent and contains information included in the TDRSS messages. The instrument tables are not yet available but will come on-line soon. The tables are 'linked' via common parameters to allow users to get a quick view of what is present in the other tables for a given observation: these links are available on the query results page.

Data from the observations are ingested into the archive one week after the observation has been taken.

This interface uses the HEASARC Browse as a search engine, and basically operates in the same way, e.g., the user sets up and makes a query using various constraints such as position, time range, etc., and the query results are given in a page which contains all the table records that satisfy the input parameters specified for the search. It differs from the standard Browse interface(s) in that it is specific to the Swift tables and has some extra features, e.g., it allows the user to set up the search parameters using a pull-down menu in which the available GRB names are listed, or to query other services, namely the GRB Coordinates Network (GCN) archives and the National Virtual Observatory (NVO) registry of astronomical archives holdings.

Data are ingested into the archive one week after the observation has been taken, however the tables will contain records even for the observations that are not a week old. Data there are not a week old are available from the Swift Quick-look site.

Using the GRB Pull-Down Menu to Set Up the Query

In this option, the user uses the "Select Burst" feature using the GRB name pull-down menu at the top of the form to select the desired GRB.

HEASARC search form

To shorten the list of GRBs that is displayed here, the user can first select a year using the left-hand "Display Bursts by Year" pull-down, or select a year and month using the left-hand pull-down and then the center "Display by Month" pull-down. Once this GRB selection has been made, the Target ID or Coordinates boxes in the "HEASARC Archive Search" part of the form will be automatically filled out. The user should not modify either of these fields once they have been thus populated. The user can however manually override the default search radius to any desired value and/or add constraints on the observation dates by entering explicit values in the "Search Radius" box and "Observation Dates" box, respectively. If desired, the user can select different logs and catalogs to be queried than the default selection Once the selections are all in place, the user should click on the `Start Search' button to send the query.

Regular Search Option

For this type of search, the user should ignore the GRB Name pull-down menu section and proceed straight to the "HEASARC Archive search" part of the form.

HEASARC search form

Target ID, Observation ID, Position and Date search
The user can enter a value in either the Target ID field, the Observation ID field, the Observation Dates field, or the desired sky position in the Object Name or Coordinates box, pick a desired search radius (or stay with the default values) and the Observation Logs to be queried, and then click on the `Start Search' button. The HEASARC recommends (i) that users not enter GRB names in the Object Name or Coordinates box, as the name resolvers used for this box are the remote SIMBAD and/or NED ones rather than the HEASARC's own GRB resolver used in the pull-down menu option, and SIMBAD and NED may not have up-to-date (or any) GRB positional information. Users should be awared that by filling more than one of the Target ID , Observation ID , Observation Dates , and Object Name or Coordinates boxes, result in a query that uses all the constraint specified.

Search by Parameter of Specific Swift Tables
The parameter search is the most flexible and powerful way to search the Swift Archive, and also allows the user to select various options for displaying the results of the query in addition to the default HTML page, e.g., FITS, Excel, pure text, etc. This search is enabled by selecting an observation log on which the user desires doing a parameter search by putting a check in its check box and then clicking on the "parameter search form" link (next to the list of observation logs and just above the "Start Search" button).

Clicking on this hyperlink,"paramater search form", near the table name will cause a new page to appear listing all the parameters of the selected table. The user can then make specific selections on any of the listed parameters in the usual way that parameter searches are done inside Browse. If the user has made any selections, e.g., on position, observation date, and search radius, on the Browse Swift Archive page before selecting this option and going to the table parameter search page, these selections will carry over (and can of course be modified at this point, if desired). After the desired constraints are placed on the parameters, the user should start the search by clicking on the `Start Search' button.

Searches of External Sites

The bottom section of the form is dedicated to querying other services: the National Virtual Observatory (NVO) and the Gamma-Ray Burst Coordinates Network (GCN). The output results from either of these services will appear in a new browser window than that in which the input parameters were entered.

GRB name search menu

(i) NVO Search: the user can search the NVO to see what might be available at all NVO-registered astronomy sites for a given sky position. To use this option, either select the desired sky position using the GRB Name pull-down menu or by directly entering the positional information into the Object Name or Coordinates box, enter the desired search radius (or leave it at the default value), and then click on the "NVO Search" button. This will then spawn an NVO query of what resources are available for the selected sky region. (ii) Query GCN: the user can search the GCN for circulars related to a given GRB. To use this option, select the desired GRB using the GRB pull-down , and then click on the "Query GCN" button. This will then search the GCN Archive of Circulars and list all Circulars which contain information on the selected GRB. Note that this is not a positional-based search but is a name search which looks for all occurrences of the specified GRB name in all the GCN Circulars; it is not a positional-based search.

Primary Search Parameters

Target ID

Each object observed by Swift has a numeric value named the 'Target ID' assigned to it, which can include up to 8 digits. The Target ID is assigned either on-board the spacecraft or on the ground, based on a convention adopted for Swift, for example, the numeric values for GRBs range from 100000-10000000 and correspond to the trigger number. The same target can be observed more than one time. Searching by Target Id will give all of the observations carried out by Swift on that particular target.

Observation ID

Each observation made by Swift is assigned a unique 'Observation ID' or ObsID, which consists of an 11-digit numeric string, e.g., 00100433000. This parameter value is the concatenation of an 8-character string containing the Target ID (with leading zeroes added if necessary) and the 3-character string containing the Observation Segment (Obs_segment) number.

Object name or Coordinates

The syntax to enter either the object name or the coordinates is as follows:
Example coordinate inputs:
  • 12 00 00, 4 12 6
  • 180., 4.21
  • 12 14.2 -4 12 6.48
  • 0., 0.
Examples of input names:
  • Cygnus X-1
  • Eta Car
  • Ar Lac
  • A2156
  • Sco X-1
Object
If an object name (i.e., any entry containing characters other than decimal digits, spaces, and the symbols '.', '-', or '+') is entered, then the name will be resolved, i.e., converted to the equivalent sky coordinates of the object, using one of the supported name resolving services (NED or SIMBAD). Object names should conform to the established IAU specifications for designating astronomical radiation sources. There is a nomenclature dictionary for celestial objects that can be searched if the user is unsure of the object name that should be used.
Note: It is recommended that users not enter the GRB name in the Object Name or Coordinates box as the name resolvers used for this box are the remote SIMBAD and/or NED ones which may not have up-to-date (or any) GRB positional information.

Coordinates
By default, the input coordinates are assumed to be the J2000 equatorial coordinates. Other coordinate systems or equinoxes can be selected from the pull down menu to the right of the entry box.
The coordinate pairs must be separated by either a comma or a plus or minus sign in order to be recognized as a position rather than a name. If a coordinate consists of a single number which contains a decimal point, then that coordinate is taken to be given in decimal degrees; otherwise, the sexagesimal format is assumed and the coordinate is parsed accordingly. Galactic coordinates are always assumed to be in degrees, whether in sexagesimal or decimal format. If equatorial coordinates are entered in sexagesimal format, right ascension values are assumed to be in hours/minutes/seconds, and declination values are assumed to be in degrees/arcminutes/arcseconds. Spaces should be used to separate hours/degrees from minutes and minutes from seconds in sexagesimal format. Seconds values are optional in sexagesimal format, so if the user only wants to specify hours/minutes and/or degrees/minutes, this is allowed. The minutes can even be decimal minutes if so desired. Since it is impossible to determine whether a lone integer right ascension value is in hours or degrees and to prevent confusion, typing a lone integer coordinate value is considered invalid. This means, for example, if the user wants to do a search for objects near 0 hours right ascension and 0 degrees declination, then they should enter either "0.,0." (the decimal points flag the input as decimal degrees) or "00 00 00, 00 00 00" (if sexagesimal input is preferred). Entering simply "0,0" would be considered an error.

Multiple name/coordinate inputs
Browse can perform name/coordinate cone searches on multiple object names and/or coordinate pairs in a single query submission. The user in this case should separate each entry using a semicolon.

Example of multiple name/coordinate inputs:

  • Cyg X-1; Cyg X-2; Cyg X-3
  • 3c273; 12.235, 15.345; 3c279; 18 12 5.29, 4 18 3.4
The only limit on the number of name/coordinate entries that the user can search for in this manner is determined by their browser. Depending upon the browser used, the limit on the size of the name/coordinates entry string can be on the order of hundreds, or even thousands, of characters. Caveats
When doing searches on position, be aware that the positions in the Swift Master Log refers to the pointing position of the Swift spacecraft, and not the position of the source itself.

Observation Dates

The general format for the observation date is YYYY-MM-DD hh:mm:ss, where the hh:mm:ss is optional. Dates in the form of Modified Julian Date (MJD) are also accepted. Multiple dates are allowed: each date must be separated by a semicolon. Time ranges can be specified using the '..' syntax shown in the example below. If an explicit time range is not given, the range is assumed to be +/- 1 day around the date given. Example of date/time inputs:
  • 2001-01-20 06:00:00
  • 2001-01-20
  • 51929
  • 2001-01-20 .. 2001-02-15
  • 1992-12-31; 48980.5; 1995-01-15 12:00:00; 1997-03-20 .. 2000-10-18
Caveats
(i) When doing searches in time, be aware that the time field refers to, as its name suggests, the Observation Date(s) by the Swift spacecraft, and not the date and time of the GRB itself. (ii) The HEASARC recommends that, when users select a date, they explicitly specify the desired time range, e.g., `2005-01-18 01:30:00 .. 2005-01-18 08:30:00'. Notice that the default time range for Browse in cases where the user enters only a single date and time is +/- 24 hours from the selected time. If the user enters only a single date with no specified time, the default time that Browse assumes is 0:00 UT at the beginning of the specified day: thus, entering `2005-03-16' is equivalent to specifying a time search from 2005-03-15 at 0:00 UT to 2005-03-17 at 0:00 UT.

Search type: radius

This is the angular radius on the sky used in the search by coordinates. Each database table has a default value for cone searches set by the HEASARC. For the Swift Master and TDRSS table, this value has been set to 30 arcmin.
Caveats
When doing searches in coordinates selecting multiple tables, be aware that each table will be searched using the pre-set default radius for that table unless an explicit value has been specified in the Search Radius box, in which case this common value will be used for all the tables searched.

Search type: BAT FOV

When using this option the query returns all observations where the input position was included in the BAT FOV. The software approximates the BAT FOV as an ellipse and uses the roll angle information as stored in the database table for its orientation. This search is a beta version. We hope to use more accurate calculations in a future version.
Caveats
The results of the query when using the BAT FOV option may contain a large number of observations. It is therefore recommended to input only a single position and to restrict the search to only one of observation log tables available. To verify the sky distribution of the observations selected, the user can plot the results by using the 'plot' option available from the "Search Results" page.



Page Author: Browse Software Development Team
Last Modified: 17-May-2006