Fermi Gamma-ray Space Telescope

Pulse Phase Calculation (gtpphase) Tutorial

The gtpphase tool's purpose is to assign a pulse phase to each record in an event file, based on one or more known pulsar ephemerides.

Prerequisites

  • Event data file (See Extract LAT Data).
  • Orbit file to use for the barycentric correction
  • Ephemeris information of suspected pulsation provided in one of the following forms:
    • Manually input the source (pulsar) location (for the barycentric correction), pulse frequency or period, and related information
    • Automatically extracted from a pulsar ephemerides database, available online.

Sample Files. To try the examples in this section, you can download the following simulated data files. The simulated data is for demonstration purposes and the simulated pulsar is slightly brighter than the Vela pulsar. For more information, see the parameters used for the simulation.

Note: Like gtophase, this tool operates on files in place. The examples below are designed to produce the same result from an identical input event file and, in all cases, the event file processed by gtpphase will be identical to:

Also see:

Tutorial Fermitools References
Pulsar Analysis Tutorial: Calculate Pulse Phase for Each Photon gtpsearch
Period Search Tutorial gtpphase
Binary Orbital Phase Calculation gtophase

» Fermitools References

How To Assign Pulse Phases

There are several ways to input pulsar ephemeris information to the gtpphase tool; it can:

  • Extract a series of ephemerides from an existing pulsar ephemerides database file, or
  • Accept a single ephemeris entered manually by the user.

    In each case, the tool does not produce a separate output file, but operates directly on the input file in place.

    Note: If execution is successful, the tool produces no textual output.

The tool applies the barycentric time correction on the fly using the JPL DE405 solar system ephemeris by default. You should know which solar system ephemeris the timing solution for your pulsar uses. In the event that the timing solution uses JPL DE200, simply specify solareph="JPL DE200" on the command line when invoking the tool.

The timing solution(s) for your pulsar must cover the entire dataset or gtpphase will not successfully run with the DB option. The best way to check the validity of the timing solution(s) is to inspect the D4 manually, either using something like fdump or fv, and to check the 'Valid From' and 'Valid Until' entries for the timing solution(s) corresponding to your pulsar. If the entire dataset is not covered, one may divide the dataset, using a tool like gtselect, and apply the phase with the DB option in gtpphase for the files corresponding to valid time periods and then use the FREQ or PER option to input the timing solution manually for those periods outside the valid range using either the output from gtephem (gtephem tutorial link here) or an ephemeris from the literature. Then, the files can be remerged using a tool like gtselect or the FTOOL fmerge.

Using A Pulsar Ephemerides Database File

The simplest way to run the gtpphase tool, which may suffice for most applications, is for the tool to extract the information from a pulsar database. The exact process the tool uses for choosing ephemerides will be described below.

prompt> gtpphase
Event data file name[] fakepulsar_event.fits
Spacecraft data file name[] simscdata_1week.fits
Pulsar ephemerides database file name[] bogus_pulsardb.fits
Pulsar name[ANY] PSR J9999+9999
How will spin ephemeris be specified? (DB|FREQ|PER) [DB] DB
prompt>

The following plot of the modified events file was produced using the Ftools fhisto and fplot, and shows the distribution of counts in the PULSE_PHASE column in the events file following the phase assignment performed above.

