NAME

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

USAGE

    gtophase evfile scfile psrdbfile psrname ra dec

DESCRIPTION

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

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.

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

(ophasefield = ORBITAL_PHASE) [string]
    Name of the output column to contain the assigned orbital phase.

(ophaseoffset = 0.) [double]
    Global offset applied to all assigned orbital phases.

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

(srcposition = USER) [string]
    Specify the input of source position for arrival time
    corrections. The pulsar ephemerides can be given by a "USER" or
    can be found in a database file ("DB").

(strict = no) [bool]
    If set to "yes", the tool only chooses ephemeris if the given time
    is in validity range.

(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

    This tool automatically extracts one or more ephemerides from an
    existing pulsar ephemerides database file. Unlike the similar tool
    gtpphase, there is no option for entering orbital ephemerides
    manually. This tool does not produce a separate output file, but
    operates directly on the input file in place. If execution is
    successful, the tool produces no textual output.

> gtophase evfile=fakepulsar_event.fits scfile=simscdata_1week.fits \
  psrdbfile=bogus_pulsardb.fits psrname="PSR J1834-0010" \
  ra=278.571942 dec=-0.180347

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/

SEE ALSO

    gtpphase, gtpulsardb