Skip banner and navigation tools.

 |  site map

The Swift-XRT data products generator

Build XRT products.

Contents

Overview

This facility allows the creation of X-ray light curves, spectra and positions of any object in the Swift XRT field of view. Images of the field of view can also be created. Details of how the light curves, spectra and enhanced positions are produced are given in Evans et al. (2009), (MNRAS, 397, 1177).

The tools which create these products are based on those which run automatically for GRBs (which in turn are based on the Swift software and FTOOLs), with the following modifications:

Although spectra are automatically fitted, the spectral files are available for download as a tar file should users wish to fit different models or interact with the fit. (The RMF file is not included in this file, but is part of the CALDB.)

To create products, simply fill out the form. The object details section is mandatory and the information provided here will be used to identify the source for which products should be built. You also use this section to specify which products you require. For each of the products you choose, an extra form will appear asking for details of the desired product. The label for each form field is a link; following it opens a help box in the top left of the window, which gives summary information about the field. Full details for each option follow here. Note that any control characters (& ; etc) will be removed from your input.

Back to contents | Back to product generator

How to use the products generator

To build products you need to supply basic details of the object and observations, and choose which products you want. The following sections describe each of the forms in detail. Once you submit the form you will be taken to a page telling you the status of your job. The products will appear on this page when they are built, and will be kept for 7 days. Note that it is safe to leave the page or close the browser while the products are building and the job will not be terminated. However we recommend that you bookmark the page first so you can find your products later. Alternatively, if you supply your e-mail address on the main form you will be notified by e-mail when each of your products is built. That e-mail will also contain a link to the page in case you did not bookmark it. Note that every time you submit the products form a new job is executed, so re-entering the product details in the form will start the product building again from scratch, it will not take you to the status page of the existing job.

Object details form