prompt> fhisto lowval=0.0 highval=1.0
Name of FITS file and [ext#][] fakepulsar_event.fits
Name of output FITS file[] fakepulsar_pulse_shape.fits
Name of column to generate histogram[] PULSE_PHASE
Size of bins[INDEF] 0.05
input file (no binspec): file://fakepulsar_event.fits[1]
input file: file://fakepulsar_event.fits[1][bin  PULSE_PHASE=0:1:0.05]
The histogram extension: 1dhisto
prompt>


prompt> fplot
Name of FITS file and [ext#][] fakepulsar_pulse_shape.fits
Name of X Axis Parameter[error][] X
Name of Y Axis Parameter[error] up to 8 allowed[] Y[Error]
Lists of rows[-] -
Device: /XWindow, /XTerm, /TK, /PS, etc[/XW] /xserv
Any legal PLT command[] marker on
PLT> exit
prompt>

gtpphase example 3 (graphical output)

The plot shows a sinusoidal folded-light curve, which is consistent with a pulse profile of the simulated pulsar.

Inputing A Pulsar Ephemeris Manually

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. 

prompt> gtpphase
Event data file name[] fakepulsar_event.fits
Spacecraft data file name[] simscdata_1week.fits
Pulsar ephemerides database file name[] NONE
Pulsar name[ANY] PSR J9999+9999
How will spin ephemeris be specified? (DB|FREQ|PER) [DB] FREQ
Epoch for the spin ephemeris[0.] 54870.0
Time format for spin ephemeris epoch (FILE|MJD|ISO|FERMI|GLAST) [FILE] MJD
Time system for spin ephemeris epoch (FILE|TAI|TDB|TT|UTC) [FILE] TDB
Right Ascension to be used for barycenter corrections (degrees)[0.] 111.11
Declination to be used for barycenter corrections (degrees)[0.] 22.22
Base value of phase at this epoch[0.] 0.0
Pulse frequency at the epoch of the spin ephemeris (Hz) (0.:) [1.] 12.345
First time derivative of the pulse frequency at the epoch of the spin ephemeris (Hz/s)[0.] -2.345e-10
Second time derivative of the pulse frequency at the epoch of the spin ephemeris (Hz/s/s)[0.] 3.45e-20
prompt>

The result of this run is identical to that of the previous example.

Getting More Information on Computation

If gtpphase is invoked with chatter parameter set to 4 or larger, it will display brief summaries of loaded ephemerides, arrival time corrections, and time systems being used. This feature shows you additional information on computations being performed, which may help you understand the tool. Also, the extra information printed may contain a clue to diagnose certain types of problem. So, try a high chatter when you are unsure on the tool's behavior.

prompt> gtpphase chatter=4
Event data file name[] fakepulsar_event.fits
Spacecraft data file name[] simscdata_1week.fits
Pulsar ephemerides database file name[] bogus_pulsardb.fits
Pulsar name[ANY] PSR J9999+9999
How will spin ephemeris be specified? (DB|FREQ|PER) [DB] DB
gtpphase: INFO: ==========================
gtpphase: INFO: Pulsar ephemerides are loaded and/or filtered as follows:
gtpphase: INFO:    Load FITSDB AUTHOR='Anonymous Tester' DATE='2009-02-11T19:12:04'
gtpphase: INFO:    Filter by pulsar name 'PSR J9999+9999'
gtpphase: INFO:    Filter by solar system ephemeris 'JPL DE405'
gtpphase: INFO: ==========================
gtpphase: INFO: Pulsar ephemerides FITS files loaded are:
gtpphase: INFO: [1] PULSARDB AUTHOR='Anonymous Tester' DATE='2009-02-11T19:12:04'
gtpphase: INFO:    * Load TEXTDB SPIN_PARAMETERS(FREQ) FILENAME='bogus_pulsardb_spin.txt'
gtpphase: INFO:    * Load TEXTDB OBSERVERS FILENAME='bogus_pulsardb_obs.txt'
gtpphase: INFO:    * Load FITSDB AUTHOR='Masaharu Hirayama' DATE='2006-03-24T15:40:16'
gtpphase: INFO: ==========================
gtpphase: INFO: Spin ephemerides in the database are summarized as follows:
gtpphase: INFO:    1144 spin ephemeri(de)s in total
gtpphase: INFO:    1 spin ephemeri(de)s for pulsar "PSR J9999+9999"
gtpphase: INFO:    1 spin ephemeri(de)s with solar system ephemeris "JPL DE405" for pulsar "PSR J9999+9999"
gtpphase: INFO:    1 spin ephemeri(de)s loaded into memory
gtpphase: INFO: ==========================
gtpphase: INFO: Orbital ephemerides in the database are summarized as follows:
gtpphase: INFO:    19 orbital ephemeri(de)s in total
gtpphase: INFO:    0 orbital ephemeri(de)s for pulsar "PSR J9999+9999"
gtpphase: INFO:    0 orbital ephemeri(de)s with solar system ephemeris "JPL DE405" for pulsar "PSR J9999+9999"
gtpphase: INFO:    0 orbital ephemeri(de)s loaded into memory
gtpphase: INFO: ==========================
gtpphase: INFO: --------------------------
gtpphase: INFO: Arrival time corrections are applied as follows:
gtpphase: INFO:    Barycentric correction: Applied if necessary
gtpphase: INFO:    Binary demodulation: Not applied
gtpphase: INFO:    Pdot cancellation: Not applied
gtpphase: INFO: Following time system(s) are listed for this task:
gtpphase: INFO:    Spin ephemeri(de)s are defined in: TDB(1)
gtpphase: INFO:    Orbital ephemeri(de)s are defined in: None
gtpphase: INFO:    Pdot cancellation will be performed in: None
gtpphase: INFO:    Time series analysis will be performed in: TDB
gtpphase: INFO: --------------------------
prompt>

Last updated by: 11/09/2017