; QUFIX
;---------------------------------------------------------------
;! determines Right minus Left phase difference, corrects cal files
;# Task UV Calibration polarization SPECTRAL
;-----------------------------------------------------------------------
;;  Copyright (C) 2011
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
QUFIX     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
QUFIX:  Task to apply Right - Left phase difference
INNAME                             UV data (name)
INCLASS                            UV data (class)
INSEQ             0.0    9999.0    UV data (seq. #)    0 => high
INDISK                             UV data Disk unit #  0 => any
IN2NAME                            Good image (name)
IN2CLASS                           Good image (class)
IN2SEQ             0.0    9999.0   Good image (seq. #)   0=>high
IN2DISK                            Good image disk unit   0=>any
IN3NAME                            Uncal image data (name)
IN3CLASS                           Uncal image (class)
IN3SEQ             0.0    9999.0   Uncal image (seq. #)  0=>high
IN3DISK                            Uncal image disk unit 0=>any
PCUT               0.0             Use only Q,U values > PCUT
                                   in total polarization
NBOXES             1.0     50.0    Number of boxes for averaging
CLBOX             -2.0   16384.0   Four coordinates for each box
CALIN
                                   Text file with corrections
OUTTEXT
                                   Text file w corrections
                                   not blank => do not apply
----------------------------------------------------------------
QUFIX
Type:  Task
Use:   Performs the function of RLDIF to correct the BP, CP, and PD
       tables in a spectral-line data set.  These tables are produced
       by BPASS and PCAL but are on separate phase references in the
       two polarizations.  This matters to cross-hand data.  The best
       way to correct this problem is with RLDIF.  But that requires a
       calibration source for which the Q and U spectrum or at least
       the polarization position angle as a function of frequency is
       well known.  3C286 is a good calibration source at all
       frequencies, but 3C48, for example, has significant, but poorly
       known polarization behavior at low frequencies and 3C147 has no
       polarized signal at these same frequencies.

       If you have images of a source which are well calibrated in Q
       and U and wish to correct data from another day that lacks the
       polarization position angle calibrator, QUFIX offers a
       solution.  It compares two 4-dimensional images (Ra, Dec, freq,
       Stokes) to determine the rotation angle which will align the Q
       and U on average as a function of channel.  This angle may be
       written out in a text file or simply applied to the tables of a
       UV data set.

       QUFIX offers the option of reading in a text file of
       corrections determined from a previous run of QUFIX or from any
       other method the user may devise.  In that case, it does not
       require or use the two image 4-cubes.

       If your image is of a source with a spatially constant
       polarization angle (e.g. a point source), then QUOUT and RLDIF
       are better solutions for you.  QUFIX is better used in the case
       of complex sources with spatially variable polarization
       position angle.
Adverbs:
           ****  Data set with tables to be corrected  ****
  INNAME......UV file name (name).       Standard defaults.
  INCLASS.....UV file name (class).      Standard defaults.
  INSEQ.......UV file name (seq. #).     0 => highest.
  INDISK......Disk unit #.               0 => any.
           ****  Well-calibrated Stokes-spectral cube  ****
  IN2NAME.....Image file name (name).       Standard defaults.
  IN2CLASS....Image file name (class).      Standard defaults.
  IN2SEQ......Image file name (seq. #).     0 => highest.
  IN2DISK.....Disk unit #.               0 => any.
           ****  Calibrated but not RLDIF Stokes-spectral cube  ****
  IN3NAME.....Image file name (name).       Standard defaults.
  IN3CLASS....Image file name (class).      Standard defaults.
  IN3SEQ......Image file name (seq. #).     0 => highest.
  IN3DISK.....Disk unit #.               0 => any.
           ****  control parameters ****
  PCUT........If determining the corrections from images, use only
              pixels having SQRT (Q*Q + U*U) > PCUT in both image
              cubes.
  NBOXES......Number (<=50) of rectangular or circular boxes to search
              in all Ra-Dec planes.
  CLBOX.......A 4x50 array with the parameters of each box.
              CLBOX(1,i)=-1 indicates a circle of radius CLBOX(2,i)
                 pixels centered on (CLBOX(3,i), CLBOX(4,i)).
              CLBOX(1,i) >= 0 indicates a rectangular box.
  CALIN.......Text file containing the corrections as angles in
              degrees. - see below for format details.
              If CALIN is not blank, the 2nd and 3rd images will be
              ignored and the contents of CALIN used.
  OUTTEXT.....Text file output containing the corrections.  If OUTTEXT
              is not blank, it will be used and no corrections will be
              applied to UV extension tables (first UV file ignored
              entirely).

NOTES:
   1. Images 2 and 3 must be aligned in all axes.
   2. Images 2 and 3 (or CALIN) do not have to be aligned in
      frequencies with the UV data set.  The corrections will be
      interpolated to the UV data set frequencies.
   3. CALIN must be in strict increasing frequency order.

CALIN file format:
   1. Comment lines at any point begin in column 1 with either a
      ; or a # character.
   2. Data lines contain the specified type of data columns:
         frequency in GHz, polarization angle in degrees

Example:
;FAS
# QUOUT run 12-JAN-2011 11:27:03 using CP version    2
# source is 3C286 with constant pol angle 33
# changed to corrections by 2 * (33 - pos ang)
#
# 4.988000000    32.97708      0
  4.988000000     0.04592
# 4.990000000    32.97708      0
  4.990000000     0.04592
# 4.992000000    33.01998      0
  4.992000000    -0.03996
# 4.994000000    33.12441      0
  4.994000000    -0.24882
# 4.996000000    33.31594      0
  4.996000000    -0.63188
# 4.998000000    33.39096      0
  4.998000000    -0.78192
----------------------------------------------------------------
