; POLCO
;---------------------------------------------------------------
;! Task to correct polarization maps for Ricean bias
;# TASK POLARIZATION
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1997, 2009
;;  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
;-----------------------------------------------------------------------
POLCO     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
POLCO: Task to correct polarization maps for Ricean bias
INNAME                             Input image name (name)
INCLASS                            Input image name (class)
INSEQ           0.0      9999.0    Input image name (seq. #)
INDISK                             Input image disk drive #
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ          0.0      9999.0    Output image name (seq. #)
OUTDISK                            Output image disk drive #
PIXSTD          0.0      9999.0    Sigma of noise on Q or U map
PCUT            0.0                Blank below PCUT sigma.
                                   <= 0 => no blanking
OPCODE                             If 'ZERO', blank with zeros,
                                   else use magic blanking
BADDISK                            Disks to avoid for scratch
----------------------------------------------------------------
POLCO
Type: Task
Use:  POLCO is a task to correct total polarized intensity (P) images
      for the bias introduced when combining the Stokes Q and U images
      which are assumed to have a noise distribution obeying Gaussian
      statistics with a standard deviation sigma.  The P image obeys the
      Rice distribution, and at high signal-to-noise, Gaussian
      statistics are approached (see Vinokur, Ann. d'Ap., 1965, 28,
      412).  One needs to estimate the intrinsic polarized intensity
      (Pint) given an observed polarized intensity (Pobs).   If Pint=0,
      then the bias in the observed image is Pobs(Pint=0) = sqrt(pi/2) *
      sigma.  This task uses the maximum likelihood (ml) estimator of
      Pint from Pobs (see Killeen, Bicknell, and Ekers, 1986, ApJ, 302,
      306). The ml estimator does not provide an analytic solution.
      Therefore,  this task uses an asymptotic expression together with
      an empirically determined correction.   There is no significant
      loss of accuracy with this procedure.   The magnitude of the
      correction is approximately Pint/Pobs ~ 0.8 at Pobs/sigma=2 and
      Pint/Pobs ~ 0.9 at Pobs/sigma=2.5.  Pint/Pobs asymptotes to unity
      with increasing Pobs/sigma.  The user must input sigma (Jy).

      The parameter PCUT is the ratio Pobs/sigma below which the output
      image will be blanked.  This may be used to avoid the (mis)use of
      low signal-to-noise polarization data.  Furthermore, it is likely
      that a more conservative value of PCUT (e.g. 3-sigma) may be more
      desirable.  On the other hand, blanking will give a false sense of
      the noise on the image (underestimating by about a factor of 2).
      An empirical method for handling lower values of Pobs/sigma,
      attributed to Wardle and Kronberg, is used for Pobs/sigma < 2.
      This method gives negatives for the lowest values and represents
      the noise much more correctly.  Pobs <= 0 (which should not occur)
      are still blanked.

      The task COMB with OPCODE 'POLC' performs the same operation with
      a somewhat different algorithm for the correction.

Adverbs:
  INNAME......First image name (name).  blank=>any
  INCLASS.....First image name (class).  blank=>any
  INSEQ.......First image name (seq. #).  0=>any
  INDISK......Disk drive # for the first image.  0=>any
  OUTNAME.....Output image name (name)
  OUTCLASS....Output image name (class)
  OUTSEQ......Output image name (seq. #)
  OUTDISK.....Output image disk drive #
  PIXSTD......Input sigma of noise distribution on Q or U image (Jy)
  PCUT........Blank below (Polarized flux/sigma)=PCUT
  OPCODE......Type of blanking, if 'ZERO' blank with 0.0.
              Anything else gives magic blanking.
  BADDISK.....Disks to avoid for scratch
----------------------------------------------------------------
