NAME

    gtpphase - Computes a pulse phase for each event in input event
               file(s), and writes it to a FITS column in the file(s).

USAGE

    gtpphase evfile scfile psrdbfile psrname ephstyle ephepoch timeformat
             timesys ra dec phi0 f0 f1 f2 p0 p1 p2

DESCRIPTION

    This tool operates on input event file(s) to compute a pulse phase
    for a photon arrival time of each event, and writes it to the
    PULSE_PHASE column (by default) of the event file(s).  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 and the binary
    demodulation to each photon arrival time on the fly.

PARAMETERS

    evfile [file name]
        Name of input event file, event file format or equivalent.

    scfile [file name]
        Name of input spacecraft data file, S/C 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.

    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: phi0, f0, f1, f2, p0, p1, and
        p2.  In other words, ephemeris computaions 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.

    phi0 = 0. [double]
        Phase offset at this ephepoch for a user-supplied ephemeris.
        This parameter only has effect if ephstyle is FREQ or PER.  Note
        that ephemeris computations using this parameter will be
        performed in the time system specified by timesys parameter.

    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 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|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 or
        ALL, 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 AUTO, the barycentric
        correction will be applied, then the binary demodulation will be
        applied only when an orbital 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.

    (pphasefield = PULSE_PHASE) [string]
        Name of the output column to contain the assigned pulse phase.

    (pphaseoffset = 0.) [double]
        Global offset applied to all assigned pulse phases. This may be
        used to shift the entire pulse profile. Note that this offset
        will be applied regardless of the source of the ephemeris used,
        whereas phi0 is used only when ephstyle is FREQ or PER.

    (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 simplest way to run the gtpphase tool, which may suffice for
    most applications, is for the tool to extract the information from
    a master pulsar database. The exact process the tool uses for
    choosing ephemerides will be described below.

    > gtpphase evfile=fakepulsar_event.fits scfile=simscdata_1week.fits \
    psrdbfile=bogus_pulsardb.fits psrname="PSR J9999+9999" ephstyle=DB

    Another option is to supply the essential ephemeris information
    manually. For example, this may be useful when an ephemeris is not
    available in a database, but the necessary information is
    available in the literature. In the example shown below, the same
    values which were extracted from the database in the previous
    example were entered manually.

    > gtpphase evfile=fakepulsar_event.fits scfile=simscdata_1week.fits \
    psrdbfile=bogus_pulsardb.fits psrname="PSR J9999+9999" \
    ephstyle=FREQ ephepoch=54870.0 timeformat=MJD timesys=TDB \
    ra=111.11 dec=22.22 phi0=0.0 f0=112.345 f1=-2.345e-10 f2=3.45e-20

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

SEE ALSO

    gtophase, gtpulsardb
