4.7 Spectral-line calibration

The calibration of spectral-line data is very similar to that of continuum data with the exception that the antenna gains have to be determined and corrected as a function of frequency as well as time. The model used by AIPS is to determine the antenna gains as a function of time using a pseudo-continuum (“channel-0”) form of the data. Then the complex spectral response function (“bandpass”) is determined from observations of one or more strong continuum sources at or near the same frequency as the line observation. In general, the channel-0 data are calibrated using the recipes in the previous sections of this chapter. The sub-sections below are designed to bring out the few areas in which spectral-line calibration differs from continuum.

4.7.1 Reading the data

If your data are on a VLA archive tape then they should be read into AIPS using FILLM, as described in 4.1.1. FILLM will fill a typical line observation into two files, a large one containing the line data only, and a smaller file containing the “channel-0” data. (Note that FILLM computes channel-0 from the line data rather than using the channel-0 provided by the on-line system.) The standard calibration and editing steps are performed on channel 0 and the results copied over to the line data set. You must be careful with the tolerance you allow FILLM to use in determining the FQ numbers. If you desire all of your data to have the same FQ number, so that you can calibrate it all in one pass, then set CPARM(7) in FILLM to an appropriately large value. If you wish to retain spectral-line autocorrelation data, you must set DOACOR to true.

By default for the VLA, the channel-0 data are generated by the vector average of the central 3/4 of the observing band. If this algorithm is not appropriate for your data, you may generate your own channel-0 data set by averaging only selected channels. You may now select different spectral channels in different IFs. To do this, use the task AVSPC:

> TASK AVSPC  C R

> INDI n ; GETN m  C R

to specify line data set.

> OUTDI i ; OUTCL ’CH 0’  C R

to specify output “channel-0” data set disk and class.

> ICHANSEL 10, 30, 1, 0, 31, 55, 2, 1  C R

for example, to average every channel between 10 and 30 in all IFs and also every other channel between 31 and 55, but only in IF 1.

> GO  C R

to create a new channel-0 data set.

You might find this necessary when observing neutral hydrogen at galactic velocities. Most calibrator sources have some absorption features at these frequencies.

4.7.2 Spectral-line aspects of SETJY

The LISTR output with OPTYPE = ’SCANwill show information from the source table including spectral-line parameters. VLA data from FILLM are normally supplied with adequate information regarding the source velocity, line rest frequency, and velocity reference (radio versus optical, LSR versus barycentric). However, data from the EVLA and other telescopes may be missing these parameters. SETJY must then be used to fill in the needed values. In 31DEC12, a new OPTYPE=’VCAL’ option computes the velocity of the reference channel from first principles. It is recommended over inaccurate guesses of adverb values in other SETJY OPTYPEs. It may be run over all sources after the rest frequencies and velocity reference information has been filled in.

4.7.3 Editing the data

You should follow the steps outlined in 4.4 to edit the calibrator data using the channel-0 data set. Even though channel-0 data is continuum, be careful to have TVFLG and UVFLG generate the flagging commands for all channels, not just channel 1. Then, copy the resulting FG table to the line file. Use TACOP:

> TASK TACOP  C R

> INDI n ; GETN m  C R

to specify channel-0 data set.

> OUTDI i ; GETO j  C R

to specify the line data set.

> INEXT ’FG’  C R

to copy the FG table.

> INVER 1  C R

to copy table 1.

> NCOUNT 1  C R

to copy only one table.

> OUTVER 1  C R

to copy it to output table 1

> INP  C R

to review the inputs.

> GO  C R

to run the program when inputs set correctly.

Specifying the “ALL-CH” setting in TVFLG and specifying BCHAN 1 ; ECHAN 0  C R in UVFLG cause all channels to be flagged when the FG table is copied to the line data set.

Spectral-line observers should also use SPFLG (10.2.2) to examine and, perhaps, to edit their data. This task is very similar to TVFLG described in 4.4.3, but SPFLG displays spectral channels for all IFs on the horizontal axis, one baseline at a time. If you have a large number of baselines, as with the VLA, then you should examine a few of the baselines to check for interference, absorption (or emission) in your calibrator sources, and other frequency-dependent effects. Use the ANTENNAS and BASELINE adverbs to limit the displays to a few short spacings and one or two longer ones as well. If there are serious frequency-dependent effects in your calibrators, use SPFLG and UVFLG to delete them. (You might wish to delete the FG table with EXTDEST to begin all over again.) Then use AVSPC to build a new channel-0 data set and repeat the continuum editing. Note that you should not copy the FG table from the spectral-line data set to the new continuum one. The reason for this is the confusion over the term “channel.” If you have flagged channel 1, but not all channels, in the spectral-line data set — a very common occurrence — then a copied FG table would flag all of the continuum data since it has only one “channel.” When you have flagged the channel-0 data set, you can merge the new flags back into the spectral-line FG table with task TABED.

