TEMPO2 Intro Tutorial
The primary aim of this tutorial is to teach beginners the basics of Tempo2. Pulsar timing basics will also be covered in the intro, so if you have prior knowledge of pulsar timing you may want to skip over that section.
Tempo2 is a software that has been developed to fit and analyze data that has been detected through pulsar timing. To understand Tempo2, one must first understand pulsar timing, and how the data one deals with in Tempo2 is collected.
Pulsar Timing Basics
Pulsars are highly magnetized, rotating neutron stars that emit a beam of electromagnetic radiation. On a very regular period the pulse becomes momentarily visible to us. These pulses are usually most visible when observed through the radio-wave band of the electromagnetic spectrum. The typical observing frequency is around 1400 MHz, however different pulsars are observed better at different frequencies. Lower frequencies often result in more earth-based interference, and as frequencies get higher the pulses become weaker.
Through use of telescopes we can detect the Times Of Arrival (TOAs) of these pulses of electromagnetic radiation on earth. Normal spin frequencies of pulsar can give us anywhere from one pulse every few seconds to thousands of pulses a second. After the observation the pulses are all averaged together, whats called 'folding', to get a single pulse profile for the observation.You may wonder about the information that is lost by doing this, however for pulsar timing the main goal is to get an average pulse arrival time, not to understand the mechanics of pulse emmission that result in these small variations over one observation.
Once we have an averaged pulse profile we compare it to an expected pulse profile template that has been created by averaging all the pulse profiles since observations began on the pulsar. We then find the maximum cross-correlation of the actual pulse profile and the template, and add that to????? to get the designated TOA for that observation. The difference between designated TOA and the actual peak of the pulse profile is the error for that observation and is called the 1σ error. There are many, many other issues that need to be accounted for to understand when the pulse was emitted though. These issues include effects of the interstellar medium, the earth's rotation and revolution around the sun, and various issues associated with the pulsar. This is where Tempo2 comes in.
Required Input Files for Tempo2
There are two main required input files Tempo2 needs to run, they are the observation file, and the parameter file.
When the TOAs have been collected they are saved into the observation file, traditionally with the extension
Within these main two files are other required files that allow for some automatic corrections right when you load up Tempo2.
Clock Correction Files
TOAs in the observation file given to TEMPO2 are only as precise as the clocks at the observatory, so one of the primary issues that needs correcting is clock precision. Although precise compared to the average clock, we make them much more precise by comparing the clocks at the telescope to GPS and TAI, the two best timing systems in the world. The information needed to correct for the clocks is the TOA and the site it was observed at, both are contained in the observation file. When Tempo2 starts executing it will then correct for the clocks error.
For more detailed information on how this is done visit: Required Files
TOA to BAT
The next step is changing the TOA to the time of arrival at the (unchanging) center of mass of the solar system, also called the Solar System Barycenter (SSB). This is done because the TOA at one point of the earth is different than the TOA at another point on the earth, so instead we use BATs, or Barycentric Arrival Times.
There are a few pieces of information Tempo2 needs to figure out the BAT. We must know k (the distance and position of the pulsar), rí (the distance and position of the telescope relative to the center of the earth), and the solar system ephemeris, which tells us r (the position of the center of the earth relative to the Sun). Using these three pieces of information Tempo can deduce the time difference between the TOA and BAT due to their different positions in space. Luckily the parameter file and observation file contain all the information needed. This is another correction Tempo does automatically when starting up.
The final issue that must be taken into account when deducing the BAT is the effect of relativity. The SSB is very near to the Sun, thus in a very strong gravitational field, so the effect of relativity due to this gravitational field needs to be looked at when getting the final BAT. Once again, Tempo corrects for this automatically once given a par and tim file.
Observation Files (.tim)
As mentioned before the observation files are where the TOAs are stored, as well as some other pieces of information. The observation files typically have a certain format as seen in figure 1. The first column lists the specific file name, which is inconsequential except to make it easier for the reader of the file to understand. The second column lists the frequency at which the pulsar was observed in units of MHz. The next column lists the TOA in units of MJD. The fourth column is the TOA error in units of microseconds. The final required column signifies where the observation took place. There can be more columns of information than this, but these five columns are essential.
For more detail on observation files visit: Observation File Documentation
The next step in the process is to create a model of what you expect the TOAs to be for a specific pulsar. This can be estimated by using parameters such as position and spin frequency of the pulsar. These parameters are traditionally put in a file with extension
To get a better understanding of the par file and the parameters in general take a look at the parameter file. It should look something like this:
The first column in the table lists the parameter, the second column gives the post fit values and the final column tells the measurement uncertainty. The third column will have a 1 in it if the parameter was being fit for when the par file was created.
Some of the parameters are constant, and once put in the par file are not meant to be changed.
For more detail on parameter files visit: Parameter File Documentation
Parameter Models and Timing Residuals
Tempo2 combines information in the observation file and parameter file to create a model of the pulse TOAs. The longterm goal is to create better models of the pulsar and its parameters. The more short-term goal is to study any irregularities that our model doesn't take into account. To do this we compare the current model with the actual data, to look for differences. These differences in TOAs are called timing residuals.
Once you have the timing residuals the next step is to fit the parameters of the model against the actual data to decrease the residuals. When the parameter values change after fitting they are then called the post-fit values. The pre-fit values are the values of the parameters before the most recent fit.
Working in TEMPO2: Inspecting Residuals
Once you have your two required input files and have compiled Tempo2 you are ready to run it. To do this simply open a terminal and type:
Here pulsarname is simply the name of the .par or .tim file corresponding to the pulsar and observing frequency you wish to deal with. Once you have typed this in something resembling figure 4 should come up in your terminal.
Fig. 4 This table lists all the parameters, their pre-fit and post-fit values, the difference between the two, and the measurement uncertainty. Just below the pre-fit values you will find either a "Y" or an "N", which correspond to whether or not the parameter is being fit for. Above the table of parameters the residual rms is given for both the pre-, and post-fit. The residual rms gives the standard deviation between the predicted TOA and the actual TOA. This is the number that we want to get as small as possible.
The plk plug-in
The most useful aspect of Tempo2 is being able to graphically analyze timing residuals because this allows you to see long term patterns that might be occurring. To do this we will use the plk ("plot-look") plug-in. To do this type into your terminal:
There are some standard input arguments here:
-gr: determines which graphical interface we use. For now we shall use plk, but there are other options.
-f: designates the .par and .tim files as the input. It is important to list the .par file before the .tim file.
This should bring up a graphical interface looking something like this:
Of course keep in mind that the initial graph of the data points will differ from file to file.
As you can see there a few different parts of the graphical interface plk.
An important thing to keep in mind, is that if you ever have a question there is a help option. There are two ways to get a help manual for Tempo2. While using the plk interface you can simply press h, then a help manual should open up in your terminal.
Also, while in terminal you can simply type:
Or if you want information on something more specific (like on plk for example) you can type:
The graph itself starts off automatically as a graph of pre-fit timing residuals versus modified Julian day. Each point represents an observation, the bars extending vertically from each point represent the 1σ error that came from the specific observation's TOA determination. Above the graph is the title, which tells you the name, and if the graph is pre-fit or post-fit. It also tells you the rms of the timing residuals, this takes the 1σ error into account, but also includes how the actual change in TOAs over time differs from how we expect them to change over time.
Note that it doesn't specify anywhere whether or not the graph is weighted or not.
There are also two sets of switches, the squares which can be switched red or white, red signifying "on". The top set of switches are the parameters of the timing model. For example F1 is the the frequency derivative, the rate at which the pulsar's frequency changes. To see how are-fitting for a particular parameter effects the residuals simply switch the parameter on or off (red or white respectively), and then click the button RE-FIT. Then press the the 2 key on your keyboard (this will explained later). Notice any change in the residual rms.
There are two sets of buttons on the plk interface. There are those above above the x and y axis options. The first of these four buttons is RE-FIT, this button re-fits whichever parameter you have selected. The "New par" and "New tim" buttons are more complicated but for now just know that with "New par" you can create a new parameter to fit for, and with "New tim" you can create a new observation file. You might want to create a new observation file after deleting some points that had huge error bars for example, and then you can have a new tim file with only those points you didn't delete. Restart is a very helpful button, it restarts the plk interface as if you just re-entered the first command in your terminal.
To easily quit out of the graphical interface press the button "QUIT" at the bottom of the interface.
The second set of switches are those to the left of the graph. As you can see there are two columns, one designates the x-axis, the other designates the y-axis. You usually keep the y-axis as either pre-fit or post-fit. However you can explore the different options for the x-axis. There are some helpful hotkeys for changing between the options. You've already seen how pressing 2 on your keyboard changes the axis from date vs. pre-fit to date vs. post-fit. Explore what the other numbers do, as well as what happens when you hold down the shift key while pressing one of the numbers.
Creating a new par file (timing model)
Once you have fit the data so that the rms is as low as possible you can create a new timing model. To do this merely press the button "New par" in the graphics window. This will freeze up the graphics window, as you now have to go to your x-terminal where it is asking you to type in a filename for the new parameter file. Once you have entered the filename it will save the new par file to your current working directory. Once you have the new par file (timing model) you can begin tempo2 using this par file and have it begin with data already fully fitted for the parameters.
Patterns in the Timing Residuals (and which parameters to correct for)
There can be many patterns in the residuals, and some have specificities that let you know which parameter is incorrect and needs to be fitted for.
I will now go over many of the most common patterns and which parameters cause them. It is important to understand how each parameter affects the residuals graph so that you can recognize specific patterns an incorrect parameter may cause. A final set of residuals, once mostly corrected for will look something like figure 5.
Note that there is not much of a discernible pattern and that most of the points are quite near zero of the y-axis.
An important note is that if any single parameter is too far off the residuals will appear completely scrambled without any pattern as in figure 5.2.
However, when specific parameters are off the right amount they have an expected error pattern you can look for.
Default Axis Settings
With the default axis settings there are a few patterns you can look for.
There are many different parameters that will cause a sine wave pattern in the residuals when incorrectly fit for. Once you look at the period you can tell more specifically which parameter is not correct. These sine waves often have periods related to an Earth year, so you should change your x-axis to days of the year (hotkey 7).
If the sine wave has a period of one year it mean that either the parameter RAJ or DECJ is not fitted correctly.
It makes sense that an error in one of these parameters would cause a yearly sin wave, because we have the position of the pulsar incorrectly accounted for, so as we travel around the SSB we get more wrong and less wrong as we travel around the SSB.
If the sine wave has a six month period, then the parameter that needs fitting is PX.
This results in a six month period sine wave because ?????
Growing Sine Wave
With Orbital Phase as the x-axis
Some patterns are only discernible while having your x-axis be orbital phase, the hotkey for this graphical option in "3". A few patterns can present themselves.
If the residual becomes greater than half the period of the pulsar it will result in a wrap-around effect as seen in figure 8. This happens because once a residual is more than half a period, it means that the expected time is more than half a period away from the actual TOA. Therefore it is actually closer to the next/previous pulse, so tempo2 will assume thats what you meant to compare it to, resulting in a jump from positive residuals to negative residuals (or the other way around). Note also that this can occur different types of patterns, for example figure nine shows a wrap around with a sine-wave pattern.
Although I have described many different patterns here, the truth is that the patterns are usually not that apparent. Tempo2 is a powerful software, but continually a work in progress as we discover new parameter and new patterns in the timing residuals.
There is much more to learn about tempo2 than is presented in this tutorial. To learn more please visit the PPTA tempo2 homepage at this site: Tempo2 Homepage