PSRCHIVE user documentation: psradd

1.0 Purpose

The psradd program combines multiple pulsar archives into one or more output files. It is the primary method of forming a mean pulse profile from many observations, it includes a number of criteria for automatically grouping observations into subsets, and it can perform arbitrarily complex preprocessing tasks using the psrsh command language.

psradd is generally run in one of several modes:

  1. Single output file (time append): In this mode, all of the input files specified on the command line are combined along the time dimensioninto a single output file; e.g. 
    psradd -o output.ar input*.ar
    On success, the sub-integrations from each of the input files are concatenated in time to form a single output file in which the number of sub-integrations equals the total number of sub-integrations in each input file.

  2. Single output file (frequency append): In this mode, all of the input files specified on the command line are combined along the frequency dimension into a single output file; e.g. 
    psradd -R -o output.ar subband*.ar
    On success, the frequency channels from each of the input files are concatenated in frequency to form a single output file in which the number of channels equals the total number of channel in each input file.

  3. Multiple output files: In this mode, the input files are grouped and integrated into one or more output files based on one or more criteria. These criteria currently include: the maximum time elapsed between archives, the maximum integration length, the minimum signal-to-noise ratio, and/or the maximum difference in the phase of the reference source. The output files will have the same name as the first input file included in the group, plus an additional extension (by default, .it). e.g. to form five-minute integrations from the input files, with the extension .5min, 
    psradd -I 300 -e 5min input*.ar

2.0 Usage

For pulsar observations, psradd uses a phase model (currently, either a polyco generated by tempo or a predictor generated by tempo2) to align the phases of the sub-integrations of the output archives. The ephemeris used to generate the phase model may be specified using the -p ephemfile command line option. The ephemfile can be obtained using psrcat; e.g. 
psrcat -e Jname > Jname.eph
If psrcat cannot find a new pulsar, try the -all option to load any private catalogues with additional, unpublished data.

2.1 Preprocessing of input archives

Arbitrarily complex preprocessing tasks can be performed on each input archive before it is added to the output file, as described in the psrsh manual. For example, to weight each profile by its signal-to-noise ratio before adding to the total, 
psradd -o output.ar -j 'w snr' input*.ar
You can also make psradd produce a tscrunched output archive with the -T option. In frequency append mode, when combining sub-bands that span overlapping frequencies (e.g. the output of an oversampled polyphase filter bank [PFB]), it can be useful to first delete the channels from the edeges of each sub-band; e.g. 
psradd -o output.ar -R -j "delete edge .125" subband_*.ar
will delete 12.5% of the channels from each edge of the band (for a total of 25% of the band deleted) before combining, which is useful if the PFB had 4/3 oversampling.

3.0 Algorithms

No information at this time.

4.0 Testing and examples

A simple example:

1. Generate ephem file J1643-1224.eph:

psrcat -e J1643-1224 > J1643-1224.eph

2. Run psradd to phase-align and concatenate the archives listed in 20cm.lis into file called 20cmadd.Ft, using ephemeris file J1643-1224.eph:

psradd -f 20cmadd.Ft -p J1643-1224.eph `cat20cm.lis`

3. To check for phase alignment, plot an image of the dedispersed total intensity as a function of pulse phase on the x-axis and time on the y-axis

psrplot -pY -jDp 20cmadd.Ft

5.0 Known bugs and features that require implementation

  • None at this time.