About Chandra Archive Proposer Instruments & Calibration Newsletters Data Analysis HelpDesk Calibration Database NASA Archives & Centers Chandra Science Links

Skip the navigation links
Last modified: December 2006

URL: http://cxc.harvard.edu/ciao3.4/lightcurve.html
Hardcopy (PDF): A4 | Letter
AHELP for CIAO 3.4 lightcurve Context: tools

Synopsis

Bin source and background events by specified time intervals

Syntax

lightcurve infile bkgfile outfile nbins binlength counts_per_bin
[errtype] [bkgfactor] [kernel] [clobber] [verbose]

Description

NOTE: lightcurve has been deprecated as of CIAO 3.0; users are encouraged to migrate to dmextract ("ahelp dmextract"). Development on this tool has stopped, but any new bugs found will be reported on the CIAO bugs page.

`lightcurve' will first get the good time intervals from the GTI (Good Time Interval) extension of the source file. From these it determines the data start time (start_time) and data stop time (stop_time) as the beginning of the first good time interval, and the end of the last good time interval. If the input source file does not have the GTI extension, start_time will be set to TSTART (listed in the header of the source file), and stop_time will be set to TSTOP (also listed in the header of the source file).

After getting the good time intervals from the source file, lightcurve will determine the bin size according to the "nbins", "binlength", and "counts_per_bin" user parameters.

There are three binning options in lightcurve. The user can bin by one of the following options:

1) total number of bins ("nbins" greater than 0): binlength = (stop_time - start_time) / (nbins)

2) bin length in seconds ("binlength" greater than 0, and "nbins" less or equal to 0): nbins = (stop_time - start_time)/(binlength) + 1

3) minimum number of counts per bin ("counts_per_bin" greater than 0; and "nbins" less or equal to 0; and "binlength" less or equal to 0): This option requires the tool to find out how many events are in the source file, and how many events are in the background file (if specified). NOTE: If command line filtering is applied on the input files, this option is not recommended because it requires going through the whole file to find out the total number of events and this is time consuming.

The total number of bins, and bin length can then be determined from the following equations:

binlength=(counts_per_bin/total_net_counts) * exposure

where total_net_cnts=total_source_cnts - source_area/bkgd_area * bkgfactor* bkgd_source_cnts

(Note that bkgfactor is the background normalization factor entered by the user, and the default value is 1.)

nbins = (stop_time - start_time) / (bin_length) + 1

`lightcurve' proceeds as follows for each bin: a)Read and sum the first bin of data from the source file. b)Read and sum the first bin of data from the background file if there is a background file. c)Determine the good exposure in the first bin. This is just the time in the bin that also lies within the good time intervals. d)Calculate the net counts, net count error, net count rate, and net count rate error in the bin. Note: Net count rate = (net counts in the bin)/(good exposure in the bin). Also Note: There are 2 different methods used for calculating the uncertainties on counts (or count rate), namely Poisson statistics and Gaussian statistics. User can pick either method by setting the "errtype" user parameter. For Poisson statistics (set errtype= poisson): error=1+sqrt(counts + 0.75) For Gaussian statistics (set errtype=gaussian): error=sqrt(counts) e)Write the results to the output lightcurve file.

Analysing multi-chip Chandra data

Chandra event files contain data blocks which represent the "good-time intervals" - or GTIs - for an observation, and each ACIS chip can have a different set of GTIs. For pipeline-produced data, the GTIs give the time periods when the mission time line parameters fell within acceptable ranges (see "ahelp mtl" for more information). Additional temporal filtering by the user - such as to remove background flare events - can further restrict these periods; the data subspace of a file (see "ahelp subspace") lists the GTI ranges that have been applied to it.

For single-chip data, the event file should be filtered on the ccd_id (ACIS) column to ensure that the correct GTI is used. This can be done either before passing the file to lightcurve or by using the DM virtual-file syntax for the infile parameter, e.g.

         infile="acis_evt2.fits[ccd_id=7]"
      

to select the data, and GTI, for ACIS-S3. If no filtering on chip number has been applied, then the GTI for the aim-point chip will be used.