> TASK TABED  C R

> INDI n ; GETN m  C R

to specify channel-0 data set.

> OUTDI i ; GETO j  C R

to specify the line data set.

> INEXT ’FG’  C R

to copy the FG table.

> INVER 1  C R

to copy table 1.

> OUTVER 1  C R

to copy it to output table 1.

> BCOUNT 1 ; ECOUNT 0  C R

to copy from the beginning to the end.

> OPTYPE ’COPY’  C R

to do a simple copy appending the input table to the output table.

> TIMER 0  C R

to copy all times.

> INP  C R

to review the inputs.

> GO  C R

to run the program when inputs set correctly.

If the channel-0 data set is meaningful for your program sources, you might consider doing a first-pass editing of them along with your calibrators before copying the FG table back to the line data set. If your program sources contain significant continuum emission, then this is a reasonable operation to perform. If they do not, then the standard channel-0 data set is not useful for editing program sources. You can use SPFLG to edit all channels, or if the signal is strong in a few channels, you could run TVFLG on those channels from the spectral-line data set or average those with the BCHAN, ECHAN, and NCHAV adverbs.

4.7.4 Bandpass calibration

The task BPASS is designed to take visibility data from specified calibrator(s) to determine the antenna-based complex bandpass functions. It does this in a manner analogous to self-calibration in that the data are divided by a source model or the so-called “channel 0” before the antenna gains are determined as a function of frequency. These are written to a BandPass (BP) table. The bandpass calibration is the first operation that should be performed on the line data. So long as one uses the mode in which the data are divided by the so-called “channel 0,” it is not necessary to calibrate the data before estimating the bandpasses.

> TASK BPASS  C R

> INDI i ; GETN j  C R

to specify the line data set.

> CALSOUR cal1’ , ’cal2’ ,  C R

to specify bandpass calibrators.

> FREQID 1  C R

to select which FQ value to use.

> ANTENNAS 0  C R

to solve for all antennas.

> REFANT n  C R

to set the reference antenna number.

> DOCALIB FALSE  C R

to avoid applying calibration.

> BPASSPRM 0  C R

to turn off all “parameters.”

> BPASSPRM(5) 0  C R

to divide by channel 0 on a record-by-record basis before determining antenna-based bandpasses. Other normalization options are available and may be preferred.

> IN3DI a ; GET3N b  C R

to specify the channel 0 data file, or

> CLR3NAME  C R

to have channel 0 found from the input data themselves.

> ICHANSEL 20 50 1

to use the average, in each IF, of all channels from 20 through 50, for example, to determine channel 0, when the third input file name is empty.

> FLAGVER 1  C R

to apply flag table 1.

> SOLINT 0  C R

to use scan averages.

> BPVER 1  C R

to select the output BP table number.

> INP  C R

to review the inputs.

> GO  C R

to run the program when inputs set correctly.

Be careful with the adverb SMOOTH. If you smooth, or do not smooth, the data while finding a bandpass solution, then you must apply the same SMOOTH adverb values whenever you apply that bandpass solution to the data. The only exception is that you may smooth the data after applying the bandpass solution with SMOOTH(1) values 5 through 8 when you did no smoothing in BPASS.

The stored bandpass correction table should be corrected for the spectral index of the calibration source. Use adverbs SPECINDX and SPECURVE to describe the spectral index to BPASS and new task SOUSP to find the spectral index values from the fluxes in the source table. BPASS knows the flux coefficients for all standard calibration sources and, in 31DEC13, can fit the spectral index of other calibration sources from the SU table. It can handle spectral inices for multiple calibration sources at one time, although the adverbs apply of necessity only to the first such source.

