Skip banner and navigation tools.

 |  site map

Swift-XRT GRB Light Curve Repository — Algorithm



The process of building light curves was discussed in detail in Evans et al. (2007), and slightly revised by Evans et al. (2009). Since then, there have been many small modifications and many larger under-the-hood improvements in efficiency, which are detailed in the changelog. This page provides an up-to-date overview of the algorithm. This is deliberately written generically, to cover both automatically generated GRB light curves and products created on-demand: the only difference between these two cases is that for GRBs a specific binning method is always used, whereas for on-demand products, the user can select the method and parameters.

The process can be split up into three phases which, in the original paper, we named alliteratively as the preparation, production and presentation phases. These phases can be summarised thus:

Preparation phase
The purpose of this initial phase is to start with the full set of observations of the object, and produce one of each of several key files per mode, as described below. This represents the bulk of the work of creating a light curve, and consequently the majority of the time it takes to build a light curve is spent in this phase.
Production phase
Also know as the ‘binning’ phase, this is where the files produced in the preparation phase are analysed to produce a binned data file per mode, according to the binning criteria requested.
Presentation phase
In this phase, the binned data file from the production phase is converted into the main light curve files and hardness ratios. These are then also plotted to allow presentation in graphical format.

The following sections describe the algorithms of these three phases. For GRBs, light curve data can also be constructed from the data obtained in WT mode while the spacecraft is slewing to the newly-discovered burst. These ‘WT settling-mode’ data are analysed via a separate script and only combined with the normal pointing-mode data at the presentation phase.

Back to contents | Back to repository

Preparation phase

This phase begins with the data from the quick-look site and archive, and ends by producing the following files (per mode):

Source event list
A single event list containing all events from the source extraction region from all of the constituent observations. The source region may not have been the same in all observations, information about this is embedded in the event file.
Background event list
A single event list containing all events from the background extraction region from all of the constituent observations. As with the source list, the background region may change from one observation to the next, and this information is stored in the event list.
Correction file
A single file listing the PSF corrections to be applied, as a function of time. This is generated from each individual observation, using the xrtlccorr software.
Systematic error file (WT only)
A single file giving the systematic error as a function of time.

For WT mode data, if any snapshots were marked as unreliable (see below), then there will be two source and background event lists created: one comprised of all available data, and one which does not include data from the unreliable snapshots.

