Period Search (gtpsearch) Tutorial
The gtpsearch tool searches for pulsations in data which is known or suspected to have a pulsation of a known approximate period or frequency.
Note: It is not useful for a so-called blind period search, in which data are examined for pulsations at any frequency.
Known Issues: 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.
Prerequisites
- Event data file in FT1 format, also known as a photon 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.
- fakepulsar_event.fits (372 kB) (Parameters Used)
- simscdata_1week.fits (2.5 MB)
- bogus_pulsardb.fits (256 kB)
Note: The output of gtpsearch consists of text describing the result of the periodicity search and an optional plot. This tool also creates an output file when requested. The output file contains the result of computation, i.e., the search result in the text output and the data array to plot, for future reference.
Also see:
| Tutorial | Fermitools References |
|---|---|
| Pulsar Analysis Tutorial: Calculate Pulse Phase for Each Photon | gtpsearch |
| Pulse Phase Calculation | gtpphase |
| Binary Orbital Phase Calculation | gtophase |
How To Perform A Simple Search
Using A Pulsar Ephemerides Database File
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).
The command shown below produces the following output message that describes the search criteria and explains the search result.
prompt> gtpsearch 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 Output FITS file name (NONE for no FITS output)[] gtpsearch_example_3.fits Type of statistical test to perform (CHI2 - Chi squared, RAYLEIGH - Rayleigh test, Z2N - Z2n test, H - H test) (CHI2|RAYLEIGH|Z2N|H) [CHI2] Chi2 Number of phase bins for Chi2 test[10] 10 Size of steps for trials, in units of the Fourier resolution (0.:) [0.5] 0.5 Number of trials[100] 1600 How will the time origin of the periodicity test be specified? (START|STOP|MIDDLE|USER) [MIDDLE] MIDDLE How will spin ephemeris be specified? (DB|FREQ|PER) [DB] DB Search Type: Folding Analysis Fourier Resolution: 1.65352e-06 Hz Sampling Frequency: 8.26762e-07 Hz Type of test: Chi-squared Test, 10 phase bins Probability distribution: Chi-squared, 9 degrees of freedom Search Range (Hz): [12.3443081844528, 12.3456301768625] Number of Trial Frequencies: 1600 Number of Independent Trials: 800 Maximum Statistic: 457.721899224806 at 12.3449695940386 Hz Chance Probability Range: (5.12306683181322e-90, 5.12357914272081e-90) Warning in <TClass::TClass>: no dictionary for class st_graph::IFrame is available prompt>
A plot will also be produced which is similar to the following plot.
This plot very likely shows a pulsation consistent with the ephemeris found in the file.
Using Estimated Frequency Only
In practice, an ephemerides file which contains the object of interest may not be available. In this case, one may still proceed if one has an estimate for the frequency from some other source. Suppose the best known estimate for the frequency at 54870.0 MJD (TDB) is 12.3448 Hz and that for its first time-derivative -2.3e-10 Hz/s. One could then run gtpsearch as follows.
prompt> gtpsearch 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 Output FITS file name (NONE for no FITS output)[] gtpsearch_example_4.fits Type of statistical test to perform (CHI2 - Chi squared, RAYLEIGH - Rayleigh test, Z2N - Z2n test, H - H test) (CHI2|RAYLEIGH|Z2N|H) [CHI2] Chi2 Number of phase bins for Chi2 test[10] 10 Size of steps for trials, in units of the Fourier resolution (0.:) [0.5] 0.5 Number of trials[100] 1600 How will the time origin of the periodicity test be specified? (START|STOP|MIDDLE|USER) [MIDDLE] MIDDLE 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 Pulse frequency at the epoch of the spin ephemeris (Hz) (0.:) [1.] 12.3448 First time derivative of the pulse frequency at the epoch of the spin ephemeris (Hz/s)[0.] -2.3e-10 Second time derivative of the pulse frequency at the epoch of the spin ephemeris (Hz/s/s)[0.] 0.0 Search Type: Folding Analysis Fourier Resolution: 1.65352e-06 Hz Sampling Frequency: 8.26762e-07 Hz Type of test: Chi-squared Test, 10 phase bins Probability distribution: Chi-squared, 9 degrees of freedom Search Range (Hz): [12.3441087676517, 12.3454307600612] Number of Trial Frequencies: 1600 Number of Independent Trials: 800 Maximum Statistic: 373.24515503876 at 12.3449694268752 Hz Chance Probability Range: (5.55660807119948e-72, 5.55716373502439e-72) prompt>
The result is similar to the first example, but the main peak in the plot is shifted to the right because the estimated frequency used for the search center was chosen to be noticeably lower than the peak frequency for demonstration purposes. The peak still occurs at the correct frequency, but the value of the statistic is lower because the trial frequencies are coarsely spaced on the natural frequency scale determined intrinsically by the data set.
Correcting For Known Frequency Variations
From the shape of the graph, it appears that there is a strong maximum with mainly symmetric side lobes. Encouraged by this result, one might run the tool again, using the position of the peak from the previous run as the central frequency. (The position of the peak is stated at the beginning of the tool output.) To zoom in on the peak more closely, the number of trials will be reduced to 100. In addition, the process of correcting for variations in the frequency known from other observations will be demonstrated. For this example, the frequency derivatives were taken from the Monte Carlo truth of the simulated pulsar.
prompt> gtpsearch 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 Output FITS file name (NONE for no FITS output)[] gtpsearch_example_5.fits Type of statistical test to perform (CHI2 - Chi squared, RAYLEIGH - Rayleigh test, Z2N - Z2n test, H - H test) (CHI2|RAYLEIGH|Z2N|H) [CHI2] Chi2 Number of phase bins for Chi2 test[10] 10 Size of steps for trials, in units of the Fourier resolution (0.:) [0.5] 0.5 Number of trials[100] 600 How will the time origin of the periodicity test be specified? (START|STOP|MIDDLE|USER) [MIDDLE] MIDDLE 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 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 Search Type: Folding Analysis Fourier Resolution: 1.65352e-06 Hz Sampling Frequency: 8.26762e-07 Hz Type of test: Chi-squared Test, 10 phase bins Probability distribution: Chi-squared, 9 degrees of freedom Search Range (Hz): [12.344721565444, 12.3452167958713] Number of Trial Frequencies: 600 Number of Independent Trials: 300 Maximum Statistic: 479.02519379845 at 12.3449695940386 Hz Chance Probability Range: (5.26612783793371e-95, 5.32751826472965e-95) prompt>
The effect of correcting for frequency variation was to increase the value of the maximum statistic, or the height of the main peak. Changing the central frequency brought the main peak back to the center of the graph. With the smaller number of trials, the second lobe on either side was cut off.
Looking For Precise Centroid Of The Peak
By decreasing the steps between subsequent trials, one can see the shape of the peak in a finer resolution.
prompt> gtpsearch 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 Output FITS file name (NONE for no FITS output)[] gtpsearch_example_6.fits Type of statistical test to perform (CHI2 - Chi squared, RAYLEIGH - Rayleigh test, Z2N - Z2n test, H - H test) (CHI2|RAYLEIGH|Z2N|H) [CHI2] Chi2 Number of phase bins for Chi2 test[10] 10 Size of steps for trials, in units of the Fourier resolution (0.:) [0.5] 0.05 Number of trials[100] 100 How will the time origin of the periodicity test be specified? (START|STOP|MIDDLE|USER) [MIDDLE] MIDDLE 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 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 Search Type: Folding Analysis Fourier Resolution: 1.65352e-06 Hz Sampling Frequency: 8.26762e-08 Hz Type of test: Chi-squared Test, 10 phase bins Probability distribution: Chi-squared, 9 degrees of freedom Search Range (Hz): [12.3449654602287, 12.3449736451724] Number of Trial Frequencies: 100 Number of Independent Trials: 5 Maximum Statistic: 482.242248062016 at 12.3449696767148 Hz Chance Probability Range: (1.71778604002754e-97, 1.819750454803e-97) prompt>
Getting More Information on Computation
If gtpsearch 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, followed by a description of test condition and test result. 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> gtpsearch 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 Output FITS file name (NONE for no FITS output)[] gtpsearch_example_8.fits Type of statistical test to perform (CHI2 - Chi squared, RAYLEIGH - Rayleigh test, Z2N - Z2n test, H - H test) (CHI2|RAYLEIGH|Z2N|H) [CHI2] Chi2 Number of phase bins for Chi2 test[10] 10 Size of steps for trials, in units of the Fourier resolution (0.:) [0.5] 0.5 Number of trials[100] 100 How will the time origin of the periodicity test be specified? (START|STOP|MIDDLE|USER) [MIDDLE] MIDDLE How will spin ephemeris be specified? (DB|FREQ|PER) [DB] DB gtpsearch: INFO: ========================== gtpsearch: INFO: Pulsar ephemerides are loaded and/or filtered as follows: gtpsearch: INFO: Load FITSDB AUTHOR='Anonymous Tester' DATE='2009-02-11T19:12:04' gtpsearch: INFO: Filter by pulsar name 'PSR J9999+9999' gtpsearch: INFO: Filter by solar system ephemeris 'JPL DE405' gtpsearch: INFO: ========================== gtpsearch: INFO: Pulsar ephemerides FITS files loaded are: gtpsearch: INFO: [1] PULSARDB AUTHOR='Anonymous Tester' DATE='2009-02-11T19:12:04' gtpsearch: INFO: * Load TEXTDB SPIN_PARAMETERS(FREQ) FILENAME='bogus_pulsardb_spin.txt' gtpsearch: INFO: * Load TEXTDB OBSERVERS FILENAME='bogus_pulsardb_obs.txt' gtpsearch: INFO: * Load FITSDB AUTHOR='Masaharu Hirayama' DATE='2006-03-24T15:40:16' gtpsearch: INFO: ========================== gtpsearch: INFO: Spin ephemerides in the database are summarized as follows: gtpsearch: INFO: 1144 spin ephemeri(de)s in total gtpsearch: INFO: 1 spin ephemeri(de)s for pulsar "PSR J9999+9999" gtpsearch: INFO: 1 spin ephemeri(de)s with solar system ephemeris "JPL DE405" for pulsar "PSR J9999+9999" gtpsearch: INFO: 1 spin ephemeri(de)s loaded into memory gtpsearch: INFO: ========================== gtpsearch: INFO: Orbital ephemerides in the database are summarized as follows: gtpsearch: INFO: 19 orbital ephemeri(de)s in total gtpsearch: INFO: 0 orbital ephemeri(de)s for pulsar "PSR J9999+9999" gtpsearch: INFO: 0 orbital ephemeri(de)s with solar system ephemeris "JPL DE405" for pulsar "PSR J9999+9999" gtpsearch: INFO: 0 orbital ephemeri(de)s loaded into memory gtpsearch: INFO: ========================== gtpsearch: INFO: -------------------------- gtpsearch: INFO: Arrival time corrections are applied as follows: gtpsearch: INFO: Barycentric correction: Applied if necessary gtpsearch: INFO: Binary demodulation: Not applied gtpsearch: INFO: Pdot cancellation: Applied gtpsearch: INFO: Following time system(s) are listed for this task: gtpsearch: INFO: Spin ephemeri(de)s are defined in: TDB(1) gtpsearch: INFO: Orbital ephemeri(de)s are defined in: None gtpsearch: INFO: Pdot cancellation will be performed in: TDB gtpsearch: INFO: Time series analysis will be performed in: TDB gtpsearch: INFO: -------------------------- Search Type: Folding Analysis Fourier Resolution: 1.65352e-06 Hz Sampling Frequency: 8.26762e-07 Hz Type of test: Chi-squared Test, 10 phase bins Probability distribution: Chi-squared, 9 degrees of freedom Search Range (Hz): [12.3449282559395, 12.3450101053758] Number of Trial Frequencies: 100 Number of Independent Trials: 50 Maximum Statistic: 457.721899224806 at 12.3449695940386 Hz Chance Probability Range: (3.20191676988326e-91, 3.20223696420051e-91) Warning in <TClass::TClass>: no dictionary for class st_graph::IFrame is available prompt>
Going Beyond The Simple Case
How To Use Other Statistical Tests
In the examples above, the Chi-Squared statistic was used for purposes of finding the pulsation. The gtpsearch tool currently also supports the Z2n test, the Rayleigh test, and the H test. A full explanation of the strengths and weaknesses of these approaches is beyond the scope of this document. For the sample data used in this test, all the tests return similar results, so specific examples using the other tests will not be shown.
Working In The Period Domain
The examples above all used inputs in the form of frequencies, and derivatives of frequencies. It is also possible to enter the input data as periods and derivatives of periods. These values are immediately converted to the frequency domain, and the search is still performed in the frequency domain. To enter period information instead, select PER for the ephemeris style. For example, the following input should produce the same plot as the example Using Estimated Frequency Only.
prompt> gtpsearch 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 Output FITS file name (NONE for no FITS output)[] gtpsearch_example_7.fits Type of statistical test to perform (CHI2 - Chi squared, RAYLEIGH - Rayleigh test, Z2N - Z2n test, H - H test) (CHI2|RAYLEIGH|Z2N|H) [CHI2] Chi2 Number of phase bins for Chi2 test[10] 10 Size of steps for trials, in units of the Fourier resolution (0.:) [0.5] 0.5 Number of trials[100] 1600 How will the time origin of the periodicity test be specified? (START|STOP|MIDDLE|USER) [MIDDLE] MIDDLE How will spin ephemeris be specified? (DB|FREQ|PER) [DB] PER 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 Pulse period at the epoch of the spin ephemeris (seconds) (0.:) [1.] .08100445524503847711 First time derivative of the pulse period at the epoch of the spin ephemeris (dimension-less)[0.] .01538723754958406065e-10 Second time derivative of the pulse period at the epoch of the spin ephemeris (Hz)[0.] -.01679216091436480369e-20 Search Type: Folding Analysis Fourier Resolution: 1.65352e-06 Hz Sampling Frequency: 8.26762e-07 Hz Type of test: Chi-squared Test, 10 phase bins Probability distribution: Chi-squared, 9 degrees of freedom Search Range (Hz): [12.3443081844537, 12.3456301768616] Number of Trial Frequencies: 1600 Number of Independent Trials: 800 Maximum Statistic: 479.02519379845 at 12.3449695940386 Hz Chance Probability Range: (1.40430075678232e-94, 1.42067153726124e-94) prompt>
Last updated: 11/09/2017
- Curator: J.D. Myers
- NASA Official: Elizabeth Hays
- Fermi FAQ, Comments, Feedback
- › Privacy Policy and Important Notices
- › Accessibility
- › Contact NASA
- › Page Last Updated: Thu, Sep 26, 2019