Autoaips HOWTO

autoaips -- a tool to generate aips runfiles for a particular observation.
Written for the VLBA parallax project.
Walter Brisken, Socorro NM July 2002

Documentation version 1.0 Last modified 2002/11/21, SC.

Contents:

  1. Building and installation
  2. Calibration strategy
  3. How to run autoaips
  4. Autoaips output
  5. How to run these scripts in AIPS
  6. CLEANUP and UVCLEANUP
  7. Customization
  8. Calibration Copying
  9. Additional notes
  10. A complete example walkthrough.
1. Building and installation:

A few standard unix programs will be required for installation and at autoaips runtime: strings, grep, wget, python. Any modern Linux installation will certainly provide these. No guarantee on Solaris.

Get the latest version of autoaips: see the downloads section on http://www.astro.cornell.edu/~shami/psrvlb/.

  1. Download the .tar.gz file
  2. Extract : tar zxvf autoaips-version.tar.gz
  3. cd autoaips
  4. Take a look at the changelog in autoaips.c
  5. edit Makefile so that INSTDIR points to the desired installation directory.
  6. make install
    Note that you need write permission for INSTDIR.
Installation puts two files in INSTDIR: autoaips and ionex.py. If INSTDIR is not in your path (test by changing to a different directory and trying to run autoaips with no arguments) you need an environment variable IONEXPY pointing to ionex.py. For example, if INSTDIR is /home/aips/random:

	tcsh % setenv IONEXPY /home/aips/random/ionex.py
	bash $ IONEXPY=/home/aips/random/ionex.py
It is probably more convenient to add the above command to your .tcshrc/.bash_profile.

Return to top

2. Calibration strategy:

Autoaips generates scripts (all of the form X*.001) for the following calibration strategy:

  1. Load the data. Run fitld separately on each VLBA UVFITS file. Always concatenate the data sets.
  2. Delete provided NX table and rerun INDXR. This ensures that no scans are split into 2 by gaps caused by tape reversal.
  3. Mergecal (divided into 3 TAMRG calls) to combine the GC, TY, and PC tables from each of the FITS files.
  4. Run ACCOR to correct amplitudes based on autocorrelation values.
  5. Apply gain table to data (APCAL).
  6. Apply JPL (or other?) ionosphere data .
  7. Flag data with commands specified in the .x.N file (N=epochnum)
  8. Fringe fit the bandpass calibrator (and show fringe phases).
  9. Image the calibrator and self cal for a couple loops.
  10. Re-fringe the bandpass calibrator using model from 9.
  11. Self calibrate bandpass calibrator within the multi-source file
  12. Run BPASS to calculate the bandpass response.
  13. Show the results using POSSM.
  14. Fring fit and self calibrate the phase calibrators. A model of the calibrator is saved. (.MODEL)
The pulsar or in-beam calibrator is split out using this calibration.

Return to top

3. How to run autoaips:

AIPS uses environment variables to specify disk areas. You will need to use the same one when running autoaips.

Note that autoaips must be run separately for each correlation pass and each requires its own directory. Autoaips should be immune from file clobbering due to experiments with similar file or source names, as long as the experiment code differs.

Note also that ionex.py must be in your path (as above) to get the ionosphere models. If the data is already in the directory, this program is not needed.

Return to top

4. Autoaips output:

autoaips generates several files in the directory pointed to by <envvar>: 

	<expcode>.tablog	A file listing what each aips table is
				(a * means table modified, not created)
	XLOAD.001		The script that loads the FITS data
	XAPRIORI.001		The script that runs apriori calibrations
	XUVFLG.001		A replication of the flag commands in 
				XAPRIORI.001 for convenience
	XBPASS.001		A script to do a good job of band pass
				calibration.
	XPHASE.001		Script for phase calibration.  Single
				source files for the calibrators and target
				are made.
	XGEOD.001		An experimental geodesy calibration step
	XCOPY.001		Script to copy calibration tables from
				one correlation pass to another.  Must
				first set AIPS variable CALXFR
	jplg???0.0?i		One or more JPL ionex files
	autoaips.save		Currently just caches the source name, to
				speed up (tremendously) future runs of
				autoaips in that directory.

Return to top

5. How to run these scripts in AIPS:

Before entering AIPS, make sure the same environment variable used in step 3 is still pointing to the data directory. then start AIPS. Once aips is going, type 