The preparation phase begins by attempting to detect and localise the source (unless centroiding has been disabled), initially using only the data from the first observation, but using later datasets if the source cannot be found in the first one. A deep image of all observations is also created, and source detection is used to identify all sources in this image, so that they can be excluded from the background extraction region. The code then steps over each observation, and within these it works independently, first in WT mode, and then PC mode. The observation is split into snapshots - periods of continuous observation - and the following steps are run for each snapshot:

  1. (WT mode only) Identify the roll angle of the spacecraft in this orbit, and update the keyword in the event list1.
  2. Attempt to centroid on the source. If this fails, either calculate a count-weighted mean of all centroids to date (PC mode) and use this, or mark this snapshot as unreliable (WT mode).
  3. Check that the source is fully inside the field of view, and skip the snapshot if it is not.
  4. (PC mode only) Estimate the mean count-rate of the source in this snapshot, and adjust the source extraction radius accordingly.
  5. (PC mode only) Check if the background annulus falls outside the field of view, and if so, adjust it.
  6. Check for times of pile-up, and create annular source regions appropriate to eliminate pile up.
    If the source is piled up for some of the snapshot, but not for the entire time, the annular region will only be used during the times of pile-up: in this case the event list for the snapshot will be split up, with one event list for all the non-piled up times, and one event list per interval of pile up. Additionally, for GRB-like sources which decay over several orders of magnitude, a new pile-up interval is identified every time the source fades in WT mode by a factor of two: this allows us to reduce the inner radius of the annulus, so as to maximise the number of source counts included in the light curve.
  7. Create an event list for each of the times identified, using the appopriate source extraction region for each, call this a ‘Source event list’.
  8. For each event list just created, build an exposure map and run the xrtlccorr code to build a file giving the time-dependent PSF corrections.
  9. (WT mode only) Construct a file to calculate the evolution of the source position on the CCD and the corresponding systematic error, as a function of time. The systematic error is determined using a predefined model which was calibrated using simulations.
  10. Create an event list for the entire snapshot based on the background region (in PC mode, removing from this region any sources identified in the deep image at the start of the process.

1 An event list has a single roll angle keyword (PA_PNT), so if there are multiple spacecraft orbits in the list it will contain the mean value. The s.mkf file in the data auxil directory gives the roll angle as a function of time, and we use this to determine the per-snapshot roll angle.

Once all snapshots in the observation have been processed in this way, the source event lists are merged into a single source event list, and likewise for the background event lists, the correction files produced by xrtlccorr, and the WT mode systematic error files. This process is repeated for all observations, and then the per-observation files are then merged, and sorted into time order. Note that the PC and WT mode files are not merged with each other, but remain distinct.

At this stage the preparation phase is complete.

Back to contents | Back to repository

Production (binning) phase

The next step is to take the event lists produced in the preparation phase and bin the events into a light curve. If the data contain unreliable WT mode points the binning process is performed twice for WT mode: once using only the reliable WT mode snapshots, and once using all snapshots.

The binning software runs on PC mode and WT mode separately, following the same process for each (apart from the WT mode systematic errors, see below). It reads in the files produced by the preparation phase, and the first step is to identify the snapshot times. This is done using the GTI information in the event lists.

The four binning methods are:

  1. Count binning (default for GRBs)
  2. Time binning
  3. Snapshot binning
  4. Observation binning

Time binning is probably familiar to all readers: the bins are of a predefined duration; therefore the bin times are defined first, and then source and background events are allocated to them. Snapshot binning and observation binning are similar, except that instead of the duration of the bin being set in seconds, it is set in Swift's observing units. i.e. one bin is constructed for each snapshot, or each observation; thus the bins can be of non-uniform duration. In each of these cases, events are allocated to the appropriate bin based on their time, therefore if the dataset has observations which overlap in time, per-observation binning cannot be used, because there is not a unique mapping from time to bin. Count binning, as employed for GRBs, is different: in this case a bin accumulates events until it is deemed to be ‘full’ (described below).

Whichever binning method is used, once a bin has been filled, certain operations are carried out before the bin is saved. The decisions made at this point depend upon the parameters of the binning that have been specified, and much of this has been added to the software since the publication of the papers describing the facility, therefore we detail them in full.

  1. The significance, σ, of the source detection in the bin is calculated, as (C-B)/ΔB, where C is the number of counts in the bin, B is the expected number of background counts, and ΔB is the uncertainty in the background estimate. If B=0, σ is set to an arbitrary high number (1000).
  2. The signal-to-noise ratio (SNR) of the bin, = S/ΔS is estimated. S is the number of source counts in the bin (i.e. C-B) and ΔS the uncertainty therein. At this stage, this is calculated using frequentist statistics, i.e. ΔS=√(C+B).
  3. There are now three options as to the type of bin that can be produced: a frequentist bin (as above); a ‘Bayesian bin’, where the count-rate, error and significance are determined using the method of Kraft, Burrows & Nousek (1991); or an upper limit (also derived using the Bayesian calculation). Which is produced is determined as follows (note that once a bin is produced, the decision-making process ends. e.g. if after the second step a bin was produced, the remaining steps are not considered. This also means that step iii, for example, implicitly assumes that the conditions of steps i and ii were not met):
    1. If upper limits and Bayesian bins are not enabled, produce a frequentist bin.
    2. If the number of counts in the bin and the SNR of the bin are above the Bayesian threshold, produce a frequentist bin.
    3. If upper limits are not allowed, produce a Bayesian bin.
    4. If σ (from step 1) is below the minimum value required (3 for GRBs), or if Bayesian binning is allowed and the SNR calculated in step 1 is below the Bayesian threshold, the Bayesian method is used to determine σ and therefore whether the source is detected (i.e. σ is above the minimum value).
    5. If the source is detected, produce a Bayesian bin (if allowed) otherwise a frequentist bin.
    6. If the source is not detected, produce an upper limit (because of the first few steps in the process, it is only possible to reach this step if upper limits are enabled).
  4. If the bin produced by this method is a Bayesian bin, σ and the SNR are recalculated once the bin has been produced, since the calculations in step 1, which were frequentist in nature, are not valud.

For time, snapshot and observation binning, once the above steps have been done, details of the newly created bin are written to disk. For counts (GRB-style) binning, there are more steps which must be taken, as we now explain.

Extra steps for counts binning

When binning by counts, a bin that has undergone the above steps is not necessarily finalised. If the source was found to be undetected in the bin, instead of being saved, the bin is kept ‘open’ that is, events continue to be added to the bin until either the bin represents a detection, or an observation gap longer than some specified maximum duration is exceeded. In the latter case, the bin must be written to disk and a new bin started. In the former case, even though the bin represents a detection, and meets the binning criteria it is not immediately finalised. A new bin is started, but the previous bin is not written to disk, but stored in memory. At the end of the current snapshot of data, if the new bin is not yet complete, the software decides whether to append those counts to the previous bin (in which case the bin calculations are reperformed), or to keep the new bin open, and carry it forward to the next snapshot; whichever method maximises the fractional exposure is accepted. A bin is only finalised and saved when the observation gap criterion mentioned above is met, or when the next bin is considered ‘complete’.

Hardness ratios

The hardness ratios are produced in a manner identical to that described above, except that events are allocated to the hard or soft channels depending on their energy and only frequentist calculations are permitted. Also, if counts binning is selected, for a bin to be considered complete the number of counts in the bin must exceed the specified threshold in both channels.

Back to contents | Back to repository


At the end of the production phase binned data files exist separately for WT and PC mode, and these files contain much more than simply count-rate data (they are in fact the detailed data files which you can download). The bins comprising detections are in separate files from the upper limits. The presentation phase parses these files and combines the appropriate data from each to produce the final light curve plots presented online. These are plotted as postscript files using qdp and then also converted to GIF format for publication on the website. The different light curves produced by this phase of the process are described in the light curve web page documentation.

If the light curve contains WT mode data, the presentation phase produces two light curves: in the first the count-rates and errors are taken directly from the output of the production phase; in the second the systematic errors are removed before plotting. If the light curve contained unreliable WT mode points, the production phase produced two WT mode datasets: one including only the reliable WT mode data and one using all data; the presentation phase will produce separate plots based on these two datasets. Therefore, the presentation phase produces up to four sets of light curves, those with and without systematic errors and for each of these, those with and without the unreliable WT mode data.

Back to contents | Back to repository

WT settling-mode data

Swift collects data in WT mode while the spacecraft is slewing. For most objects these data have little value: they add maybe 5—10 s of data at the start of the exposure, but they cannot always be analysed reliably, especially if the source is not bright: it is better to rely purely on the standard data available once Swift has settled on the target. For GRBs, however, speed is of the essence, and those few seconds of data potentially contain interesting information. We therefore include the settling-mode data in GRB light curves, provided the source is bright enough to produce at least 15 events in the settling-mode data (if the source is fainter than this, the light curve will be background-dominated).

The settling-mode data cannot be analysed using the same software as the normal, pointing-mode data, because the spacecraft attitude information during the settling phase is less accurate than after Swift has settled, and also, the degree of inaccuracy is changing. That is, the position of the GRB in RA & Dec appears to change while the spacecraft slews! Therefore, in order to analyse the settling mode data, it is necessary to determine the source position in the XRT coordinate frame with high cadence. Based on a detailed analysis of the data, we find that repeated centroids are necessary until the slew rate has fallen below 1 pixel/sec in the CCD x and y axes, at which point the attitude information has stabilised; from this point onwards, if necessary, an RA & Dec position derived from pointing-mode data can be used.

Of course, despite this difference, the overall approach to constructing a settling-mode light curve is the same as for the pointing mode-data. The settling-mode algorithm can be summarised thus:

  1. Convert the source (RA,Dec) position derived from the pointing-mode data into a time series of detector (x,y) positions, with 0.5 s cadence.
  2. Using this series, identify the times when the slew rate drops below 10 pix/sec in each axis, and below 1 pix/sec in each axis. Also discard data where the source lies more than 20 pixels outside the WT-mode field of view.
  3. If the source is piled up (i.e. bright), create an image and exposure map every 40 events, and centroid on the source in each image, to produce a time series of (RA,Dec) positions in the (evolving) XRT coordinate frame.
  4. If the source is not bright enough for pile-up to be an issue, it is also not bright enough to generate usable time-dependent centroids, so the data taken while the slew rate is above 1 pixel/sec in either axis are discarded. If there are still at least 20 events in the event file, build an image and exposure map, and centroid on the source. Otherwise, rely on the position derived frmo the pointing-mode data.
  5. If centroiding was performed in steps 2 or 3, recalculate the time series of detector (x,y) positions, with 0.5 s cadence. At each interval, also calculate the systematic error associated with that detector position. If a time series of (RA,Dec) positions was produced in step 2, then the (RA,Dec) to be converted to (x,y) at each 0.5-s step is derived by interpolation from these centroids.
  6. If the source is bright enough to be piled up, identify an annular region around the source which is not affected by pile up. Recalculate the time-dependent systematic error appropriate for this annular extraction region.
  7. Step through the event list, and for each event in the list, perform the following steps:
    1. Determine the detector (x,y) position of the source at the time of this event, by interpolating on the time-series of positions produced in step 5.
    2. If a time-dependent series of centroids, with a centroid at least once every 0.2 s, was produced (in step 3), discard this event if the source is more than 20 pixels outside the field of view; otherwise, discard the event unless the source is inside the field of view, and at least 20 pixels from the edge. If the event is discarded, the process moves to the next event. Otherwise:
    3. If the source is piled up, but the cadence of time-series of position is lower than one position every 0.2 s, discard the event if the slew rate is above 10 pixel/s.
    4. Calculate the correction factor for PSF losses due to the bad columns, field of view size, and (if necessary) the pileup annulus used.
    5. Determine the systematic error at this time, by interpolating the time-series of systematic errors produce in step 5.
    6. Write the time, energy, grade, PSF correction factor, detector position and systematic errors to a file.
  8. The file produced by the above steps is analagous to the final event lists produced in the preparation phase for pointing-mode data. This can then be binned using the same algorithm as applied to the pointing mode data in the production phase, except that Bayesian bins and upper limits are not supported. This is carried out before the presentation phase, which incorporates the settling-mode data into the final light curves.

Back to contents | Back to repository