NAME

    gtpsearch - Searches for pulsations at frequencies near to a
                known, guessed or estimated reference frequency.

USAGE
    
    gtpsearch evfile scfile psrdbfile psrname outfile algorithm numphase
              numharm maxharm scanstep numtrials timeorigin usertime
	      userformat usersys ephstyle ephepoch timeformat timesys
	      ra dec f0 f1 f2 p0 p1 p2

DESCRIPTION

    This tool searches for pulsations in data which is known or
    suspected to have a pulsation of a known approximate period or
    frequency.  It is not useful for a so-called blind period search,
    in which data are examined for pulsations at any frequency.  The
    tool supports several test statistics available, including
    Chi-squared (X2), Z-squared-n ( Z2N), H, and Rayleigh (Z2N with N
    == 1).  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.

algorithm = CHI2 [enumerated string (CHI2|Z2N|H)]
    Type of search algorithm to use.  Current valid choices are CHI2
    (for the chi-squared test), Z2N (the Z2n/Rayleigh test), or H
    (the H test). The Rayleigh test may be obtained by choosing Z2N
    here and setting the number of harmonics used for each trial (the
    numharm parameter) to 1.

numphase = 10 [integer]
    Number of phase bins in each trial for the chi-squared test. 
    This parameter only has effect if algorithm is CHI2.

numharm = 10 [integer]
    Number of harmonics in each trial for the Z2n/Rayleigh test. 
    This parameter only has effect if algorithm is Z2N.  For the
    Rayleigh test, set algorithm to Z2N, and set numharm to 1.

maxharm = 10 [integer]
    Maximum number of harmonics in each trial for the H test.  This
    parameter only has effect if algorithm is H.

scanstep = 0.5 [double]
    Size of steps for trials, in units of the Fourier resolution.

numtrials = 100 [integer]
    Number of separate trials to perform. The larger this number, the
    wider the search around the central frequency.

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.

ephstyle = DB [enumerated string (DB|FREQ|PER)]
    Method to specify how the ephemerides will be supplied. If
    ephstyle is DB, a pulsar database file in Fermi (formerly GLAST)
    D4 FITS format will be used. If ephstyle is FREQ (PER), the user
    will supply values for the frequency (period) and its derivatives
    at the time given by the epoch parameter.

ephepoch = 0. [string]
    Reference epoch of the ephemeris that will be manually specified.
    This parameter only has effect if ephstyle is FREQ or PER.

timeformat = FILE [enumerated string (FILE|MJD|FERMI|GLAST)]
    String describing the representation used for ephepoch parameter.
    If FILE is chosen, the time format specified in the input event
    file header will be used.

timesys = FILE [enumerated string (FILE|TAI|TDB|TT|UTC)]
    String describing the time system used for ephepoch parameter and
    the following ephemeris parameters: f0, f1, f2, p0, p1, and p2.
    In other words, ephemeris computations with those parameters will
    be performed in the time system specified by this parameter.  If
    FILE is chosen, the time system specified in the input event file
    header (TIMESYS keyword) will be used.

ra [double]
    Right Ascension of point source in degrees for which to perform
    the barycentric correction.  This parameter only has effect if
    ephstyle is FREQ or PER.

dec [double]
    Declination of point source in degrees for which to perform the
    barycentric correction.  This parameter only has effect if
    ephstyle is FREQ or PER.

f0 = 1. [double]
    Value of the frequency at the time given by the epoch parameter
    in the units of s^(-1).  This parameter only has effect if
    ephstyle is FREQ.  Note that ephemeris computations using this
    parameter as will be performed in the time system specified by
    timesys parameter.

f1 = 0. [double]
    Value of the first time derivative of the frequency at the time
    given by the epoch parameter in the units of s^(-2).  This
    parameter only has effect if ephstyle is FREQ.  Note that
    ephemeris computations using this parameter will be performed in
    the time system specified by timesys parameter.

f2 = 0. [double]
    Value of the second time derivative of the frequency at the time
    given by the epoch parameter in the units of s^(-3).  This
    parameter only has effect if ephstyle is FREQ.  Note that
    ephemeris computations using this parameter will be performed in
    the time system specified by timesys parameter.

p0 = 1. [double]
    Value of the period at the time given by the epoch parameter in
    seconds.  This parameter only has effect if ephstyle is PER. 
    Note that ephemeris computations using this parameter will be
    performed in the time system specified by timesys parameter.

p1 = 0. [double]
    Value of the first time derivative of the period at the time
    given by the epoch parameter (dimension-less).  This parameter
    only has effect if ephstyle is PER.  Note that ephemeris
    computations using this parameter will be performed in the time
    system specified by timesys parameter.

p2 = 0. [double]
    Value of the second time derivative of the period at the time
    given by the epoch parameter in the units of s^(-1).  This
    parameter only has effect if ephstyle is PER.  Note that
    ephemeris computations using this parameter will be performed in
    the time system specified by timesys parameter.

(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.

(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

    Performing a period search is straight forward if the object of
    interest is listed in a pulsar ephemerides database file. The
    example below shows how to perform the test under these
    circumstances using the files described above. The time origin of
    periodicity test 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).

        > gtpsearch evfile=fakepulsar_event.fits scfile=simscdata_1week.fits \
            psrdbfile=bogus_pulsardb.fits psrname="PSR J9999+9999" \
            outfile=gtpsearch_example_1.fits algorithm=Chi2 numphase=10 \
            scanstep=0.5 numtrials=800 timeorigin=MIDDLE ephstyle=DB

    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/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

    gtpspec, gtptest, gtpulsardb