The divide by channel 0 option is very convenient in that it allows one to ignore both source structure (when the bandwidth is narrow enough) and continuum calibration. However, the average of some channels on a record-by-record basis can be rather noisy and the “division” operation is actually a subtraction of the average phase and a division by the average amplitude. The latter suffers from a “Ricean” bias — the average amplitude will always be larger than the correct amplitude, averaging one rms larger. Therefore, if the continuum calibration is stable (or already known and able to be applied) and the source structure is negligible, then it would be better to defer the normalization (on a baseline by baseline basis) until the data are averaged over SOLINT or, better still, to defer the normalization (on an antenna basis) until the unnormalized solutions are determined. BPASSPRM(5) and BPASSPRM(10) control the normalization options. Do note also that, with no normalization, BPASS is capable of replacing any use of CALIB including calibration of the data weights.

The spectral quality of the final images has been found to be determined in part by the quality of the bandpass solutions. In particular, for reasons which are not yet known, the bandpasses are not exactly antenna dependent especially in the edge channels. This “closure error” may be measured in individual and statistical ways by BPASS and reported to you. To check on this problem for your data set, set

> MINAMPER a  C R

to count and, if BPASSPRM(2)> 1, to report amplitude closure failures > a per cent. Note that closure errors are accumulated as logarithms so that 0.5 and 2.0 are both errors of 100%.

> MINPHSER p  C R

to count and, if BPASSPRM(2)> 1, to report phase closure failures > p degrees.

> BPASSPRM(2) 1  C R

to report statistics of amplitude and phase closure failures without reporting individual failures.

> BPASSPRM(6) a  C R

to report all channels in which the average amplitude closure error > a per cent.

> BPASSPRM(7) p  C R

to report all channels in which the average phase closure error > p degrees.

> SOLTYPE ’R’  C R

to select robust solutions which discard data with serious closure problems. Try other types if there are solution failures.

It is probably a good idea to set MINAMPER and MINPHSER fairly high (i.e., 20 and 12) to make a big deal only about major excursions, but to set BPASSPRM(6) and (7) fairly low (i.e., 0.5 and 0.5) to view the spectrum of closure errors (which will look a lot like the spectrum of noise on your final Clean images). There is even a task called BPERR which will summarize and plot the error reports generated by PBASS and written to text files by PRTMSG.

The bandpass solutions are calculated at each bandpass calibrator scan. As a consequence, they are likely to be unevenly spaced in time and may even have times (due to on-line or later editing) at which there are solutions for some IFs and polarizations but not all. When the latter happens, program source data will be lost unless the missing solutions are filled in. The task BPSMO may be used for this purpose or to create a new BP table at regular time intervals using one of a number of time-smoothing functions. Set APARM(4) = -1 for the “repair” mode or set APARM(4) to the desired BP interval.

After the bandpasses have been generated, you can examine them using tasks BPLOT and POSSM. You can obtain an average from all antennas with

> TASK POSSM  C R

> INDI i ; GETN j  C R

to specify the line data set.

> SOURCES cal1’ , ’cal2’ ,  C R

to specify the bandpass calibrators.

> ANTENNAS 0  C R

to include all antennas.

> TIMER 0  C R

to average over all times.

> BCHAN 1 ; ECHAN 0  C R

to display all channels.

> BPVER 1  C R

to select the BP table.

> FREQID 1  C R

to set the FQ value to use.

> APARM = -1, 0  C R

to do a scalar average and have the plot self-scaled and labeled in channels.

> APARM(8) 2  C R

to plot BP table data.

> NPLOTS 0  C R

to make one plot only, averaging all included data.

> INP  C R

to review the inputs — check closely.

> GO  C R

to run the program when inputs set correctly.

> GO LWPLA  C R

to send the plot to the (PostScript) printer/plotter.

To view each antenna individually, using the TV to save paper

> DOTV TRUE  C R

to use the TV.

> NPLOTS 1  C R

to plot one antenna per page/screen.

> GO  C R

to display the bandpasses, averaged over time, on the TV with one antenna per screen.

POSSM shows each screen for 30 seconds before going ahead. You can cause it wait indefinitely by hitting button A, speed it up by hitting TV buttons B or C, or tell it to quit by hitting button D. If DOTV = -1, then POSSM makes multiple plot extension files, which can be sent to the printer (individually or collectively) by LWPLA. You might want to use a larger value of NPLOTS to reduce the number of pieces of paper.

BPLOT is used to create one or more plots (on the TV or in plot files) of the selected bandpass table. The plots will be a set of profiles separated on the vertical axis by an increment in time or antenna number (depending on the sort selected). More than one plot for more than one antenna or more than one time may be generated. Multiple IFs and polarizations will be plotted along the horizontal axis if they are present in the BP table and selected by the adverbs. Thus, BPLOT is useful for plotting the change in bandpass shape as a function either of time or of antenna.

