For the purpose of this demonstration, I will be using data from PSR J0437–4715 collected at Parkes in 2009. A typical data set will generally contain files from a stable reference flux calibrator eg. HYDRA A taken once per day, files from a 100% linearly polarized reference source (CAL - an amplitude modulated linear noise diode signal), taken before and after each observation, and the observation files from the pulsar itself. Before starting any analysis, it is worth getting to know the file attributes.
One can check a file’s attributes using psrstat. A polarization calibration is marked ‘PolnCal’, a flux calibrator is marked ‘FluxCal-On’ or ‘FluxCal-Off’, and a pulsar observation type marked ‘Pulsar’.
For example,
psrstat m2009100020946.fb produces the following output for this particular polarization calibration file:
Attribute Name Description Value ------------------------------------------------------------------ file Name of the file m2009100020946.fb nbin Number of pulse phase bins 1024 nchan Number of frequency channels 128 npol Number of polarizations 4 nsubint Number of sub-integrations 1 type Observation type PolnCal site Telescope name 7 name Source name CAL coord Source coordinates 04:37:00.000-47:35:00.00 freq Centre frequency (MHz) 1341 bw Bandwidth (MHz) 64 dm Dispersion measure (pc/cm^3) 0 rm Rotation measure (rad/m^2) 0 dmc Dispersion corrected 0 rmc Faraday Rotation corrected 0 polc Polarization calibrated 0 scale Data units FluxDensity state Data state Coherence length Observation duration (s) 4.718762 etc...
Similarly,
psrstat m2009097074500.fb produces the following output for a Pulsar file:
Attribute Name Description Value ------------------------------------------------------------------ file Name of the file m2009097074500.fb nbin Number of pulse phase bins 1024 nchan Number of frequency channels 128 npol Number of polarizations 4 nsubint Number of sub-integrations 1 type Observation type Pulsar site Telescope name 7 name Source name 0437-4715 coord Source coordinates 04:37:15.815-47:15:08.63 freq Centre frequency (MHz) 3256 bw Bandwidth (MHz) 64 dm Dispersion measure (pc/cm^3) 2.64397811889648 rm Rotation measure (rad/m^2) 0 dmc Dispersion corrected 0 rmc Faraday Rotation corrected 0 polc Polarization calibrated 0 scale Data units FluxDensity state Data state Coherence length Observation duration (s) 13.1076740000001 etc...
Other useful tools for querying attributes are vap, psredit and vip.
For example:
vap -nc bw * returns the bandwidth (bw) without headers (-n) of all the files in the current directory. Type vap -H for a full list of parameters able to be queried.
psredit -c type,name,dm <archive> returns the observation type, name and dispersion measure of an archive
vip -a <file> returns the pointing attributes of a particular file, such as RA, DEC, LST etc
Once familiar with the file attributes, it is a good idea to sort the observation files according to frequency and/or bandwidth, in preparation for downstream analysis. This becomes important during archive creation to avoid frequency/bandwidth mismatch errors.
Gather all cal files into a single directory, and make this directory the working directory.
Create a database summary file (default output is database.txt) of all the calibrators eg:
pac -wp . -u $file-extension where pac searches in the local directory (-p .) for files with extension $file-extension (-u), and writes to a new database.txt file (-w)
Next, determine the system temperature and flux density of the reference source using fluxcal eg:
fluxcal -d database.txt -c $prefix/share/fluxcal.cfg where fluxcal.cfg contains the standard candle information
Here, fluxcal appends database.txt with flux calibration solutions, but keeps a copy of the original as database.txt.bkp
Graphical display of the calibrator archive is possible with pacv, psrplot and pav, utilising the PGPLOT graphics package, for example
pacv -P <archive>.fluxcal produces a publication quality plot of a flux calibrator archive, showing system and noise diode cal equivalent flux densities with frequency, of both polarizations. When applied to a HYDRA cal file, say a ‘FluxCal-Off’ pointing (ie. a pointing taken one full beam width north or south of HYDRA), pacv will display the calibrator solution of the instrument response in terms of absolute gain, differential gain and differential phase
pacv -n cpu <archive> plots uncalibrated on-pulse total and polarized flux (-n cpu) with frequency; for calibrated use -n cpc; to view system parameters (ie. off-pulse) use -n spu and -n spc
pacv -n csu <archive> plots uncalibrated on-pulse Stokes parameters (-n csu) with frequency; for calibrated use -n csc; likewise to view system parameters use -n ssu and -n ssc
psrplot -p D -j FTp <archive> scrunches frequency channels, sub-integrations and polarizations (-j FTp), and produces a single plot of total flux (-p D), eg. for checking the performance of the linear noise diode cal square wave.
pav -X - -publn - -ch 0.8 <archive> produces a black and white publication plot (- -publn) with a set character height (- -ch 0.8), of the cal and system amplitude and phase as a function of frequency channel (X)
The next step is to make the pulsar observations directory the working directory and use psradd to create 5 minute integrations (-I 300), prior to calibration eg:
psradd -I 300 $file-extension the output files of which have .it extensions. Use of the -E <psr.eph> argument tells psradd to load a new ephemeris if required.
Assuming the archives are free of problematic RFI (See ‘RFI Mitigation’ below), they can be calibrated for flux and polarisation, again by applying pac but this time with reference to the calibrator summary file created above. By default, pac uses the ‘SingleAxis’ calibration model, but use of this model assumes that the two receptors are orthogonally polarised, that the reference source is 100% polarised, and that both receptors receive the signal in phase.
pac -d /path to/database.txt *.it
The output files are given .calib extension if both flux and pol calibration were possible, and .calibP if only pol calibration was possible; use of the -P argument with pac, calibrates for polarization only.
In order to acquire a more accurate instrument response, use of the ‘Reception’ calibration model is required. Firstly, pcm is used to produce a calibrator solution by choosing the most suitable phase bins in the integrated pulse profile created by psradd, for example:
Say the output of pac above are .calibP files, then
psradd -T -o total.calibP *.calibP creates a Tscrunched archive (-T) ‘total.calibP’ (-o)
Then run pcm on the uncalibrated *.it archives:
pcm -d /path to/database.txt -c total.calibP -s -t2 -D result *.it where pcm automatically chooses the best phase bins from the calibrated archive (-c), intrinsic signal fluctuations are compensated for (-s), a diagnostic report is printed (-D result), and the process is split between two processor cores (-t2) since it is quite computationally intensive. The output from pcm is the calibrator solution ‘pcm.fits’, and can be viewed with pacv.
The solution from pcm can now be used in the calibration process by re-running pac using the ‘Receptor’ model option eg:
pac -d /path to/database.txt -e new.calib -A pcm.fits -S *.it where pac utilises the pcm output for instrument response (-A), and the complete Reception model (-S), and outputs recalibrated files with extension ‘.new.calib’ (-e).
Finally, create a new recalibrated archive for viewing with pav or psrplot (see ‘Viewing archives’ below) eg:
psradd -T -o total.calibP.new *.new.calibP
The PSRCHIVE suite offers two archive viewing and plotting routines, namely pav and psrplot. Both utilise the PGPLOT graphics package and can produce publication quality plots.
1) pav
pav can graphically display the content of an archive, and also allows preprocessing of the archive before displaying it, but without any change to the archive’s content.
For example,
pav -FTp -DC <archive>, scrunches all frequency channels, sub-integrations and pols (-FTp), and plots the centred (-C) integrated pulse profile (-D)
pav -FY <archive>, scrunches all frequency channels (-F), and plots sub-integrations with pulse phase (Y)
pav -G <archive>, plots pulse amplitude and phase with frequency (G); addition of the -d (dedisperse) option corrects for the dispersion delay of the interstellar medium, illustrated by the frequency-dependent phase sweep across the band
pav -FT -SC -g 1/xs <archive>, scrunches all frequency channels and sub-integrations (-FT), and plots centred polarization parameters I, L, V and PA (-SC) on PGPLOT window no. 1 (-g 1/xs); addition of - -plot_qu displays the stokes parameters I, Q, U, V and PA, and addition of - -ld displays pulse phase in degrees
Other options for pav include the ability to zoom in on a specific range of phase (-z), frequency (-k), sub-integration (-y) and position angle (-l).
2) psrplot
To list available plot types use psrplot -P.
To list plot options for a specific plot type use psrplot -C <plot-type>, or psrplot -A <plot-type> for more common options.
Some psrplot examples:
psrplot -N1×3 -jFT -c ch=2 -p o -p s -p Y <archive>, preprocesses by scrunching frequency and integrations (-jFT), and plots an array of 3 plots one on top of the other (-N1×3), polarisation angle (-p o), stokes parameters (-p s) and subint/phase with amplitude (-p Y). Character height (ch) is set to double the default using the -c argument (-c ch=2).
Zooming in on the data is possible by including eg. -c ‘x:range=(0.5,0.7)’, which plots the xrange from 0.5–0.7
Overlaying multiple plots can be achieved using both the -F and -c arguments, for example:
psrplot -p D -j FTp -F -c “x:win=(0,1),y:win=(0,1)” fileA fileB
PSRCHIVE facilitates many levels of archive manipulation, from changing file parameters to full pre-processing and output of new archives. Here are just a few examples.
psredit allows you to change a file parameter (-c), for example to change the bandwidth (bw) sign to positive (sometimes the CPSR2 output might have been set incorrectly) and output to a new archive (-e) with no change to the original:
psredit -c bw=64 -e new <archive>
pam allows you to conduct pre-processing on an archive, for example
pam -m -SFT <archive> scrunches in time and frequency (FT), transforming to Stokes parameters (S) and overwrites the archive (-m) while,
pam -e new -SFT <archive> creates the new archive (-e), leaving the original untouched.
Supposing you wanted to tweak the folding period of an archive but leave the original unchanged, use pam with the - -period option eg.
pam -e new -FTp - -period <arg> <archive>
Archives may be combined with or without preprocessing using psradd, for example
psradd -I 300 -E <.eph> <archive> creates 5 minute integrations (-I 300) using the supplied ephemeris (-E). The addition of the -j option allows preprocessing before integration.
Use pazi the interactive version of paz the zapper to check for and remove bad subints, channels or bins.
First, create a phase-aligned archive from individual sub-integrations eg.
psradd -f <archive>.ar *.fb
1) To check the subints, create a frequency-scrunched archive and run pazi:
pam -e Fscrunched -F <archive>.ar
pazi <archive>.Fscrunched enters into interactive mode with a cross as a cursor on the time/phase graphic, movable by mouse.
Any bad subints can now be zapped by right-clicking the mouse, or to remove a block of subints for example, left-click at one end of the block, move the cursor to the other end of the block and press ‘z’. By default the subints are not removed but zero-weighted (paz -w) to conserve the temporal signature of the archive. A useful option is ‘p’ which prints the command used, listing the subints that are zero-weighted. Left click the mouse twice to zoom in, and at any time use ‘u’ to undo any changes if required.
When happy with the outcome, press ‘s’ to save the file (default is to <archive>.pazi), and ‘q’ to quit.
The saved file can be checked and viewed with pav eg:
pav -Y <archive>.pazi
2) To check for bad channels first create a time-scrunched archive, then run pazi:
pam -e Tscrunched -T <archive>.ar
pazi <archive>.Tscrunched
With the cursor on the time/phase graphic, press ‘f’ to switch to the frequency/phase graphic.
Any bad channels can now be zapped using the methods described above. Similarly, ‘p’ prints the command and lists the channels that pazi removes.
Press ‘s’ to save the file, and ‘q’ to quit.
As above, the saved file can be checked and viewed with pav eg:
pav -G <archive>.pazi
Alternatively, after checking the subints and channels above but not saving the changes, run paz on the unscrunched archive using the output from the ‘p’ option above to automate the procedure, for example:
paz -w “20” -z “119 120 121 122 123 124 125 126 127 0 1 2 3 4 5 6 7 8 9 10” -e pazi <archive>.ar
Here, paz zero-weights subint 20 (-w), and flags channels (-z) at the edges of the band (119 120 121 122 123 124 125 126 127 0 1 2 3 4 5 6 7 8 9 10) and outputs the new archive ‘<archive>.pazi’
The saved file can be checked and viewed with pav eg:
pav -TG <archive>.pazi (frequency/phase) or
pav -FY <archive>.pazi (subint/phase)
3) Corrupt phase bins can be zapped either interactively or manually. In interactive mode, pazi allows checking and removal of bins by use of the ‘b’ option, and as above, bins can be removed individually or in blocks, with the use of ‘p’ printing the command plus a list of bins removed.
psrsh is a scripting tool designed to allow repetitive processing of multiple archives. For example the following script, if included in a shell for-loop, will load each archive, perform some preprocessing and then unload with new file extensions, leaving the originals untouched:
#!/usr/bin/env psrsh #zap band edges zap edge 0.05 #scrunch frequency channels and subints FT #centre maximum intensity of profile centre max #unload with new extension unload ext=new
Analysis of pulsar archives can be done either by dedicated software in the PSRCHIVE suite itself such as pdmp for parameter optimisation and pat for timing, or by running external scripts on the ascii output from PSRCHIVE’s pdv or psrtxt.
pdmp searches for the best period and DM, and S/N at that period/DM of a given archive, eg:
pdmp <archive> -g archive.ps/ps Here the output is a postcript file (-g DEVICE).
Using 0437–4715 as an example, you could then refine the DM search by decreasing the DM range (-dr) and step (-ds), eg:
pdmp -dr 5 -ds 0.01 <archive>
To plot the DM/period output only, use the -k option:
pdmp -k 0 0 <archive>
To include a period offset in the search, use the -po option:
pdmp -po <> <archive>
pdmp also outputs two ascii files, pdmp.per and pdmp.posn. These can be passed to an external plotting package such as gnuplot, and in the case of a millisecond pulsar in a binary orbit such as 0437–4715, plotting period change with time for example, can demonstrate the doppler effect on the signal as the pulsar orbits its companion.
In order to produce pulse time of arrival estimates (TOAs), a template profile needs to be created and a fudicial point chosen on that profile, for each frequency of observation. These templates or standards (stds) are then aligned so that toas can be combined from different frequencies.
a) Create the stds.
Using 300 second calibrated integrations, scrunch them (-j FTp) and add them into one archive eg:
psradd -f 300sec.ar -j FTp *.calibP
Then run pas on the archive for each frequency eg.:
pas 300sec.ar At this point, pas enters interactive mode, offering a number of fine tuning options. With the crosshairs over the plot, centre © and smoooth the profile (m), and save (s) the file.
b) Align the templates
Choose one of the stds created above as the reference profile, and align the others to it either individually (-r) or automatically (-a) eg:
pas -r <reference_profile> -a *.std
This leaves all stds aligned in phase with your reference profile.
c) Create the TOAs
Run pat on the calibrated 300 second subints and output to a .tim file eg:
pat -a /path/to/refernce_profile *.calibP > pulsar.tim
d) Fit the TOAs to the timing model
In the presence of a parameter (.par) file for the chosen pulsar, run TEMPO or TEMPO2 on the .tim files. Alternatively, use GUIs such as PSRCHIVE’s RHYTHM.
1) pdv
pdv can print output as ascii textfiles, that can then be manipulated using awk as you see fit, and sent to external plotting packages. For example,
pdv -K -f -n 20 archive > file.txt prints mean flux and pulse width (both W10 and W50) (-f) of channel 20 (-n), and hashes the header lines (-K).
pdv -FTZKt archive > file.txt scrunches frequency and time (-FTp), hashes the header lines and prints the pulse profile, stokes parameters and polarisation angle as ascii (-t).
pdv -NK archive > file.txt prints the S/N
2) psrtxt
psrtxt can output single channels, bins, pols or subints to ascii text.
A useful option is to find max and min values in the data eg:
psrtxt -m -b 100 <archive> returns the max and min values in bin 100 (-b) and the relevant channels, pols and subints the values occurred in.