VERSION = '<envvar>'
This allows aips to find the X*.001 scripts. Then just type 
RUN XLOAD
to get going. Once that is finished, keep following the instructions that are given.

Note that when running, aips will want to write data back to the directory, specifically the boxfiles used for image cleaning and any save files. Thus, if the data was distributed on CDROM, you should copy the contents to your hard disk. The XLOAD script writes nothing back to the disk, so it can be run off the CDROM, and then the non-FITS files can be copied to the hard disk for later steps if disk space is limited. Alternatively, the path to the data on read-only media can be specified with the <datapath> argument to autoaips.

The phase referenced target name will be <psrname>.SPLIT<n> for the pulsar, where <n> is the number of the phase calibrator used (the script will run for each phase calibrator). For the in-beam passes, the output file will be <psrname>.<m>.SPLIT<n>, where <m> is the in-beam number.

Return to top

6. CLEANUP and UVCLEANUP

Two procedures are defined in each RUNFILE:

CLEANUP -- goes through the current INDISK and deletes all files with extension XCALIB, I----*, UVTMP, IBM0** and it RECATs the disk. These extensions should be unique enough not to clobber any other data on the disk.

UVCLEANUP -- goes through and deletes all original (un-FXPOLed) multisource UV files. All files with extensions XPSR or XIB* will be deleted. These can be run safely at any time that AIPS is not running one of the autoaips RUNFILES. It is ill-advised to run UVCLEANUP between XLOAD and as this would require running XLOAD again.

Return to top

7. Customization

Most customization is done by adding to the .x file. Since customization and flagging will differ epoch-to-epoch, each epoch has a dedicated .x file, identified by the epoch number (.x.1, .x.2, etc).

A few bits of customization can be done, both before and after running autoaips. By default, autoaips uses refant = 4 (usually Kitt Peak). This can be changed either before autoaips is run by inserting a line 

refant = <ant number>
into the .x.N file, or by changing a line (obvious which!) in X*.001. It is recommended to use the first approach as this is less likely to cause inconsistencies.

The default bandpass calibrator is given by geod_cal_name1 in the .x.N file. Adding a line 

bpass_cal_name = <source name>
to the .x.N file will force it to use that instead. Known flags can also be inserted into the .x.N file. The AIPS task UVFLG is used to execute the flag. In the .x.N file place a command of the form: 
flag1 = bif=2;eif=2;bchan=12;echan=14;ante=10
flag2 = ante=5;basel=6
flag3 = bchan=1;echan=1
Make sure there are no spaces in the flag expression. All flags are initialized with no selection before being applied (ie, flagging adverbs are not cumulative).

Return to top

8. Calibration Copying

For many of the pulsar observations there will be two or more data sets that differ only in the way the target source (be that the pulsar or an in-beam calibrator) is correlated.

In these cases, when processing the second or third set of data, the fringing and bandpassing can be avoided by copying the BP, FG, SN, CL tables from an existing data set that is still loaded into AIPS.

For example, if BC123C inbeam pass #1 is already on disk, and BC123C inbeam pass #2 needs processing, all that needs to be done is: 

VERSION = 'BC123CIB2'
RUN XLOAD
RUN XAPRIORI
RUN XCOPY
XCOPY needs the variable CALXFR set to the class name of the source data set. This variable defaults to 'IB1' as all cases where XCOPY is needed can be done relative to the first in-beam calibrator.

XCOPY copies all needed tables to the destination data set (in this case in-beam set number 2) and splits out the target source with each of the phase calibrators present. XCOPY does the equivalent of XBPASS and XPHASE. XGEOD is only needed on one correlation pass, presumably the first.

Return to top

9. Additional notes

Sometimes an ionosphere file does not exist on the JPL server. In this case TECOR step should be run manually or not run at all and the CL version 4 should be copied to version 5.

If using a different refant or disk, rather than modifying all of the X*.001 files, it is highly recommended that the scripts are recreated with autoaips. The refant parameter is in the .x.N file.

Return to top

10. A complete example walkthrough: After this is run, the pulsar single source file is created and you are ready to do science.

Return to top, or return to the Pulsar Astrometry page.

Shami Chatterjee
shami at astro.cornell.edu
Last modified: 25 Nov 2003
 Valid HTML 4.0! Best viewed with Any Browser