In 31DEC16, task BPEDT offers a TV-inteactive graphical way to check your BP table. It displays the amplitude and phase of one antenna to be edited and up to 10 more antennas for comparison. The task is like EDITA except that the horizontal axis is spectral channel rather than time. You may walk through the entire bandpass table selecting the editable antenna and time in sequence. If some of the solutions show residual effects from RFI, then you may generate flags in a flag table to delete certain spectral channels for certain antennas and times. If you do this, of course, you should re-run BPASS applying the new flags.

The BP tables are applied to the data by setting the adverb DOBAND > 0 and selecting the relevant BP table with the adverb BPVER. There are three modes of bandpass application. The first (DOBAND 1) will average all bandpasses for each antenna within the time range requested, generating a global solution for each antenna. The second mode (DOBAND 2) will use the antenna bandpasses nearest in time to the data point being calibrated. The third mode (DOBAND 3) interpolates in time between the antenna bandpasses and generates the correction from the interpolated data. This mode has been found to be required for VLA data. If BPSMO was used to make a fairly finely sampled BP table, then DOBAND 2 may be used. Modes DOBAND 4 and DOBAND 5 are the same as modes 2 and 3, respectively, except that data weights are ignored.

It is often not possible to observe a strong bandpass calibrator many times during a run. In this case, one can run BPASS on the single scan on the strong calibrator and then remove the main bandpass shape with DOBAND 1 in task SPLAT. Corrections to this basic bandpass shape as a function of time may then be determined with adequate signal-to-noise using task CPASS. This task can be used to fit the residual bandpass with a small number of parameters (<< the number of spectral channels) at each calibrator scan. The results may then be applied with DOBAND 2. Check the output of CPASS carefully — it is capable of making bandpass shapes with large ripples that are not present in the data. CPASS also knows about the flux coefficients of all standard sources and can fit the spectral index of other sources from the flux values in the SU table.

4.7.5 Amplitude and phase calibration

The channel-0 data set should be calibrated as described above for continuum data (4.4 and 4.5). When you are satisfied with your results, you should copy the relevant CL table over to the line data set with TACOP:

> TASK TACOP  C R

> INDI n ; GETN m  C R

to specify the channel-0 data set.

> OUTDI i ; GETO j  C R

to specify the line data set.

> INEXT ’CL’  C R

to copy a CL table.

> INVER 0  C R

to copy highest numbered table from CLCAL step.

> NCOUNT 1  C R

to copy only one table.

> OUTVER 0  C R

to create new output table.

> INP  C R

to review the inputs.

> GO  C R

to run the program when inputs set correctly.

If you copy SN, TY, or SY tables, you may apply a flagging table to the table values.

At this point it is often useful to examine your fully calibrated data using POSSM:

> TASK POSSM  C R

> INDI i ; GETN j  C R

specify line data.

> SOURCES source1’ , ’ ’  C R

to specify the source of interest.

> ANTENNAS 0  C R

to plot all antennas.

> BCHAN 10 ; ECHAN 55  C R

to plot spectrum for this channel range only.

> DOCALIB 1  C R

to apply the antenna gain to both visibilities and weights (if appropriate). calibration.

> GAINUSE 0  C R

to use most recent CL table.

> DOBAND 3  C R

to apply the bandpass calibration time smoothed.

> BPVER 1  C R

to use BP table 1.

> FREQID 1  C R

to use only one FQ value.

> APARM 0  C R

to do vector averaging of amplitudes and self-scale the plots.

> SMOOTH 5 , 0  C R

to apply Hanning smoothing in the spectral domain after bandpass calibration is applied. Use 13,0 to smooth after the data are averaged, which is faster and less prone to oddities due to channel-dependent flagging. Use 1,0 only if the data were Hanning smoothed when BPASS was run.

> INP  C R

to review the inputs.

> GO  C R

to run the program when inputs set correctly.

> GO LWPLA  C R

to send the plot to the (PostScript) printer/plotter.

If you have multiple FQ entries in your data set, you should repeat the calibration for each additional FQ entry. Bookkeeping is simplified if you eliminate all extant SN tables before calibrating the data associated with each frequency identifier. However, it is not essential to do this.