NAME gtselect - Performs selection cuts on event data files. USAGE gtselect infile outfile ra dec rad tmin tmax emin emax zmin zmax evclass evtype DESCRIPTION gtselect creates a filtered FITS file by selecting rows from an input event data file based on user-specified cuts that are applied to each row of the input file. This application enables detailed selections to be made on Fermi photon and event data obtained from the FSSC data server or simulated data generated using gtobssim (see gtobssim help). The most common selections are these involving time range (minimum and maximum time) and energy range (minimum and maximum energy), and event class. For each cut that is applied Data Subspace (DSS) keywords are written to the EVENTS header of the output FITS file that describe the selection. This information is used by the likelihood tools and gtrspgen for computing exposure-related information. NOTES - The selection cone center (right ascension and declination) must match exactly that which was used in the original selection from the data server. - both evclass and evtype are "hidden" parameters, i.e. they are not propmted for but must be supplied on the command line - evclass, recommended selection for standard analysis = 128 (source) The event classification system in Pass 8 is similar to that employed in Pass 7 (i.e. a bitmask classification system for various event classes), Additionally, through the use of the new data filter EVENT_TYPE (see below), further subselection of events are allowed in data preparation. Each bit in the EVENT_CLASS variable corresponds to a particular set of the Instrument Response Functions (IRFs). The more used event classes (Transient, Source, Clean and UltraCleanVeto ) are still hierarchical, i.e., Transient > Source > Clean > UltraCleanVeto. Most analyses will use either the Source or Clean event samples. **NOTE** once you perform selection on event class or event type, you cannot revert to a more general selection at a later stage of your analysis. Table of standard (non-transient) event classes (for a complete list see the FSSC Website or Cicerone) ----------------------------------------- |Class (Pass 8)| evclass |---------------------------------------- |Source | 128 | |Clean | 256 | |UltraCleanVeto| 1024 | ----------------------------------------- - evtype, recommended selection for standard analysis = 3 (front + back events) The Pass 8 processing implements a new scheme for partitioning the data within an event class with "event type" selections. The event type selections partition the data within a class into independent subsets. Currently, evtype has the ability to select on 2 different types of event conversions (front/back), 4 different PSF classes, and 4 different energy reconstruction classes. You may select a sub-sample within a given event type (e.g. PSF2), but those events can only be used with other events of the same type. If you select one of the "all events" values (3 = front+back, 60 = PSF0+PSF1+PSF2+PSF3, 960 = EDISP0+EDISP1+EDISP2+EDISP3). be aware that different IRFs will be applied. If you do not select an "all events" value, then the tool may apply results only to a subset of the events. PARAMETERS infile [filename] Input event FITS file. This is the file containing the event data. outfile [filename] Output event FITS file with events that satisfy the selections performed with gtselect. ra [double] Right ascension of acceptance cone (J2000) in decimal degrees. If the parameter is set to INDEF the right ascension will be read from the header of the input file. dec [double] Declination of acceptance cone (J2000) in decimal degrees. If the parameter is set to INDEF the declination will be read from the header of the input file. rad [double] Radius of acceptance cone (decimal degrees). A value of 180 (default) indicates that no acceptance cone cut will be applied. If the parameter is set to INDEF the radius will be read from the header of the input file. tmin [double] Event arrival time lower limit in mission elapsed time (MET) seconds. All the events in the output FITS file will have "event arrival time" larger than this value. The reference time used for MET is midnight (0h:0m:0s) on January 1, 2001, in Coordinated Universal Time (UTC). The Fermi convention is that MJDREF=51910 (UTC)=51910.0007428703703703703 (TT); the fractional part of MJDREF in the TT system compensates for the use of midnight in the UTC system as the reference time. MJDREF is divided into two keywords: MJDREFI=51910, the integer part; and MJDREFF=7.428703703703703D-4, the fractional part. If the parameter is set to INDEF (default) tmin will be read from the header of the input file. For conversions between MET and other commonly used time conventions we refer the user to the HEASARC online tool http://heasarc.gsfc.nasa.gov/cgi-bin/Tools/xTime/xTime.pl. tmax [double] Event arrival time upper limit in mission elapsed time (MET) seconds. All the events in the output FITS file will have "event arrival time" smaller than this value. A value of zero in this context means that no upper limit will be applied. If the parameter is set to INDEF (default) the tmax will be read from the header of the input file. emin [double] Minimum event energy in MeV. All the events in the output FITS file will have "event energy" larger than this value. Default is "100" MeV. emax [double] Maximum event energy in MeV. All the events in the output FITS file will have "event energy" smaller than this value. Default is "300000" MeV. zmax [double] Maximum apparent zenith angle (degrees). It ranges from 0 to 180 (default). (evclsmin) [integer] This parameter is ignored for data reprocessed after Aug. 1, 2011 (Pass 7 series). Mininum event class ID to include. Each set of IRFs will define a set of event classes numbered 0 to n, where n+1 is the number of event classes. These numbers will be ordered such that the more inclusive classes are numbered lowest. Default is "INDEF". (evclsmax) [integer] This parameter is ignored for data reprocessed after Aug. 1, 2011 (Pass 7 series). Maximum event class ID to include. Default is "INDEF". (evclass) [integer] Event class selection for pass 8. The default is 128 (source class). (evtype) [integer] The event type selection for Pass 8 data. The event type is a subselection of the event class. Users can select on range of events based on conversion type (front/back), angular reconstruction quality (PSF values), and energy reconstruction quality (EDISP values). The default value is INDEF, which will not apply a subselection. (convtype) [integer] Conversion type. This parameter screens events based on which portion of the instrument the incident gamma-ray pair conversion event occurred. 0=Front, 1=Back, -1=both (defalt value). Refer to the Cicerone manual for details (http://fermi.gsfc.nasa.gov/ssc/data/analysis/documentation/Cicerone). (phasemin) [double] Minimum pulsar phase to include. This cut is only applied if the PULSE_PHASE column has been added to the FT1 file by the gtpphase tool. Default is "0". (phasemax) [double] Maximum pulsar phase to include. Default is "1". (evtable) [string] Event data extension. Default is "EVENTS". (chatter) [integer] This parameter fixes the output verbosity: no screen output (0), nominal screen output (2), maximum verbosity (4). Default is "2". (clobber) [boolean] If true, an existing file of the same name will be overwritten. Default is "yes". (debug) [boolean] Activate debugging mode. Default is "no". When debug is "no", all exceptions that are not caught and handled by individual tool-specific code are caught by a top-level exception handler that displays information about the exception and then exits. When debug is "yes", such exceptions are not caught by the top level code. Instead the tool produces a segmentation violation, which is more useful for debugging. When debugging mode is enabled, the tool produces more verbose output describing any errors or exceptions that are encountered. (gui) [boolean] Graphical User Interface (GUI) mode is activated if set to "yes". Default is "no". (mode) [string] Mode of automatic parameters: "h" for batch, "ql" for interactive. Default is "ql". EXAMPLES The way that the parameters are passed follows the FTOOLs model. They could be passed by answering from a prompt, as a list in a command line, or by modifying the parameter file. The command line option facilitates calling gtselect from a script. To prompt for gtselect type in the command line: > gtselect This will prompt for parameter values. Not all parameter are prompted: some of them are "hidden". To change one of the "hidden" parameter, the user should specify the values in the command line or modify its mode by editing the parameter file. For example, to prevent overwrite the existing output file, the following command line as to be typed: > gtselect clobber=no This is an example of how to run the tool: In this case the quasar 3C279 (centered on Ra=193.98, Dec=-5.82) was simulated using gtobssim (type "fhelp gtobssim" for further explanation), although the indentical procedure could be followed for actual data. Note that a radius of 40 degrees was specified in the input simulation. The energy for the simulated events ranges between 20 MeV and 200000 MeV. Using gtselect it possible to select the events with energy larger than 100 MeV and within a radius of 20 degrees centered on Ra=193.98, Dec=-5.82 and a time range between 220838400 and 225590400 MET seconds: > gtselect evclass=2 Input FT1 file[] 3C279_events_0000.fits Output FT1 file[] 3c279_filtered.fits RA for new search center (degrees) (0:360) [INDEF] 193.98 Dec for new search center (degrees) (-90:90) [INDEF] -5.82 radius of new search region (degrees) (0:180) [INDEF] 20 start time (MET in s) (0:) [INDEF] 220838400 end time (MET in s) (0:) [INDEF] 225590400 lower energy limit (MeV) (0:) [100] 100 upper energy limit (MeV) (0:) [300000] 100000 maximum zenith angle value (degrees) (0:180) [180] 105 Done. The last example could be also run from the command line as: > gtselect infile=3C279_events_0000.fits outfile=3c279_filtered.fits \ ra=193.98 dec=-5.82 rad=20 evclass=128 evtype=3 \ tmin=220838400 tmax=225590400 emin=100 emax=100000 zmax=100 You can also use the defaults in the input file header by using the INDEF syntax > gtselect infile=3C279_events_0000.fits outfile=3c279_filtered.fits \ ra=INDEF dec=INDEF rad=INDEF evclass=128 evtype=INDEF tmin=INDEF \ tmax=INDEF emin=100 emax=100000 zmax=100 KNOWN BUGS Use the INDEF values for right ascension, declination, and radius are handled peculiarly. If any one of the parameters are set to INDEF it is treated if all are set to INDEF. SEE ALSO fselect gtobssim gtpphase gtrspgen