12.6 Adding your own tasks to

This Section is a brief guide for the user who wants to modify an existing task in  or to write a new task. While it is difficult to write an  task from scratch,  contains several template tasks that are designed to hide most of the work from the “occasional” programmer. Anyone familiar with FORTRAN and a little of the system services of their local computer should be able to add convenient tasks to their local version of  with a little practice and patience. The growing use of binary installations makes this more difficult since local sites are unlikely to have the relevant compilers.

12.6.1 Initial choices to make

The simplest way to write an  task is to modify one of the four template tasks, TAFFY, CANDY, FUDGE, OFUDG, or UVFIL. These tasks handle the  I/O, contain extensive documentation, need to be modified in only a few well-defined places, and can be easily interfaced to user subroutines. They are limited in their ability to handle many input and output images, however, and generally operate on one image row or one visibility point at a time. Softening of these limitations will be discussed in §12.6.5.

TAFFY — This template task reads an existing image in  line by line, modifies the line of data as desired and then creates and writes the modified image in . This template task might, for example, be used to blank pixels in an input image in some specified manner.

CANDY — This task is similar to TAFFY except the input data are contained in an auxiliary file which is FORTRAN readable and outside . The task can transfer an image in any reasonable format outside  into the  data structure.

FUDGE — This template task reads an existing  uv database optionally applying calibration, editing, and data selection, modifies the results point by point, and then creates and writes this modified output uv database in the  catalog. This template task might, for example, be used to modify a uv data base for which the time parameter has been incorrectly written. OFUDG is an older version of FUDGE which omits all the complications of the calibration system.

UVFIL — This task is similar to FUDGE without calibration and editing, except that the input uv data are contained in one or two auxiliary files, which are FORTRAN readable and outside . The task is useful for translating visibility data in an arbitrary format into an  cataloged uv data set, or for computing a uv data set from model sources.

If you wish to make a minor change in an existing  task, it will be simpler to copy the  task itself and modify it as needed. For example, if you wanted to add a option in COMB to combine two input images in a new way to obtain a resultant image, it would be better to start with COMB itself than with one of the templates. However, non-trivial changes to major tasks will require a careful look at the code, which is generally well documented and segmented.

Changes to tasks that make plots and/or use the TV and other graphics devices can be tricky, but are useful sometimes. Changes to imaging and deconvolution software should not be attempted unless the changes are almost trivial. Modifying existing verbs or creating new ones require you to find which AUxx.FOR routine is involved and then require the entire AIPS program to be re-linked. Going  describes some of the considerations. The new pseudo-verbs VERB and PSEUDOVB allow you to update your AIPS vocabulary using your own procedure rather than by changing the supplied vocabulary files and executing POPSGN as described in Going . In all cases, do not put your modified code into the standard  code areas unless your local  Manager agrees and has made a backup copy of the original code and executables. Such modified files may well disturb the  updates done by the so-called “Midnight Job.”

12.6.2 Getting started

Even if you have special privileges in , it is wise to generate and link new code in your own user directory rather than in your installation’s designated local  directory. After the code has been written and tested, check with your local  Manager about installing it in a public area. Decide which template task or other  task you want to modify, then follow these instructions after logging into your private area.

Under Unix

12.6.3 Initial check of code and procedures

Before modifying the task in any way, it is wise to compile, link and execute the unchanged task to check that the original code is sound and that all of the  logical assignments have been properly set. The duplicated  task should run identically to the original; the template tasks are set up to duplicate the input data set with no changes and default parameters. In this way errors or other problems associated with the generation of new tasks can be found and corrected before getting into the quagmire of bugs that you are about to add. Note that CANDY and UVFIL require external data files and are therefore not so easily checked.

One change is needed in the FORTRAN program before checking. In the main program, about 60 lines down, there is a data statement which identifies the task.

Change this to

The maximum number of characters in a task name is five and the DATA statement must be in the above form. There is no need to change the help file yet, as long as it is named NTASK.HLP.

To compile and link the task, type:

To compile the task for debugging, add the DEBUG NOOPT options to the COMLNK line. There should be no error messages and no significant warnings.

After successful compilation and linking, try executing the task. Under Unix, stay logged in to your area. To initiate the AIPS program, type:

Your  Manager may have to make some arrangements for you to activate  from your login. Once you have started , type

Set up the input parameters, then

12.6.4 Modifying an  task

If you are modifying an existing task, the only ground rules are to read the task carefully and note the locations where changes must be made. Unlike the template tasks which are organized so that additional code need be inserted in only one or two places, an  task may need revisions in a variety of places. Some guidelines are:

1. Change the data statement DATA PRGM … near the beginning of the program and the PROGRAM statement at the very beginning, if you have not already done this.
2. Make changes in the introductory text which describes the task. This is particularly important if you are adding or removing adverbs.
3. The subroutine GTPARM obtains the adverb values from the input table in order. If you add or subtract adverbs, change INPRMS, the amount of input information. Be careful in the translation of the adverbs, which are usually listed in a COMMON named /INPARM/.
4. Change code as desired. Try to modify HIstory file entries as well.
5. Liberally sprinkle PRINT statements in crucial places to help debug the program. If much of the new code can be put in a subroutine, write and debug the subroutine outside . Then, add it to the task.
6. Revise the file NTASK.HLP. At least, change all references to TASK to NTASK! If there are any changes in the adverb list, look at these changes carefully. Further changes in the HELP and EXPLAIN portions of the file may be needed to document your work for for others and for yourself at a later date.
7. Compile and link the modified task following the instructions in the previous section. When it compiles and links without errors, try it out in .