The situation is much-more complicated for regions that span chips. In most cases the GTI ranges for the different chips will not be significantly different, so the use of a single GTI (lightcurve will use the GTI for the chip at the aim-point) will not significantly affect the result. If there are significant differences in the GTI ranges between chips, then great care must be taken, such as analysing chips individually. For ACIS data, the ONTIME series of keywords in the header of the event file list the exposure times of the different chips.

Example

lightcurve infile="in_source.fits[EVENTS]" bkgfile=NONE
outfile=out_lightcurve.fits nbins=500 binlength=0 counts_per_bin=0

Create a lightcurve with no background subtraction with a total of 500 bins.

Parameters

name type ftype def min max units reqd
infile file input         yes
bkgfile file input NONE       yes
outfile file output         yes
nbins integer   0       yes
binlength real   0     seconds yes
counts_per_bin real   0       yes
errtype string   poisson        
bkgfactor real   1        
kernel string   default        
clobber boolean   no        
verbose integer   0 0 5    

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input source file.

Input FITS source file. The source file must be time-sorted.

Parameter=bkgfile (file required filetype=input default=NONE)

Input background file.

Input FITS background file. The background file must be time-sorted.

Note that the GTI block from the source file (ie infile parameter) is used to select good times in the background file. This can have implications if the background is taken from either a different chip (for Chandra ACIS data) or from a different event list, as described in the "Analysing multi-chip Chandra data" section of this help file.

Parameter=outfile (file required filetype=output)

Output lightcurve FITS file. Currently, the output will only be in FITS format. The output table contains all relevent information for each time bin.

Parameter=nbins (integer required default=0)

Total number of bins.

Total number of bins. This is the first binning option. If 0 is entered here, the data will be binned according to the binlength.

Parameter=binlength (real required default=0 units=seconds)

Bin length in seconds.

Bin length in seconds. This is the second binning option. If the total number of bins is given, the value entered for bin length will have no effect on how the data should be binned. If 0 is entered for both the total number of bins, and bin length, the data will be binned according to the minimum number of counts per bin.

Parameter=counts_per_bin (real required default=0)

Minimum counts per bin.

Minimum counts per bin. This is the last binning option. If the total number of bins or the bin length is given, the value entered for minimum counts per bin will have no effect on how the data should be binned. Note that if command line filtering is applied on the input files, we do not recommend using the counts_per_bin binning option, since it requires going through the whole file to find out the total number of events in the file, and this is time consuming.

Parameter=errtype (string default=poisson)

Method used for calculating the uncertainties on counts and count rates. (poisson|gaussian)

Parameter=bkgfactor (real default=1)

Background normalization factor.

Background normalization factor. It is used to scale the background counts when calculating the net counts in a bin.

Parameter=kernel (string default=default)

Data Model creation/copy kernel.

Data Model creation/copy kernel. It allows the user to specify the format of the output file. Currently, the tool can only create a FITS file.

Parameter=clobber (boolean default=no)

Clobber the existing output file?

Parameter=verbose (integer default=0 min=0 max=5)

Verbosity level (0=none, 5=most).

CHANGES IN CIAO 3.0

There have been no changes made in 'lightcurve' for CIAO 3.0. As of CIAO 3.0, 'lightcurve' will no longer be actively maintained or enhanced. Users instead are encouraged to create lightcurves with the new lightcurve functionality of 'dmextract', which more carefully and accurately applies good time interval (GTI) information. For users choosing bin option 2 above, i.e., binning by setting a bin length in seconds, 'dmextract' is the recommended choice. For users choosing binning method 1 (i.e., binning by total number of bins), or method 3 (i.e., binning by a minimum number of counts per bin), 'lightcurve' is still viable, as 'dmextract' does not directly support those options.

CHANGES IN CIAO 3.4

IRAF QPOE Files

Support for IRAF QPOE files has been removed from CIAO.

Bugs

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

Hardcopy (PDF): A4 | Letter
Last modified: December 2006



The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory.
60 Garden Street, Cambridge, MA 02138 USA.    Email: cxcweb@head.cfa.harvard.edu
Smithsonian Institution, Copyright © 1998-2004. All rights reserved.