Fermi Gamma-ray Space Telescope

Ephemeris Data File (gtpulsardb) Tutorial

The gtpulsardb tool is a utility for manipulating and accessing databases containing pulsar ephemeris data. Using this tool, one can accept input from any number of FITS files in the Fermi D4 format, and/or simple text files containing pulsar data. These input pulsar ephemerides can be filtered by pulsar name and other criteria, and the results stored in a new Fermi (formerly GLAST) D4 FITS file.

Note: The FTOOL fv can be used to view the pulsar database file.

Prerequisites

Sample Files

To try the following examples, download the following simulated data files. The simulated data is for demonstration purposes.

Also see:

Tutorial Fermitools References
Pulsar Analysis Tutorial: Collect Ephemeris Information of Your Pulsar gtephem
Ephemeris Computation Utility gtpulsarDb

» Fermitools References

How To Filter An Existing Pulsar Ephemeris File

Filtering By Pulsar Name

It is possible to filter an ephemerides file to extract only ephemerides for a particular pulsar as follows:

prompt> gtpulsardb
Input pulsar ephemerides database file name[] bogus_pulsardb.fits
Output pulsar ephemerides database file name[] bogus_pulsardb_Crab.fits
Filter ephemerides (NAME|TIME|SOLAREPH|NONE) [NONE] NAME
Pulsar name[ANY] Crab
Name of person responsible for generation of the database being compiled[Anonymous User] John Doe
prompt>

The name supplied in the example was simply "Crab", but in general the "B-name" or "J-name" may be used as well as common names such as "Crab" or "Vela". Colloquial names and B-names are looked up using the ALTERNATIVE_NAMES extension to obtain the correct J-name, which is then used to look up ephemerides in the SPIN_PARAMETERS and/or ORBITAL_PARAMETERS.

Filtering By Time Range

It is also possible to filter an ephemerides file to extract only ephemerides which are valid during some portion of a user-specified time range, as follows:

prompt> gtpulsardb
Input pulsar ephemerides database file name[] bogus_pulsardb_Crab.fits
Output pulsar ephemerides database file name[] bogus_pulsardb_MJD55k.fits
Filter ephemerides (NAME|TIME|SOLAREPH|NONE) [NONE] TIME
Start time of observation in MJD (TDB)[0.] 54900
Stop time of observation in MJD (TDB)[1.e5] 55100
Name of person responsible for generation of the database being compiled[Anonymous User] John Doe
prompt>

How To Merge Two Or More Pulsar Ephemeris Files

In order to merge two or more ephemerides files, it is necessary to supply more than one file name through the psrdbfile parameter. This is done using the "at-file" syntax familiar to Ftools users, in which the file names are written into a text file, and that text file is supplied to gtpulsardb with a prepended at-sign (@). 

prompt> cat filename_list.txt
bogus_pulsardb.fits
my_pulsardb.fits
prompt>


prompt> gtpulsardb
Input pulsar ephemerides database file name[] @filename_list.txt
Output pulsar ephemerides database file name[] bogus_pulsardb_merged.fits
Filter ephemerides (NAME|TIME|SOLAREPH|NONE) [NONE] NONE
Name of person responsible for generation of the database being compiled[Anonymous User] John Doe
prompt>

How To Create A New D4 FITS File

Pulsar ephemerides can also be supplied to gtpulsardb using a simple text file format. Each text file contains data which correspond to one of the four extensions in a Fermi D4 FITS file. Using the same at-file syntax described in the previous example, any number of these text files can be combined into a single Fermi D4 FITS file.

prompt> cat my_pulsardb_summary.txt
my_pulsardb_spin.txt
my_pulsardb_bin.txt
my_pulsardb_obs.txt
my_pulsardb_name.txt
prompt>


prompt> gtpulsardb
Input pulsar ephemerides database file name[] @my_pulsardb_summary.txt
Output pulsar ephemerides database file name[] my_pulsardb.fits
Filter ephemerides (NAME|TIME|SOLAREPH|NONE) [NONE] NONE
Name of person responsible for generation of the database being compiled[Anonymous User] John Doe
prompt>

Going Beyond The Simple Cases

The three examples above outline the three basic functions of gtpulsardb: filtering, merging and creating brand new Fermi D4 FITS files. However, advanced users may use the tool for more complicated tasks.

For example:

  • Combining functions. Instead of invoking the three functions separately as shown above, these functions can all be performed at the same time (i.e., ephemerides can be filtered by a pulsar name when a brand new Fermi D4 FITS file is created from two existing Fermi D4 FITS files, if requested).

    This technique may be useful when updating a local copy of D4 FITS file that contains only ephemerides of a particular pulsar.

  • Mixing input formats. Another feature worth noting is the ability to freely mix the two formats, text files, and D4 FITS files.

    This feature may be useful when adding a few ephemerides to (a local copy of) the master ephemerides database, in order to update the database; or when inserting "test ephemerides" in the database to share them with collaborators.

    Caution: To maximize flexibility, the tool does not require the input files to contain complete and consistent ephemeris information, i.e., if the inputs are incomplete, or self-contradictory, the tool can produce an output file which is in a Fermi D4 FITS file format, but which is missing key information, and may not work properly with other tools. For example, it is a simple matter to produce a FITS file that includes only a SPIN_PARAMETERS extension.

Last updated: 11/09/2017