Summary of Vlafiller Enhancement


                                     1. Motivation

         At the VLA it is often the case that flux density calibrator
         is not scheduled at precisely the same frequency as the gain
         calibrators and target sources. This is due to turning off
         Doppler tracking on the flux density calibrator.  This
         enhancement of the vlafiller will allow these spectral
         windows to be recognized as one and the same band as they
         should be. The way to achieve this is to add a tolerance to
         the freqquency and pointing so that any frequencies within
         the tolerance will be indicated by the same spectral window
         id and similarly with the pointing.

         Previously, in order to make the filling process work
         correctly, in the glish scripts one has to reassign the
         spectral window id ( DATA_DESC_ID) for some of the data
         records. For instance, in the glish scripts
         ngc7538_regTest.g( this is one of the regression test code ),
         we have the following code for this purpose:

             x:=table('n7538.ms', readonly=F); ddi:=x.getcol('DATA_DESC_ID');
             ddi[ddi==0] := 2; ddi[ddi==1]:=3; x.putcol('DATA_DESC_ID',ddi);
             x.flush(); x.done();

          Now after this enhancement, the above glish code is no more
          needed if you pass in a proper tolerance for the frequency
          into vlafillerfromdisk(). As a matter of fact, they may
          cause some error in the filling process if in the meantime
          you are using a tolerance.

                        2. Criteria for Spectral Window Match

          When two spectral window( one from source and one from
          calibrator ) should be regarded as the same?  The following
          five criteria are used in the Vlafiller ( they are all
          columns in the SPECTRAL_WINDOW subtable of MeasurementSet ):
          a. NUM_CHAN:: number of spectral channels;
          b. TOTAL_BANDWIDTH: the total band width for a spectral
          window; c. IF_CONV_CHAIN: the IF conversion chain, which is
          used to distinguish the separate electronic paths for
          simultaneous observations at multiple frequencies.
          d. REF_FREQUENCY: reference frequency. It is a frequency
          representation of a spectral window, usually the sky
          frequency corresponding to the DC adge of the baseband.  If
          the two frequencies in comparison are not related to the
          same reference frame ( thus having different MEAS_FREQ_REF),
          they have to be converted to the same reference frame before
          comparison.  Alternatively, we can use the channel
          frequencies in place of the reference frequency. The default
          value of the tolerance of frequency has been set to that of
          the channel width of the current spectral window.

          Due to the variety of the dataset quality, some dataset
          requires a larger tolerance for frequeny in order to
          recognize the same spectral window. So besides the default
          tolerance for the frequency, we also give the user the
          posibility to pass in a proper tolerance according to the
          specific dataset. As a rule of thumb, executing the filling
          script first with the default tolerance and examing the
          generated SPECTRAL_WINDOW subtable of MS will give you a
          good hint about what is the right tolerance for the
          frequency to use. For instance, for dataset G192, the proper
          tolerance for frequency is about 6 times of its channel
          width( see the glish test script g192_testTolerance.g ),
          while for dataset NGC7538, a much larger tolerance, 60 times
          of its channel width, ( see the glish test scripts
          ngc7538_testTolerance.g ) is required in order to recognize
          the two related frequencies as the same spectral window.

                        3. Criteria for Pointing Match

          Since in the POINTING subtable, the same target source can
          appear more than once if it is observed at different
          time. So the subtable we need to look at is actually the
          FIELD subtable. Since the SOURCE_ID in the FIELD subtable is
          a foreign key and related to the primary key in the SOURCE
          subtable, so we also need to deal with SOURCE subtable.  The
          first thing to check is to see if the two fields have
          different field-name. Then we compare the following columns
          of the FIELD subtable for the two fields in comparison:
          a. DELAY_DIR: direction of delay center; b. PHASE_DIR:
          direction of phase center; c. REFERECE_DIR: direction of
          reference center.

          The tolerance for two direction to be recognized as same is
          set to 10.0mas in the Vlafiller.


                        4. Code Example Using Tolerance for Frequency

          a. How to determine the right value for the freqTolerance
             parameter?  Executing the filling script first with the
             default tolerance and examing the generated
             SPECTRAL_WINDOW subtable of MS ( especially, looking at
             the values of the REF_FREQUENCY column ) will give you a
             good hint about what is the right tolerance for the
             frequency to use.

          b. Passing in a value to the freqTolerance parameter.  The
             following code shows how a user can pass in a tolerance
             for the frequency matching.

   vlafillerfromdisk(filename='data/G192/AS758_C030425.xp1',msname='g192_a.ms',
             overwrite=T,bandname='K',async=F,
             freqTolerance=150000.0);

          where the parameter freqTolerance is a double and the
          tolerance is in the unit of Hz.