NAME

EXTRACTOR -- Extracts products from input events files

USAGE

       extractor <filename> [<eventsout> [<imgfile> [<binf> [<fullimage>
               [<phafile> [<specbin> [<wtmapb> [<wtmapfix> [<swapx> [<swapy>
               [<binh> [<wmapver> [<fitsbinlc> [<qdpfile> [<binlc> [<lcthresh>
               [<lcthwarn> [<lcstart> [<lctzero> [<unbinlc> [<regionfile>
               [<timefile> [<adjustgti [<gtinam> [<xcolf> [<ycolf> [<zcolf> [<xint>
               [<yint> [<tcol> [<ecol> [<stokes> [<polwcol [<ccol> [<gcol>
               [<gstring> [<xcolh> [<ycolh> [<gtitxt> [<xronwn> [<events> [<gti>
               [<timeorder> [<timeref> [<tpixrpar> [<usetpixrsel> [<eventkey> 
               [<phamax> [<xfkey> [<yfkey> [<xhkey> [<yhkey> [<copyall> [<clobber>
               ]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
     
       extractor filename=<filename> [eventsout=<eventsout>] [imgfile=<imgfile>]
               [binf=<binf>] [fullimage=<fullimage>] [phafile=<phafile>]
               [specbin=<specbin>] [wtmapb=<wtmapb>] [wtmapfix=<wtmapfix>]
               [swapx=<swapx>] [swapy=<swapy>] [binh=<binh>] [wmapver=<wmapver>]
               [fitsbinlc=<fitsbinlc>] [qdpfile=<qdpfile>] [binlc=<binlc>]
               [lcthresh=<lcthresh>] [lcthwarn=<lcthwarn>] [lcstart=<lcstart>]
               [lctzero=<lctzero>] [unbinlc=<unbinlc>] [regionfile=<regionfile>]
               [timefile=<timefile>] [adjustgti=<adjustgti>] [gtinam=<gtinam>]
               [xcolf=<xcolf>] [ycolf=<ycolf>] [zcolf=<zcolf>] [xint=<xint>]
               [yint=<yint>] [tcol=<tcol>] [ecol=<ecol>] [stokes=<stokes>]
               [polwcol=<polwcol] [ccol=<ccol>] [gcol=<gcol>] [gstring=<gstring>]
               [xcolh=<xcolh>] [ycolh=<ycolh>] [gtitxt=<gtitxt>] [xronwn=<xronwn>]
               [events=<events>] [gti=<gti>] [timeorder=<timeorder>]
               [timeref=<timeref>] [tpixrpar=<tpixrpar>] [usetpixrsel=<usetpixrsel>]
               [eventkey=<eventkey>] [phamax=<phamax>] [xfkey=<xfkey>]
               [yfkey=<yfkey>] [xhkey=<xhkey>] [yhkey=<yhkey>] [copyall=<copyall>]
               [clobber=<clobber>]
     

DESCRIPTION

EXTRACTOR produces event, image, spectrum, and/or lightcurve files from a set of input event files. The input events can be filtered on selected regions, time intervals, phase bins, or within some interval based on any integer event attribute (such as PHA or PI). EXTRACTOR is used by XSELECT when the extract command is given.

Spatial filtering is performed using region files. These are ascii files containing one region per line. If a region is to be excluded then it is prefixed with a minus sign. If the first region is an exclusion region then the entire image is first included. The valid regions are POINT(X,Y), CIRCLE(X,Y,Radius), ELLIPSE(X,Y,Radius_1,Radius_2,Rotation), ANNULUS(X,Y, Inner_radius,Outer_radius), (ROT)BOX(X,Y,Side_1,Side_2,Rotation), RECTANGLE(X_min,Y_min,X_max,Y_max), POLYGON(X_vertex_1,Y_vertex_1,...,X_vertex_N,Y_vertex_N), PIE(X,Y,Radius_1,Radius_2,Angle_1,Angle_2). A region extension describing the selection is appended to the output file.

Time filtering is performed using good time intervals. The good time intervals from all the input files are ORed together and then these are ANDed with the good time intervals from the input event files. For detectors such as CCDs which provide a time for each frame the time selection is performed based on the center time of the frame. It is best to use GTIs which match exactly to complete frames (ie the start of the GTI is the start time of some frame and the end of the GTI is the end time of a frame). If this is not possible then the adjustgti boolean parameter can be used to set the output GTIs so this criterion is met.

The grade (or pattern) can be filtered using a combination of single grades (eg 0), ranges (eg 2-6), upper limits (eg < 3), and lower limits (eg > 4). Multiple specifications should be separated by commas (eg 0,2).

If the zcolf parameter is set then each pixel in the output image will be the mean value of that column for all events in the pixel. The two axes of the image can be any two columns of the event list. If an axis is for a real event attribute then the xint or yint parameter should be set to define the image pixel size.

When extracting event files only the events and GTI extensions are written out unless the copyall parameter is set to true. If copyall=yes then the extra extensions will be copied from the input file to the end of the output file. If multiple input files are specified then only the extra extensions from the first file will be copied.

PARAMETERS

filename [string]

The input event filename. If this starts with "@" then it is assumed to be an ascii file containing a list of event files to be read. Interval filters can be specified by appending them inside [] on the end of this parameter. For instance, to accept only events with PHA lying between 7 and 30 the filename will be specified by "infile.evt[pha=7:30]". If a list of filenames is given (using "@") then the interval filtering should be specified on the input paramater, not on the individual event filenames. Successive interval filters should be separated by spaces or commas.

eventsout [string]

The name for any output events file.

imgfile [string]

The name for any output image file. The image is constructed from the event attributes given by the extractor parameters xcolf and ycolf.

binf [int]

The factor by which the event coordinates will be binned to make the image.

fullimage [bool]

If yes then output image is full-size. If no then the output image is the bounding box around the selected region.

phafile [string]

The name for any output spectrum file. The spectrum is constructed from the event attribute given by the extractor parameter ecol. If the wtmapb parameter is set to true then a wmap will be written as the primary array in the output spectrum file. This map is constructed from the event attributes given by the extractor parameters xcolh and ycolh binned by a factor binh.

specbin [int]

Binning factor for the spectrum.

wtmapb [bool]

If yes then a WMAP will be written as the primary array in phafile. This WMAP is constructed from the event attributes given by the extractor parameters xcolh and ycolh binned by a factor binh.

wtmapfix [bool]

If yes then all WMAP pixels outside the selected region are st to -1. If no then they are set to 0.

swmapx [bool]

If yes then invert the X-axis when converting WMAP to IMAGE coordinates.

swmapy [bool]

If yes then invert the Y-axis when converting WMAP to IMAGE coordinates.

binh [int]

The factor by which the event coordinates will be binned to make the WMAP.

wmapver [int]

If 1 then the old-style HDUVERS=1 WMAP will be written. If 2 then the newer HDUVERS=2 format will be used (this version is consistent with CIAO).

fitsbinlc [string]

The name for any FITS format binned light curve. The binsize is given by the parameter binlc.

qdpfile [string]

The name for any QDP format binned light curve (deprecated). The binsize is given by the parameter binlc.

binlc [double]

The binsize used to construct light curves.

lcthresh [double]

When constructing a lightcurve any bins whose exposure is less than lcthresh times the binsize are ignored. This removes bins at the edges of the good time intervals.

lcthwarn [double]

If a lightcurve bin is ignored due to lcthresh and the number of counts in the bin exceeds lcthwarn times the average then a warning is written.

lcstart [double]

The start time of the lightcurve in the same units as the GTI.

lctzero [bool]

If yes then the lightcurve times will be relative to that of the start bin. If no then the lightcurve times will be in spacecraft units.

unbinlc [string]

The name for any output unbinned light curve. This is simply an ascii list of events with time and the contents of ecol for each event.

regionfile [string]

Any region file used for spatial filtering. The region coordinates are assumed to be xcolf and ycolf binned by binf.

timefile [string]

Any file used for time filtering. This can be either a single time filter file or an ascii file listing other time filter files. In the latter case the filename should be prefixed by "@". Time filter files can be either FITS files containing GTI extensions, Xronos window files, or ascii files containing a column of start and stop times in units of the tcol column. Note that for CCD detectors time filters should ideally be lined up with readouts ie a time filter should start at the beginning of a frame and end at the end of a frame.

adjustgti [bool]

If yes then the output GTIs will be adjusted to match to frame boundaries (useful for detectors such as CCDs with large TIMEDEL values).

gtinam [string]

If a FITS file is used for time filtering then gtinam specifies the name of the extension containing the list of good time intervals.

xcolf [string]

The name of the column used for the X coordinate when region filtering and constructing the output image.

ycolf [string]

The name of the column used for the Y coordinate when region filtering and constructing the output image.

zcolf [string]

The name of the column used for constructing the output image. The value in each pixel of the output image will be the mean of the zcolf column for all events in the pixel.

xint [double]

Digitization used for the X-axis of an image. This will define the pixel size in the output image. Should be used when making an image using real event attributes for the axes.

yint [double]

Digitization used for the Y-axis of an image. This will define the pixel size in the output image. Should be used when making an image using real event attributes for the axes.

tcol [string]

The name of the column used for the time of the event.

ecol [string]

The name of the column used for constructing the output spectrum.

stokes [string]

For spectropolarimetric data choose whether to output the Stokes parameter products. If NONE then do not, if NEFF or SIMPLE then use the weighting column defined by polwcol, and if UNWEIGHTED then do not use the weighting column. In this last case the I Stokes parameter product is the same as that if NONE had been chosen. NEFF is the Baldini et al. 2203.06385 weighting scheme and SIMPLE is that from Kislat et al. 1409.6214.

polwcol [string]

The name of the column containing the polarization weights.

ccol [string]

The name of the column used to index the GTIs. In most cases this is the CCD ID.

gcol [string]

The name of the column used for the GRADE or PATTERN.

gstring [string]

The filter string for the GRADE or PATTERN. The grade (or pattern) can be filtered using a combination of single grades (eg 0), ranges (eg 2-6), upper limits (eg < 3), and lower limits (eg > 4). Multiple specifications should be separated by commas (eg 0,2).

xcolh [string]

The name of the column used for the X coordinate when constructing the WMAP for the output spectrum.

ycolh [string]

The name of the column used for the Y coordinate when constructing the WMAP for the output spectrum.

gtitxt [string]

The name for any output ascii file listing the final good time intervals after all time filtering.

xronwn [string]

The name for any output xronos window file listing the final good time intervals after all time filtering.

events [string]

The name of the extension containing the events in the input event files.

gti [string]

The name of the extension containing the good time intervals in the input event files.

timeorder [bool]

If the input events are time-ordered then set true.

timeref [double]

TJD time 0 in MJD for the output files.

tpixrpar [double]

Value of TIMEPIXR to use if the keyword is not in the event file.

usetpixrsel [bool]

Value of TIMEPIXR to use if the keyword is not in the event file.

eventkey [string]

The name of a file listing all keywords that should not be copied from the input event file to the output event file.

phamax [string]

The keyword specifying the maximum for the ecol column. If a TLMAX keyword is present then phamax does not have to be set (and if set will be ignored)

xfkey [string]

The keyword specifying the maximum for the xcolf column. If a TLMAX keyword is present then xfkey does not have to be set (and if set will be ignored)

yfkey [string]

The keyword specifying the maximum for the ycolf column. If a TLMAX keyword is present then yfkey does not have to be set (and if set will be ignored)

xhkey [string]

The keyword specifying the maximum for the xcolh column. If a TLMAX keyword is present then xhkey does not have to be set (and if set will be ignored)

yhkey [string]

The keyword specifying the maximum for the ycolh column. If a TLMAX keyword is present then yhkey does not have to be set (and if set will be ignored)

copyall [bool]

If true then copy extra extensions from the input event file to the output event file.

clobber [bool]

If true then any existing output files will be overwritten.

CATEGORY