; COHER
;---------------------------------------------------------------
;! Baseline Phase coherence measurement
;# TASK UV IMAGING
;-----------------------------------------------------------------------
;;  Copyright (C) 1998-1999
;;  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
;-----------------------------------------------------------------------
COHER     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
COHER:  Finds coherence time for selected "BT" or "TB" order uv data
INNAME                             Input UV data (name)
INCLASS                            Input UV data (class)
INSEQ             0.0    9999.0    Input UV data (seq. #)
INDISK            0.0      10.0    Input UV data disk #
APARM                              (1) Max. averaging time (min)
                                       0 => 10*APARM(8)
                                       0 is not recommended
                                   (2) SNR cutoff in coherence
                                       time estimation 0 => 5
                                   (3) Min Vector/Scalar ratio;
                                       0 => 0.8
                                   (4) Prtlev; 0=>reasonable
                                   (5) Step in time in minutes;
                                       0 => infinite
                                   (6) 0 => average frequencies
                                            with delay search
                                       1 => simple vector
                                            averaging
                                   (7) Output type
                                       0 => average coherence
                                       1 => current coherence
                                           times ready for BLING
                                   (8) expected coherence time
                                       (min), max for all basel.
                                       0 => 5min
BADDISK                            Disk #'s to avoid
TIMERANG                           Time: start day,hr,min,sec;
                                         stop day,hr,min,sec.
BIF               0.0    100.0     IF number; 0 => 1
BCHAN             0.0   4096.0     Lowest channel number 0=>1
ECHAN             0.0   4096.0     Highest channel number
                                   0 => last available
ANTENNAS                           Antennas to be selected
BASELINE                           Baselines with ANTENNAS
                                   See explanation.
SOURCES                            Source list. See explanation.
FREQID                             Freq. ID to select. 0 => 1
DOCRT                              > 0 means  use the terminal.
                                   < 0 use the line printer
OUTPRINT                           Disk file name in which to
                                   save the line printer output.
SUBARRAY          0.0     9999.0   Subarray; 0 => 1.
----------------------------------------------------------------
COHER: Task to measure coherence time
       NB: data must be sorted to 'BT' or 'TB' order before running.
Adverbs:
  INNAME.....Input UV data file (name).     Standard defaults.
  INCLASS....Input UV data file (class).    Standard defaults.
  INSEQ......Input UV data file (seq. #).   0 => highest.
  INDISK.....Input UV data file disk #.  0 => any.
  APARM.....Task enrichment parameters.
            (1) Maximum time interval for a source or selected time
                interval, in minutes. 0=> 10*APARM(8)
                Comparison of vector and scalar average for each source
                is terminated having reached a next source or
                when time (starting from the beginning of the source or
                the beginning of a sequent time interval)
                reaches APARM(1). This parameter should be selected
                several times more expecting coherence time. If the
                output file created for BLING, this interval is
                desirable to have as long as possible. It is limited
                by the buffer size. APARM(1)<2000*PREAVE, where
                PREAVE is the preaverage time.

            (2) Max SNR deviation to pass.  While calculating
                the coherence time, the scalar mean and rms of each
                baseline is calculated.  If the value of a
                visibility exceeds APARM(2) times the RMS, the
                visibility is flagged (in buffer; not in the data).

            (3) Min Vector/Scalar amplitude ratio.  The ratio of
                the vector to scalar averaged amplitude is calculated.
                The coherence time for each try is
                defined as the time interval for which the ratio
                falls below APARM(3).  0 => 0.8

            (4) Print level:
                0 => print tables of coherence times for selected
                     baselines and antennas for each selected time
                     interval and source. Print tables of coherence
                     times averaged for all selected time interval and
                     sources. Print minimum and mean coherence time
                     through all antennas
                1 => print additional information useful for debugging

            (5) Step in time in minutes; 0 => infinite
                So if zero, then the only time interval is selected.
                Introducing this parameter you can estimate the coherence
                time variance versus time.
                The less APARM(5) the more data at the time axis you get,
                but the more computing time is required.
                If output file for BLING is prepared (APARM(7)=1),
                APARM(5) is forced to be equall APARM(1). It is allowed
                continuously increasing the analysis time.

            (6) 0 => provide delay search, averaging frequencies
                1 => not provide the search.
                Generally speaking it is necessary to search for the
                delay to average frequency channels. But if signal/noise
                ratio is not high enough, an error in the solution of
                the delay can occur. As a result phases of the frequency
                average data become random from time to time, and COHER
                find a low vector averaging and therefore low coherence
                time.
                However sometimes delay is known in advance close to
                zero. In this case APARM(6)=1 allows to exclude the delay
                search providing actual vector averaging at the frequency
                axis.
                If you are sure that delay is close to zero,
                APARM(6)=1 is more preferable because the task ran faster.

            (7) Output type.
                0 => average coherence. This option gives idea about
                the coherence property of the baselines and antennas.
                1 => current coherence times ready for BLING.
                BLING will use this data (infile) to find solution for
                the given variable solution intervals.

            (8) Expecting coherence time in minutes. Maximum for all
                baselines. 0 => 5min.
                The task compares scalar average amplitude with estimated
                amplitude by FFT plus least square. The comparison starts
                with this time (APARM(8)). Then this interval is splitted
                for twice smaller intervals. This process continue while
                the maximum possible time is found satisfying condition:
                AMPVEC/AMPSCAL = APARM(3). This condition determines the
                first coherence interval. The search of the next interval
                starts at the end of the previous found interval using
                APARM(8) as the initial estimation.

  BADDISK...Disk #'s to avoid for scratch files
  TIMERANG..Time: start day,hr,min,sec; stop day,hr,min,sec.
            0 => all
  BIF.......IF number; Only one (the specified) IF can be used;
            0 => 1
  BCHAN.....Lowest channel number 0 => 1
  ECHAN.... Highest channel number, 0 => highest available
  ANTENNAS..A list of the antennas to be selected
  BASELINE...Baselines between antennas named in ANTENNAS and those
             named in BASELINE are selected..  There are four possible
             combinations of ANTENNAS and BASELINE:
             1. ANTENNAS = 0; BASELINE = 0.
                All possible baselines are selected.
             2. ANTENNAS <>0; BASELINE = 0.
                a)All ANTENNAS > 0
                  Baselines including an antenna in the ANTENNAS list
                  are selected;
                b)Some ANTENNAS < 0
                  All baselines NOT including an antenna in the ANTENNAS
                  list are selected;
             3. ANTENNAS = 0; BASELINE <> 0.
                a)All BASELINE > 0
                  Baselines including an antenna in the BASELINE list
                  are selected;
                b)Some BASELINE < 0
                  All baselines NOT including an antenna in the BASELINE
                  list are selected;
             4. ANTENNAS <> 0; BASELINE <> 0.
                a)All ANTENNAS>0 and all BASELINE>0
                  Baselines between antennas named in ANTENNAS and those
                  named in BASELINE are selected.
                b)Some ANTENNAS<0 .OR. some BASELINE<0
                  Baselines between antennas named in ANTENNAS  and
                  those named in BASELINE are DE-selected, all others
                  are selected.
  SOURCES....Source list. Blank => all
             If the first character of any source names
             begins with a "-", all sources EXCEPT those
             named will be returned.
             The "-" will be ignored in determining the source name.
  FREQID.....Freq. ID to select. 0 => 1. Use LISTR (OPTYPE=SCAN)
             to find list of FREQIDs of the data
  DOCRT......False (<= 0) use the line printer if OUTPRINT = ' '
                   else write named OUTPRINT file only.
             True  (> 0) use the terminal interactively.  The task will
                   use the actual terminal width as a display limit
                   unless 72 < DOCRT < width.  In that case, the display
                   limit will be DOCRT characters.
  OUTPRINT...Disk file name in which to save the line printer output.
             ' ' => use scratch and print immediately for interactive
             jobs - batch jobs use OUTPRINT = 'PRTFIL:BATCHjjj.nnn'
             (jjj= job #, nnn = user #).  When OUTPRINT is not blank,
             multiple outputs are concatenated, and the file is not
             actually printed.
  SUBARRAY...Subarray; 0 => 1.
----------------------------------------------------------------
COHER: Task to estimate coherence time
       NB: data must be sorted to 'BT' or 'TB' order before running.
Related programs: COHER derived from PHASE
Documentor: Leonid Kogan NRAO/Socorro.

                           Comments

Coherence time is determined by comparing vector and scalar averaged
amplitudes. When the vector/scalar ratio becomes less than APARM(3)
the coherence time is considered exceeded. A new coherence time is
determined for the following time interval starting with the end of
previously found coherence interval. This process is terminated when
the time reaches the source end or APARM(1). This process begins
again for a new source or new time interval (APARM(5)).

The result is presented as a table of found coherence times for each
source or time interval. The final coherence time is determined as an
average over the selected sources.  Complex amplitude for each time is
determined using FFT analysis of the data at the selected frequency
channels and fitting a complex exponent by non linear least square
method.  Vector averaging at the time axis is provided by fitting a
complex exponent by non linear least square method. The first approach
for the least square is given by FFT. The fitting of the complex
exponents instead of simple vector averaging allows to estimate
amplitude in the case of non zero value of delay and rate. But such a
method required more computing time. The special methods were used to
minimize the computing time. Now it is equal ~20 sec at SPARC station
IPX for 5 antennas and four 5 minutes intervals.  The task ran much
faster if delay search is excluded (APARM(6) = 1).