12.6.5 Modifying an  template task.

The template tasks are:

1. TAFFY — modifies an existing image file and writes a new image.
2. CANDY — writes a new image. Input data from outside .
3. FUDGE — modifies an existing uv database and writes a new database with calibration, flagging, source selection, etc.
4. OFUDG — modifies an existing uv database and writes a new database.
5. UVFIL — writes a new uv database taking input data from outside .

These tasks are described in detail in Chapter 2 of Going . The template tasks and the code for each are extensively documented there, so only the major points are discussed here.

TAFFY reads a selected subset of an image, one row at a time, to a user interface subroutine DIDDLE. An output image is created, cataloged and filled with values calculated in DIDDLE (or attached subroutines). The dimensionality of the output image need not be the same as the input image.

1. If the output image has identical dimensions to the input image, and an output image row can be generated from each input image row, then TAFFY is relatively straight-forward to use and the accompanying documentation should suffice.
2. TAFFY has the option of deferring the writing of an output row until some number of input rows have been read. This would allow the output to depend on some function of several, or even all, input rows. Examples would include smoothing in x and y and other sorts of spatial filtering.
3. It is possible to handle several input images and several output images with TAFFY by using multi-dimensional images and the axis transposing task, TRANS. Suppose you want to calculate the spectral index from a set of four images. First, use FQUBE to put the four images into one data cube. (FQUBE lets you avoid re-defining the frequency axis as MCUBE would require.) Then, transpose the cube so that the frequency axis is first with right ascension and declination as the second and third axes. Use this image as the input to TAFFY and use CPARM to specify the frequency values. Each input row will then be the intensity at a pixel for the four frequencies — from which the spectral index and other parameters can be calculated. The output dimension can be specified arbitrarily. For example, you might want to write out the spectral index, the error, the curvature and the flux intercept at some fiducial frequency. When the task has completed, transpose the output cube so that the celestial coordinates are again the first two axes and the spectral index and friends are the third axis.
4. Subroutine NEWHED may be modified to require certain axis types, operation codes, etc. It must be used to change the output image dimensions if they are not to be the same as the input. An option to omit from the output image the first input axis is available and must be selected in NEWHED.
5. If you can write and debug outside  any subroutines that DIDDLE will call in calculating the output image, you may speed up the debugging of your algorithms.

CANDY lets you create an image one row at a time. Input information is obtained through a file which is external to .

1. Subroutine NEWHED shows an example of how the external file may be defined and how it can be used. The first few records of the external file should contain information for defining the header of the output image and updating the appropriate catalog blocks. The pointers to the  catalog are given in Chapter 5 of Going .
2. The subroutine MAKMAP reads further records from the external file until a full row of the output image is obtained.
3. Many adverbs are built into CANDY. If you need more or wish to change them, read the information at the beginning of subroutine CANIN.

OFUDGE reads an existing uv database point by point and creates a new uv database with the modified data. It can easily be used to make simple changes in a uv database; for example, if the u, v, or w terms are to be recalculated, if all phases are to be changed in sign, etc. FUDGE does the same but with the full set of calibration, flagging, source selection, etc. adverbs.

1. If the output data set has different dimensions than the input data set (e.g., by combining several spectral-line channels), changes must be made in the subroutine FUDGIN.
2. To combine several input data points, use the task UVSRT to put the data points adjacent in the file.
3. If you wish to calculate quantities from an input uv data set without creating an output file, use this task. In the subroutine DIDDLE set IRET = -1 to avoid writing an the output uv data set.

UVFIL reads input from one or two FORTRAN-readable files which are outside  to create, catalog, and fill a uv database into . This task is useful for transcribing uv data in an arbitrary format into an  database.

1. The task code has copious notes to help the user. The first auxiliary file should contain header information about the observations and the telescopes. This file is read in the subroutine NEWHED.
2. The second auxiliary file contains the actual uv data in some format and it is converted into an  uv database, point by point, in the subroutine FIDDLE. The comments are extensive and an example is given in the code.

12.6.6 Further remarks

1. Try to use the  coding standards as described in Going . This will make your code more readable and more portable. It will also save other  programmers lots of work if your new task comes into general use.
2. Declare all variables that you use.
3. While debugging, use the FORTRAN PRINT *, ... statement in your code to obtain temporary output on your terminal during execution. If you want more permanent output, use the  message file facilities with the appropriate message level (4 is recommended for information, 6 for warnings, 8 for errors).
4. You may use a debugger (such as dbx) on  tasks by specifying DEBUG to the COMLNK and aips procedures. Inside AIPS, set the “hidden” adverb SETDEBUG to 0 for normal operation and to 20 to run tasks with your specified debugger.