DSPSR user documentation: dspsr

Post-processing output archives

Before writing folded archives to disk, dspsr can perform post-processing tasks using the command language defined by psrsh. Post-processing enables a wide variety of tasks, including polarimetric calibration, integration over frequency, giant pulse searching, etc. As with most PSRCHIVE programs, post-processing tasks can be added with the -j command-line option and post-processing scripts can be specified using the -J command-line option.

Example: polarimetric calibration

The following psrsh script: 
# the calibrator database is loaded only once
init cal load /psr/calibrators/fluxcal/database.txt
init cal load /psr/calibrators/metm/database.txt
init cal load /psr/calibrators/pcal/database.txt

# zap frequency channels with anomalous power
zap median

# correct the backend convention, if necessary
cal backend

# calibrate the archive by combining pcm and noise diode
cal type ovhb04
cal

# correct the basis and projection, if necessary
cal frontend

# calibrate the flux scale
cal flux

fscrunch
  1. loads three different calibrator databases (only once, on the first execution of the script),
  2. performs RFI mitigation using the same frequency-domain median-smoothing algorithm as paz -r,
  3. calibrates the data as done by pac -S, and
  4. integrates all frequency channels.
The above script may be saved as ZcalF.psh and used as in 
dspsr -J ZcalF.psh -F 128:D caspsr.dat

Example: searching for giant pulses

The following psrsh script: 
# disable log messages
init verbose --

# form a total intensity copy of the raw data
push
fscrunch
pscrunch

# reduce to 512 phase bins
bscrunch 512

# keep only profiles with a peak greater than ten sigma
test $all:max > ( $off:avg + 10 * $off:rms )

# restore the original file
pop
  1. creates a copy of the archive
  2. integrates over all frequency channels and polarizations to form a single total intensity profile
  3. reduces the number of pulse phase bins
  4. throws an exception if the pulse peak is less than 5 times the off-pulse noise
This script can be used to perform real-time giant pulse searching; e.g. save the above psrsh script in a file named giant.psh, then run 
dspsr -K -s -J giant.psh ...
Use -K to remove the inter-channel dispersive delays before slicing and -s to produce single-pulse archives. Only those archives that pass the test command will be written to disk. Also, because the fscrunch and pscrunch commands are performed on a copy of the data (created with the push command) the original frequency resolution and full polarization information will be written to disk.

Important Note: By default, dspsr -s divides the timeseries into single pulses at reference phase 0 (zero) as predicted by the phase model (polyco / tempo2 predictor). By convention, the peak of the template profile used for pulsar timing is often placed at reference phase 0. In this case, to avoid splitting each single pulse across two files (or sub-integrations), add -p 0.5 to the command line; this will shift the reference phase by half a pulsar rotation before dividing into single pulses.

Example: matched filter search for pulses

To perform matched filtering, save the template pulse profile in a file (e.g. template.std) and correlate each pulse with the template as in the following example: 
# disable log messages
init verbose --

# load the template
init load template template.std

# form a total intensity copy of the raw data
push
fscrunch
pscrunch

# cross correlate the profile with the template
profile correlate template

# keep only profiles with a peak greater than 15 sigma
test $all:max > ( $off:avg + 15*$off:rms )

# restore original file
pop