NAME gtselect - Performs selection cuts on event data files. USAGE gtselect infile outfile ra dec rad tmin tmax emin emax zmax DESCRIPTION gtselect creates a filtered FITS file of selected 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). 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. - The event classification have been re-evaluated in pass 7 series to properly deal with known on-orbit effects, making use of the abundance of real events collected in the first 2 years of LAT operation. In pass 6 the event classes were defined hierarchically (higher probability photon selections are subsets of the less restrictive selections and have smaller effective areas, narrower point spread functions (PSF), and lower fractions of background counts). A single integer to specify the event class was used. In pass 7 series each selection sets a different bit in the EVENT_CLASS variable. In that way, 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 UltraClean ) are still hierarchical, i.e., Transient > Source > Clean > UltraClean. Most analyses will use either the Source or Clean event samples. For gamma-ray burst (GRB) analysis, the user will prefer to select Transient, S2 (extremely loose cuts), or S3 (very loose cuts). Table of standard (non-transient) event classes ------------------------------------------------------------------------- Class (Pass 7 Series)| EVENT_CLASS | Class (Pass 6) | old EVENT_CLASS cut ------------------------------------------------------------------------- Source | 2 | Diffuse | EVENT_CLASS >= 3 Clean | 3 | DataClean | EVENT_CLASS >= 4 UltraClean | 4 | None | None ------------------------------------------------------------------------- Comments: The correlation between the classification in Pass 6 and 7 is tentative The pass 6 cut are discontinued for any data reprocessed after August 1, 2011. Table of transient and extended event classes ------------------------------------------------------------------------- Class (Pass 7 Series)| EVENT_CLASS | Class (Pass 6) | old EVENT_CLASS cut ------------------------------------------------------------------------- Transient | 0 | Transient | EVENT_CLASS >= 1 S2 | 8 | None | None NoCal | 9 | None | None S3 | 10 | None | None CalOnly | 11 | None | None S3NoCal | 12 | S2 (handmade) | Special S3 Cuts S2NoCal | 13 | S3 (handmade) | Special S2 Cuts LLE | 14 | None | None LLESSDVeto | 15 | None | None ------------------------------------------------------------------------- Comments: Note that all of the extended class bits include all the events in the transient class. - The EVENT_CLASS column is not a "bit column" in the ft1 files, so bitwise operations are not supported. However, the modulus operation is supported. For users who wish to use the FTOOLS fselect to select data, an example on how to use it correctly is given: To skim out the "Clean" class events the fselect syntax is fselect someFile_ft1.fits someFile_clean_ft1.fits "EVENT_CLASS % 16 >= 8" 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. 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 7 reprocessed data. The default is 2 (source class). Other values are 0 for transient data, 3 for the clean data class and 4 for the ultraclean data class. 1 is currently unused. (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/p7rep/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 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=2 tmin=220838400 tmax=225590400 \ emin=100 emax=100000 zmax=105 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=2 tmin=INDEF tmax=INDEF emin=100 \ emax=100000 zmax=105 KNOWN BUGS Use the INDEF values for right ascension, declination, and radius are handled peculiarly. SEE ALSO fselect gtobssim gtpphase gtrspgen