extract

Extract light curve, image or spectrum

Extract product files from the entered data, using the entered filters and selections. Extract is the new name for the old bin command. Bin still works for the nonce.

The extract command works on the latest set of product event files that you have produced. So if you have run GISCLEAN, SISCLEAN, or SELECT EVENTS, extract will operate on the cleaned or selected files, not the original files. Similarly, if you have done a EXTRACT EVENTS, a later extract will use the output events list.

The possible products are a light curve (EXTRACT CURVE), in either QDP or FITS format (or both), a spectrum (EXTRACT SPEC), an image (EXTRACT IMAGE), or a filtered FITS events list (EXTRACT EVENTS). Any combination of these is also possible simultaneously. Also, EXTRACT ALL is equivalent to EXTRACT “CURVE IMAGE SPEC”

If the event file contains polarization data then EXTRACT SPEC and EXTRACT CURVE produce three spectra or light curves, one for each Stokes parameter. An additional argument can be supplied to the EXTRACT command to control the weighting scheme used. STOKES=NEFF used the method of Baldini et al. (2203.06385), STOKES=SIMPLE the method of Kislat et al. (1409.6214), STOKES=UNWEIGHTED assumes the weights are identically unity, and finally STOKES=NONE just produces a single spectrum or light curve ignoring the polarization data.

Extract assumes that there is a GTI extension (whose extname is set in the mission database file) in the same fits file which stores the event data. It accepts timing filters in three forms, ASCII or FITS GTI form, and Xronos window format. It also accepts SAOIMAGE format region descriptor files, which are concatenated into one file called xsel_region.xsl, and fed to the extractor program.

If sisclean has been run, then the cleaned events list (stored in xsel_in_events.xsl) will be used. To clear this use clear sisclean.

If select hk or select mkf have been run, the resulting GTI's will be applied automatically. To clear this use clear hksel, or clear mkfsel.

If a timing selection has been made using filter time cursor, this too will be applied automatically.

The various bin sizes, etc, are inherited from the set command. Some of them can also be changed on the fly, by entering hidden parameters, but these values only apply to this invocation of extract.

When extracting events only the events and GTI extensions are written by default. If the copyall=yes option is set then the extra extensions from the (first) input events file are appended to the output file.

If offset is set to no then the lightcurve written will have times in spacecraft units. If offset is yes (the default) then the lightcurve times are written relative to the first bin.

Binned spectra, images and lightcurves can be plotted with the PLOT command.

Syntax:

xsel >  extract <bin_what> [use_qdp] [binsize_t] [pharebin_t]
               [xybinsize_t] [phalcut_t] [phahcut_t]  
               [xcenter_t] [ycenter_t] [xysize_t] [exposure]
               [use_qdp] [wmapcalfile] [offset] [stokes]

Examples :

a)

xsel >  extract "CURVE EVENT"

Produces a light curve, and also a filtered event list. To use this filtered event list for the next run of extract, say

xsel >  save event my_evtlist.fits yes

This is equivalent to saving the event list, and re-entering it using the read command.

b)

xsel >  extract ALL

this is equivalent to

xsel >  extract "CURVE IMAGE SPECTRUM"

c)

xsel >  extract "CURVE SPECT" bins = 30 pharebin = 4

Extracts a light curve and a spectrum, and temporarily resets the binsize and pha- rebinning factors.

d)

xsel >  extract "CURVE SPECT" exposure=0.0

The exposure parameter controls the rejection of bins from the light curve (only), based on how much of the bin lies within the GTI's. If exposure=1, then a bin is only written to the light curve if it lies wholly within a GTI. If exposure=0, then bins are written to the light curve if any portion of them lies within a GTI. Exposure can have any value between these two extremes. Of course, if a bin does not fall inside any of the GTI's, it will not be written to the light curve, no matter what the value of exposure is.

xsel >  extract "CURVE SPECT" bins = 30 pharebin = 4

e)

xsel >  extract "SPECT" stokes=SIMPLE

Extracts three spectra, one each for the I, Q, and U Stokes parameters, using the weighting scheme from Kislat et al.

HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: Tuesday, 10-Jan-2023 11:03:01 EST