Name
The name of the object. Primarily a cosmetic detail, however the "Find" button will use the name to determine the target ID, RA, Dec and start time if possible. The RA and Dec will be taken from SIMBAD, if the name can be resolved. If not, the values will be taken from the spacecraft pointing information during the first observation of the source. This may differ from the object position, so the default search radius is increased to 3' in this case. If you change the name but do not update the co-ordinates, a warning will be issued. Note -- when you submit the form, the co-ordinates supplied are not checked against any catalogued position for the source name. Although your products will be labelled with the name you supplied, they will be produced for the position you supplied.
Target ID
The target ID of the object. If your object has multiple target IDs which you wish to include in the light curve, these should be separated by commas, with no spaces, e.g. 00050100,00058990. This field is filled in automatically if the name is resolved successfully.
Start time
The zero-point of the observations. This is used to scale the x-axis in the plots. If this is left blank, the TSTART value of the first event list will be used. Accepted time formats are given below. If the name is successfully resolved this field will be automatically set to contain the Swift Mission Elapsed Time at which the first observation of your target began.
Coordinates
The position of the object of interest. This is filled in automatically if the name is resolved succesfully. Note that, if the name could not be resolved by SIMBAD, but matches a target name in the Swift observation database, the RA and Dec are taken from this database. Coordinate entry is free-format (see the acceptable coordinate formats section below).
Try to centroid?
Whether the software should attempt to centroid on the source, to get the best position in the XRT astrometric frame. This only affects the light curves and spectra. It is normally recommended that this be set to "yes" since the position in the XRT coordinate frame may slightly from the object position in other frames (the XRT has an astrometric uncertainty of 3.5" to 90% confidence). However, the centroid algorithm may not find the source if it is very faint. Also, if multiple sources lie in the search region, the brightest is assumed to be the target of interest. In such cases, it is recommended that the user examines the XRT data themselves to obtain the best XRT position of the object, and set this option to "no".
Search radius
If you set "Try to centroid?" to "yes" you must also provide an error radius. The code will centroid on the brightest object within this distance from the RA/Dec provided.
Build light curve/spectrum/position/image
Specify which products to create.
E-mail address
If a valid address is supplied, an e-mail will be dispatched when each of the requested products has been produced. We recommend that you use this facility, as jobs can take a long time to complete. The e-mail address will include the URL of your finished products.

Back to contents | Back to product generator

Choosing observations or time intervals

For each product you can choose which data get used to build the products. The options (not all present for all products) are to use all available data, only observations starting within some period of the first one, or to define which observations to use. The first two cases are self-explanetory however the latter needs some elucidation.

To define which observations are included you can either supply a list of ObsIDs if you know them, a time range, or a mixture of the two. ObsIDs should be entered as an 11-digit number and time ranges as start-stop. You can enter several time intervals, separated by commas. For example, if your object had been observed all year, but you did not want to include the summer observations, you could state 2008/01/01-2008/05/31, 2008/09/01-2008/12/31. Valid date/time formats are detailed below. Note that, when entering dates, only observations which both start and finish within the specified time will be included.

Back to contents | Back to product generator

Light curve details form

There are 4 binning options available:

The latter two settings have no further option associated with them (although see Common Options below), and simply produce a single light curve and hardness ratio bin per Swift snapshot or observation (see the definitions of observations and snapshots). Note that the "per observation" option assumes that the observations do not overlap in time. If this is not true, this binning method should not be used.
For the "Time" or "Counts" binning options there are various customisable settings, as described below.

Binning by time

This is the binning method used for most applications, where bins are defined as being of a fixed duration. Please note that, in this case, no checks are made to guarantee that the source is detected and that Gaussian statistics are valid in a given bin. Please read the caveats before using this for the first time.

Bin length (s)
The duration of each bin. Can be different for WT and PC mode.
Hardness ratio bin length
The length of each bin in the hardness ratio. By selecting "Same as main curve" you can force this to follow the main light curve settings.
Min WT Counts
Sometimes the XRT enters Windowed Timing mode for reasons other than source brightness, such as earth limb contamination. This can result in spurious WT data points with non-Gaussian errors which ruin the scaling of the light curve plots. By setting this field, any WT mode bin with fewer than the specified number of counts is assumed to be a spurious bin, and is rejected.

Back to contents | Back to product generator

Binning by counts

This is the method used for binning GRBs and is described in detail in Evans et al. (2007).

Counts per bin
The minimum number of counts necessary for a bin to be filled.
Min bin length
The shortest duration a bin can have.
Dynamic binning
In the standard products, the data are binned dynamically; that is, the binning criteria vary with count rate. In this case the "Counts per bin" field is valid at 1 count per second. At any other count-rate the counts-per-bin value (X) is determined dynamically thus:
When the count rate changes from 1, by some factor (the rate factor), X changes by some other factor (the bin factor). The default values for these factors are 10 and 1.5 respectively, thus an order-of-magnitude change in count rate produces a factor of 1.5 change in bin size. This is done discretely rather than continuously, so if X=20 then where the count rate lies in the range 1-9.99 cps a bin must contain at least 20 counts. However, when the count rate is 10-99.99 cps, there must be 30 counts for a bin to be full. At lower rates of 0.1-0.99 cps, only 13 (=20/1.5) counts are needed to complete a bin, although this is rounded to 15: no matter how low the count rate goes, a bin will always need at least 15 counts, to ensure that using Gaussian methods to propagate errors statistics is valid.
Rate/Bin factor
The settings to control the dynamic binning (see above).
Minimum counts per bin
Some minimum below which the dynamic binning cannot drop. We suggest that you leave this at 15 (or higher) so that the assumption that the errors are Gaussian is valid.
Minimum sigma
For all but the final bin, the bin is not full until the bin's sigma value (i.e. src_cts/ sqrt(bg_counts_in_src-reg)) is equal to or exceeds the value specified here.

Back to contents | Back to product generator

Common options

Energy and grade selection
The default setting is to extract light curves using events of grade 0-12 (or 0-2 for WT mode), between 0.3 and 10 keV. For the hardness ratio, the soft band covers 0.3-1.5 keV and the hard band 1.5-10 keV. If this option is set to "User specified" these numbers can be changed. For grades there are only two options: to use the default grades (0-12 for PC and 0-2 for WT mode), which is recommended; or only grade 0 events. If you do not know what this means, use the default.
Specify observations
See Choosing observations or time intervals, above.

Back to contents | Back to product generator

Spectral details form

Use redshift?
If this is set to "No" (default) the automatic spectral fit is simply an absorbed power-law, with no components fixed. However if you choose to supply a redshift the absorption is split into two components. One is at redshift 0 and frozen to the Galactic column, the second is frozen at the redshift you supplied, and the column density if free.
Redshift
If you said "Yes" to the above you must supply the redshift to be used.
Use which observations
See Choosing observations or time intervals, above.
Grade range
Whether to use events with the default grade selection criteria (0-12 for PC, 0-2 for WT mode) or only grade 0 events. Unless you know what this means, use the default. Note that the counts-to-flux conversion factor deduced from this spectrum is appropriate to the grade selection used, so if you intend to convert a count-rate light curve into flux, the light curve must be created with the same grade selection.
Time for spectrum
By default, all data contained within the selected observations are included in the spectrum. If you wish to define time ranges, select "User defined" from the drop-down menu. You can then enter up to four time regions. Each region must have a name and a time region. The latter is of the format start-stop (see accepted time formats) and can include multiple intervals separated by commas.

Back to contents | Back to product generator

Position form

Two types of position are produced: enhanced and unenhanced. Each of these uses a PSF fit, with bad column and pileup correction built in, rather than the barycentric approach in the xrtcentroid tool. For the enhanced positions the absolute astrometry is corrected using field stars in the UVOT, this yields a systematic uncertainty of 1.4" (90% confidence), compared to the 3.5" systematic for the unenhanced positions, where the astrometry is determined from the star trackers.

As well as correcting for the bad columns and any pile up, the PSF fit has a lower statistical error than the barycentric one. In the latter case the statistical error is calculated as Err=22*C-0.48, where C is the number of counts in the image. For PSF fitting the error is determined for each fit, however simulations show it scales approximately as Err=14.6*C-0.48.

The fields in the position form are details thus:

Inclusion radius
For each XRT image created as part of position determination, source detection and centroiding is performed. The source nearest to the object position given in the Object Details form is taken as the object of interest, provided it lies within this inclusion radius.
Use which observations
See Choosing observations or time intervals, above.
PSF Method
There are 3 methods which can be used to determine the position:
  1. Sum all data
  2. First snapshot only
  3. Multiple snapshots (default)
In most cases the third method is advised. Details of each method, and when to use which, follow:
Sum all data
This is necessary for sources which are too faint to be found in a single snapshot. A single image and exposure map is created from all available data, and then fitted. Note that this can be slow (as many exposure maps are created and summed). This method is not recommended for highly variable sources (unless they are never piled up), as the PSF of the aggregate image in such cases will not correspond to any individual calibrated profile which may reduce the position accuracy.
First snapshot only
In this method a single image and exposure map are created from only the first snapshot of PC mode data in which a source can be detected. This is the fastest method. This is only recommended for bright sources (with more than about 300 counts in the first snapshot) where the statistical error from a single snapshot is low.
Multiple snapshots
This is the recommended approach for most cases. The data are divided into snapshots, and a centroid is performed for each snapshot. The PSF profile used is chosen on a snapshot-by-snapshot basis accounting for variability. The final position is formed from the weighted mean of these positions, with the XRT systematic error added in quadrature as a final step. If this method is chosen, the results page will give the centroid (and image) from each snapshot for diagnostic purposes.
A sub-option of this method allows you to set the statistical error threshold, discussed below.
Statistical error threshold
If the "Multiple snapshots" method is chosen, you can specify the statistical error threshold. A running measure of the the statistical error in the weighted mean position is kept, and once it drops below the threshold value, the process stops and the position is reported. This is an efficiency setting: since the systematic error is 3.5" it is inefficient to use all (for example) 50 snapshots of data for a source if the statistical error is 0.2" after three snapshots. By default however, this value is set to 0, so all snapshots will be used.

Back to contents | Back to product generator

Image form

Images are produced in gif and FITS format.

Energy Bands
Here you specify the energy band(s) for your image(s), as a comma separated list of lowen-highen values. Energies should be in keV. The default setting is to create 3 images, 0.3-10 keV, 0.3-1.5 keV and 1.5-10 keV.
Use which observations
See Choosing observations or time intervals, above.

Back to contents | Back to product generator

Data input formats

While efforts have been made to allow users to enter data in any format they desire, it is not possible to transparently handle any conceivable input. Details of the supported input formats are below.

Time formats

Although none of the time fields is mandatory, there are several places you may wish to enter a time: the "Start time" box, to specify which data should be included in your products, and to generate time-resolved spectra. The same formats are acceptable in each box, although see the important caveat for calendar dates.

There are 3 general time formats permitted: calendar dates, [Modified] Julian Dates and Swift Mission Elapsed Time (MET). For time-resolved spectra you can also enter the time in seconds since the "Start time".

Note that dates before the Swift epoch of 2001 January 01 are not accepted.

Calendar dates

The general form for calendar dates is year month day, delimited with spaces, slashes (/) or hyphens (-). A time may also be appended as hours:minutes:seconds. This should be separated from the date either by a space, a T, @ or the word "at". The year must be a 4 digit number, month can be either the full month name in English, the first 3 digits of the month, or the month number (January=1). Some examples are given below.

Important caveat: The use of hyphens as delimiters is only possible in the "Start time" box. Any box accepting a time range uses hyphens to separate the start and end times, so, for example 2009-09 would be interpreted as "from 2009 until 9" which in turn would generate an error as these are not valid inputs.

Back to contents | Back to product generator

Julian Dates

Julian Dates or Modified Julian Dates can simply be entered as they are, optionally prefixed with JD or MJD. For example 2454950.5, or 54950 are acceptable Julian Dates.

Back to contents | Back to product generator

Mission Elapsed Time (MET)

MET is the time used internally by Swift; any times you enter are ultimately converted to MET. If you know the MET of the time in question, you can enter it directly. Note that any purely numeric (or exponential) number entered in a time box which cannot be parsed as a calendar date of Julian date will be assumed to be an MET value (for time-resolved spectra, if the number is less than 108 it is interpreted as the time since the start time).

Back to contents | Back to product generator

Coordinate formats

Coordinates must be entered as RA followed by Dec, separated either by a comma or space. Each co-ordinate can be in decimal degrees or sexagesimal. In the latter case RA is interpreted as being in hours, not degrees. Coordinates are assumed to be in J2000.0 and will not be precessed.

Sexagesimal input must have at least minute accuracy, but apart from this any valid format should be correctly parsed. For RA, hours, minutes and seconds can be separated by spaces, colons or h, m or s. Sexagesimal declination entries can be separated by colons, spaces, d, m, ', s or ". Note that meaningless use of these delimiters will result in an error. For example legal values for RA include 12h34m12s, 12 34.2 or 188.55, but 12d34m would generate an error, d cannot be used to separate RA hours from RA minutes! Some examples of valid inputs are below. This is not exhaustive.

Back to contents | Back to product generator

Usage and acknowledgement policy

Users may publish any products created using these web tools, provided that this facility is acknowledged. We request this be done both by citing Evans et al. 2009, (MNRAS, 397, 1177) when the data are introduced (if you use an enhanced position, please also cite Goad et al. 2007, A&A, 476, 1401), and including the following text in the acknowledgements section of the paper (not necessary for ATELs or circulars): This work made use of data supplied by the UK Swift Science Data Centre at the University of Leicester.

Back to contents | Back to product generator

Caveats

General

The software used to create XRT products have been designed to work for point sources. Source localisation, pile-up detection and correction, bad column correction etc. are directly affected by this assumption. These tools should not be used to create products for extended objects.

The time taken to create your products can take anything from a few minutes to a few hours, depending on the current number of jobs running, the number of observations included in your request, and the number of source events (for light curves). It is thus recommended that you bookmark the "working" page to which you are taken after submitting the form. We also suggest you supply your e-mail address, so that you are notified once your products are built, and given the link to them. In extreme cases, for very bright sources with many observations, we recommend that users submit multiple jobs (ideally sequentially), requesting only a few observations in each one.

Light curves

The code used here assumes that errors can be propagated according to Gaussian statistics -- except for the final bin of the data (a holdover from the GRB code, which is useful and so kept). Thus, if the bin size is such that some bins contain fewer than 15 counts, the error values may well be wrong. The onus is on the user to specify sufficient counts that the statistics are Gaussian. A warning will be given on the light curve results page if any bins contain fewer than 15 counts.

The maximum number of bins permitted in a single light curve is 500,000. When a light curve is selected with constant-duration bins, the total exposure time in each mode is divided by the binsize. If either mode exceeds half a million bins, the light curve will not be built. In such cases users can either select larger time bins, or create several light curves, each using less than the full set of observations, and then combine these manually to give the complete light curve.

Back to contents | Back to product generator

Change log

Back to contents | Back to product generator