NAME gtpspec - Searches for pulsations in wide frequency range using the Discrete Fast Fourier Transfer (FFT) technique. USAGE gtpspec evfile scfile psrdbfile psrname outfile binwidth numbins timeorigin usertime userformat usersys ra dec ephstyle f1f0ratio f2f0ratio p1p0ratio p2p0ratio DESCRIPTION This tool searches for pulsations in a relatively wide range of frequencies. It uses the Discrete Fast Fourier Transfer (FFT) technique to compute power spectrum density. This tool is suitable for a so-called blind period search, in which data are examined for pulsations at any frequency. Ephemeris information can be given in one of the following forms: 1) manually input the source (pulsar) location (for the barycentric correction), pulse frequency or period, and related information, and 2) automatically extracted from a pulsar ephemerides database, available online. If necessary, this tool reads the spacecraft orbit file and performs the barycentric correction, the p-dot cancellation, and the binary demodulation to each photon arrival time on the fly. PARAMETERS evfile [file name] Name of input event file, FT1 format or equivalent. scfile [file name] Name of input spacecraft data file, FT2 format or equivalent. psrdbfile [file name] Name of pulsar ephemerides database file, in Fermi (formerly GLAST) D4 FITS format (See PULSAR EPHEMERIS DATABASE FILE). Multiple files may be combined by listing them in a text file, one per line, and supplying the list file name preceded by an @ sign. If psrdbfile is NONE (case-insensitive), no ephemeris is loaded from a file. psrname = ANY [string] Name of the pulsar, used to select only ephemerides valid for a particular pulsar. outfile [file name] Name of output FITS file that contains a search result. If outfile is NONE, no FITS output will be created. binwidth = 1.e-2 [double] Width of time bins in seconds to be used to internally create a binned light curve which will be passed to the Fast Fourier Transform (FFT) algorithm. The product of binwidth and numbins will be the length of data to be transformed at once. numbins = 1000000 [integer] Number of time bins to be used to internally create a binned light curve which will be passed to the Fast Fourier Transform (FFT) algorithm. The product of binwidth and numbins will be the length of data to be transformed at once. timeorigin = MIDDLE [enumerated string (START|STOP|MIDDLE|USER)] Origin of time for the periodicity test. If START or STOP is chosen, the start or stop time is taken from the input event file(s) and used as the time origin. If MIDDLE is chosen, the mid-time between START and STOP is used. If USER is chosen, user will supply explicitly using usertime, userformat and usersys parameters. usertime = 0. [string] User-specified time origin for the periodicity test, used only if timeorigin parameter is USER. userformat = FILE [enumerated string (FILE|MJD|FERMI|GLAST)] String describing the representation used for the usertime. If FILE is chosen, the time format specified in the input event file header will be used. Used only if timeorigin parameter is USER. usersys = FILE [enumerated string (FILE|TAI|TDB|TT|UTC)] String describing the time system used for the usertime. If FILE is chosen, the time system specified in the input event file header (TIMESYS keyword) will be used. Used only if timeorigin parameter is USER. ra [double] Right Ascension of point source in degrees for which to perform the barycentric correction. dec [double] Declination of point source in degrees for which to perform the barycentric correction. ephstyle = FREQ [enumerated string (FREQ|PER)] Method to specify how the ephemeris for pdot cancellation will be supplied. If ephstyle is FREQ, the user will supply values for the frequency and its derivatives at the time given by the epoch parameter. If ephstyle if PER, the user will supply values for the period and its derivatives at the time given by the epoch parameter. f1f0ratio = 0. [double] Ratio of frequency first time derivative to frequency at the time given by the timeorigin parameter in the units of s^(-1). This parameter only has effect if ephstyle is FREQ. Note that pdot cancellation will be performed in TDB time system unless tcorrect is NONE. f2f0ratio = 0. [double] Ratio of frequency second time derivative to frequency at the time given by the timeorigin parameter in the units of s^(-2). This parameter only has effect if ephstyle is FREQ. Note that pdot cancellation will be performed in TDB time system unless tcorrect is NONE. p1p0ratio = 0. [double] Ratio of period first time derivative to period at the time given by the timeorigin parameter in the units of s^(-1). This parameter only has effect if ephstyle is PER. Note that pdot cancellation will be performed in TDB time system unless tcorrect is NONE. p2p0ratio = 0. [double] Ratio of period second time derivative to period at the time given by the timeorigin parameter in the units of s^(-2). This parameter only has effect if ephstyle is PER. Note that pdot cancellation will be performed in TDB time system unless tcorrect is NONE. (tcorrect = AUTO) [enumerated string (NONE|AUTO|BARY|BIN|PDOT|ALL)] Set of arrival time corrections to apply. If tcorrect is NONE, no corrections will be applied. If tcorrect is BARY, only the barycentric correction will be applied. If tcorrect is BIN, an appropriate orbital ephemeris is searched for in the pulsar database, and if found, binary demodulation will be applied after the barycentric correction, and if not, an error will be generated. If tcorrect is PDOT, an appropriate spin ephemeris is searched for in the pulsar database, and if found, pdot cancellation will be applied after the barycentric correction, and if not, an error will be generated. If tcorrect is ALL, both actions for the BIN option and the PDOT option will be taken. If tcorrect is AUTO, the barycentric correction will be applied, and the binary demodulation will be applied only when an orbital ephemeris is available in the pulsar database, then the pdot cancellation will applied only when a spin ephemeris is available in the pulsar database. (solareph = JPL DE405) [enumerated string (JPL DE200|JPL DE405)] Solar system ephemeris for the barycentric correction. (matchsolareph = ALL) [enumerated string (NONE|EVENT|PSRDB|ALL)] String that controls whether to use the name of the solar system ephemeris given by the solareph parameter to check the input event data file and to select ephemerides in the pulsar database. If matchsolareph is EVENT, all the input event files are required to use the same solar system ephemeris for the barycentric correction as the one given by the solareph parameter, and an error will be generated if otherwise. Such an error may occur when an input event data file has already been applied the barycentric correction with a different solar system ephemeris. If matchsolareph is PSRDB, the string given by the solareph parameter is used to select the ephemerides. If matchsolareph is ALL, both actions for the EVENT option and the PSRDB option will be taken. If matchsolareph is NONE, no selection will be performed. (angtol = 1.e-8) [double] Angular tolerance in degrees in comparison of two source positions, one for which the barycentric correction is performed, and another given by RA_NOM and DEC_NOM header keyword of an event file to which the barycentric correction has already been applied. This parameter only has effect if the barycentric correction has been applied to an input event data file. If the two source positions are separate from each other by this amount or less, then they will be considered to be the same position. Otherwise an error will be generated. The sign of the parameter value is ignored. For example, setting angtol=-1.0 results in giving angular tolerance of 1 degree. (evtable = EVENTS) [string] Name of the FITS table containing the event data. (timefield = TIME) [string] Name of the field containing the time values for temporal analysis. (sctable = SC_DATA) [string] Name of the FITS table containing the spacecraft data. (lowfcut = .01) [double] Low frequency cut-off for chance probability computation. This parameter may be used to avoid the frequency range that is severely affected by artifacts such as data gaps due to the orbital motion of the spacecraft. (plot = yes) [bool] If plot is yes, the result will be displayed in a separate plot window, as well as the numerical results will be output in a text screen. If plot is no, only the text output will be displayed, and no plot window will be displayed. (title = DEFAULT) [string] Title for the graph. By default a title indicating the type of test and other pertinent information will be displayed. (leapsecfile = DEFAULT) [file name] Name of the file containing the name of the leap second table, in OGIP-compliant leap second table format. If leapsecfile is the string DEFAULT, the default leap-second file (leapsec.fits), which is distributed with the extFiles package, will be used. (reportephstatus = yes) [bool] If reportephstatus is yes, the application will examine the input pulsar ephemeris database, and report findings which may affect the requested ephemeris computations. If reportephstatus is no, it will not report any ephemeris status. (chatter = 2) [integer, min=0, max=4] This parameter fixes the output verbosity: no screen output (0), nominal screen output (2), maximum verbosity (4). (clobber = yes) [boolean] Overwrite or do not overwrite existing output files. (debug = no) [boolean] Activate debugging mode. 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 = no) [boolean] Graphical user Interface (GUI) mode activated if "yes" is specified. (mode = ql) [string] Mode of automatic parameters. EXAMPLES The example below shows how to perform a pulsation search in the simplest case, where one can assume no significant frequency variations exist throughout the observation. The time origin of this search is taken to be the center of the observation. That means, if a pulsation is found, the pulse frequency should be interpreted as measured at the center of the observation (i.e., the time origin). > gtpspec evfile=fakepulsar_event.fits \ scfile=simscdata_1week.fits \ psrdbfile=bogus_pulsardb.fits psrname="PSR J9999+9999" \ outfile=gtpspec_example_1.fits binwidth=0.01 numbins=1000000 \ timeorigin=MIDDLE ra=111.11 dec=22.22 ephstyle=FREQ \ f1f0ratio=0.0 f2f0ratio=0.0 This command produces an output message that describes the search criteria and explains the search result. A plot will also be produced. PULSAR EPHEMERIS DATABASE FILE A pulsar ephemeris database file is a FITS file or a text file in a Fermi-specific format, and contains a set of pulsar ephemerides to be used in a temporal analysis of Fermi data. When so specified, the pulsar analysis tools in Fermi Science Tools load pulsar ephemerides from pulsar ephemeris database files, and use them in their tasks. A pulsar ephemeris database file can be created, filtered, and combined by the gtpulsardb tool. Also, pulsar ephemerides for the Fermi LAT pulsars and timing models associated with various Fermi publications are available at the following web page. http://fermi.gsfc.nasa.gov/ssc/data/p7rep/access/lat/ephems/ KNOWN BUGS When running gtpsearch multiple times using the GUI, plot windows from previous runs reappear after they are closed manually. Thus, there is no way to permanently close plot windows without exiting the GUI. SEE ALSO gtpsearch, gtptest, gtpulsardb