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
Mar22 ftools.heasarc