.help extractor Feb05 ftools.heasarc
.h
NAME
EXTRACTOR -- Extracts products from input events files
.ih
USAGE
extractor <filename> [<eventsout> [<imgfile> [<binf> [<phafile>
          [<specbin> [<wtmapb> [<binh> [<wmapver> [<fitsbinlc> [<qdpfile> 
          [<binlc> [<lcthresh> [<lcthwarn> [<lctzero] [<unbinlc> [<regionfile> 
          [<timefile> [<gtinam> [<xcolf> [<ycolf> [<zcolf> [<xint> [<yint> 
          [<tcol> [<ecol> [<ccol> [<gcol> [<gstring> [<xcolh> [<ycolh> 
          [<gtitxt> [<xronwn> [<events> [<gti> [<timeorder> [<timeref> 
          [<eventkey> [<phamax> [<xfkey> [<yfkey> [<xhkey> [<yhkey> 
          [<copyall> [<clobber>
          ]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]

extractor filename=<filename> [eventsout=<eventsout>] [imgfile=<imgfile>] 
          [binf=<binf>] [phafile=<phafile>] [specbin=<specbin>] 
          [wtmapb=<wtmapb>] [binh=<binh>] [wmapver=<wmapver>] 
          [fitsbinlc=<fitsbinlc>] [qdpfile=<qdpfile>] [binlc=<binlc>] 
          [lcthresh=<lcthresh>] [lcthwarn=<lcthwarn>] [lctzero=<lctzero>] 
          [unbinlc=<unbinlc>] [regionfile=<regionfile>] [timefile=<timefile>] 
          [gtinam=<gtinam>] [xcolf=<xcolf>] [ycolf=<ycolf>] [zcolf=<zcolf>] 
          [xint=<xint>] [yint=<yint>] [tcol=<tcol>] [ecol=<ecol>] [ccol=<ccol>] 
	  [gcol=<gcol>] [gstring=<gstring>] 
          [xcolh=<xcolh>] [ycolh=<ycolh>] [gtitxt=<gtitxt>] [xronwn=<xronwn>]
          [events=<events>] [gti=<gti>] [timeorder=<timeorder>] 
          [timeref=<timeref>] [eventkey=<eventkey>] [phamax=<phamax>] 
          [xfkey=<xfkey>] [yfkey=<yfkey>] [xhkey=<xhkey>] [yhkey=<yhkey>] 
          [copyall=<copyall>] [clobber=<clobber>]
.ih
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.

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.

.ih
PARAMETERS
.ls 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.
.le
.ls eventsout [string]
The name for any output events file.
.le
.ls 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.
.le
.ls binf [int]
The factor by which the event coordinates will be binned to make the image.
.le
.ls 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. 
.le
.ls specbin [int]
Binning factor for the spectrum.
.le
.ls 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. 
.le
.ls binh [int]
The factor by which the event coordinates will be binned to make the WMAP.
.le
.ls 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).
.le
.ls fitsbinlc [string]
The name for any FITS format binned light curve. The binsize is given by
the parameter binlc.
.le
.ls qdpfile [string]
The name for any QDP format binned light curve (deprecated). The binsize is 
given by the parameter binlc.
.le
.ls binlc [double]
The binsize used to construct light curves.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls regionfile [string]
Any region file used for spatial filtering. The region coordinates are assumed
to be xcolf and ycolf binned by binf.
.le
.ls 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.
.le
.ls 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.
.le
.ls xcolf [string]
The name of the column used for the X coordinate when region filtering
and constructing the output image.
.le
.ls ycolf [string]
The name of the column used for the Y coordinate when region filtering
and constructing the output image.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls tcol [string]
The name of the column used for the time of the event.
.le
.ls ecol [string]
The name of the column used for constructing the output spectrum.
.le
.ls ccol [string]
The name of the column used to index the GTIs. In most cases this is the
CCD ID.
.le
.ls gcol [string]
The name of the column used for the GRADE or PATTERN.
.le
.ls 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).
.le
.ls xcolh [string]
The name of the column used for the X coordinate when constructing the 
WMAP for the output spectrum.
.le
.ls ycolh [string]
The name of the column used for the Y coordinate when constructing the 
WMAP for the output spectrum.
.le
.ls gtitxt [string]
The name for any output ascii file listing the final good time intervals
after all time filtering.
.le
.ls xronwn [string]
The name for any output xronos window file listing the final good time 
intervals after all time filtering.
.le
.ls events [string]
The name of the extension containing the events in the input event files.
.le
.ls gti [string]
The name of the extension containing the good time intervals in the input 
event files.
.le
.ls timeorder [bool]
If the input events are time-ordered then set true.
.le
.ls timeref [double]
TJD time 0 in MJD for the output files.
.le
.ls 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.
.le
.ls 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)
.le
.ls 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)
.le
.ls 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)
.le
.ls 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)
.le
.ls 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)
.le
.ls copyall [bool]
If true then copy extra extensions from the input event file to the output
event file.
.le
.ls clobber [bool]
If true then any existing output files will be overwritten.
.le

.endhelp





