; MERLIN
;---------------------------------------------------------------
;! Procedure to process MERLIN data
;# 
;  This software is the subject of a User agreement and is
;  confidential in nature. It shall not be sold or otherwise
;  made available or disclosed to third parties.
;---------------------------------------------------------------
MERLIN    LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
MERLIN:   Procedure to process MERLIN data.
          Type HELP MERLIN for more details of inputs 
          and EXPLAIN MERLIN for a description of outputs.
          All editing and calibration is reversible.
          PROTOTYPE - full spectral capabilities not yet
          enabled.  Complaints/suggestions to amsr@jb.man.ac.uk
          Based on P Diamond AIPS procedure
          AUGUST 2005
        
INDISK                             No. of disk drive to use
DIR                                Environment variable for
                                   directory containing FITS 
                                   files.
DOLOAD                             = 0 Data already concatenated
                                       and loaded with name
                                       TARGET.MULTTB (default)
                                   = 1 Sources are in separate
                                       files SOURCE_NAME.FITS
                                       in DIR area
                                   = 2 Input is multi-source
                                       file with name 
                                       TARGET.FITS in DIR area
TARGET                             TARGET source name (required)
PHCAL                              Phase reference source name
PACAL                              Polarization p.a. cal name
ACAL                               Point cal name (required)
AFLUX                              Flux (Jy) of point source
                                   (see DOFLUX and HELP MERLIN)
DOPLOT                             = 0 No plots/printout
                                   = 1 Send to printer
                                   = 2 Use TKPL (interactive)
                                   = 3 Print to disc in DIR
DOEDIT                             = 0 Default: edit extreme, 
                                       isolated points  
                                      (usually interference)
                                   = 1 Run IBLED (interactive).
                                   =-1 No editing 
DOPHSC                             = 0 No phase reference souce
                                   = 1 Assume PHCAL is a point
                                   = 2 Three rounds of self-cal  
                                       starting with point model
                                   = 3 Load CLEAN map for model,
                                       from DIR area. It must be 
                                       called PHCAL.ICL001.FITS
DOPLZN                             = 0 No linear polarization
                                   = 1 Perform polarization
                                       corrections and make
                                       polarization images
DOTGSC                             = 0 No TARGET self-cal (see
                                       (HELP if DOPHSC 0).
                                   = 1 Single pass of phase 
                                       corr with solint=5 min
                                       (for weak sources)
                                   = 2 Five cycles of phase corr
                                       with decreasing solint
                                       (for simple sources)
                                   = 3 Ten cycles of phase corr
                                       (medium/complex sources)
                                   = 4 Ten cycles of phase then
                                       'A&P' (strong sources)
DOBP                               =-1 Do not correct bandpass
                                       (default for single-
                                       channel data)
                                   >=0 Correct bandpass (default
                                       for multi-channel data)
DOCHANS                            = 0 Default: data averaged to
                                       single channel
                                   = 1 Spectral line imaging:
                                       Final image is datacube
                                       ONLY IF DOPLOT 0
                                   = 2 Wide-field imaging: final
                                       single image made from
                                       multi-channel data
SYSVEL                             If line source, velocity of
                                   TARGET at band centre (km/s) 
                                   in LSR, radio definition.
RESTFREQ                           If line source, rest freq. of
                                   transition (Hz). Use
                                   RESTFREQ(1)+RESTFREQ(2).
BCHAN                              Start channel for reference
                                   feature. If continuum leave
                                   as 1 ONLY CURRENT OPTION
ECHAN                              End channel for reference
                                   feature. If continuum leave
                                   as 0 ONLY CURRENT OPTION
REFANT                             Reference antenna number (use
                                   0 for MERLIN defaults)
DOFLUX                             = 0 Use AFLUX for ACAL and 
                                       existing flux scale for
                                       all sources. Default, but
                                       see HELP MERLIN
                                   = 1 At 1.2-7 GHz use ACAL and 
                                       3C286 to refine flux 
                                       scale for all sources.
                                   = 2 Compensate for resolved    
                                       ACAL (NOT IMPLIMENTED)
DOUVR                              If > 0 then will apply 
                                   uv-range restrictions during 
                                   TARGET self-cal. If unsure or
                                   your TARGET has significant
                                   extended structure set 
                                   DOUVR = 0
DOSEARCH                           If > 0 then will search for
                                   the TARGET within the field.
                                   Not allowed if DOPHSC 0
DOREWT                             = 0 No reweighting (Default)
                                   = 1 Reweight the uv-data 
                                       according to different 
                                       antenna sensitivities
                                       before final TARGET image  
IMSIZE          0.0      8192.     Minimum image size for TARGET
BMAJ                               Major axis of TARGET 
                                   restoring beam. 
                                   Default: natural beam size.
BMIN                               Minor axis of TARGET 
                                   restoring beam.
                                   Default: natural beam size.
BPA                                Position angle of TARGET 
                                   restoring beam.
                                   Default: natural beam angle.
DOTV                               =-1 Default: no interactive
                                       imaging
                                   = 1 INTERACTIVE TARGET 
                                       imaging 
                                   = 2 INTERACTIVE PHCAL and
                                       TARGET IMAGING
----------------------------------------------------------------
MERLIN
Type:  Procedure
 Use:  To perform basic editing, calibration and imaging on MERLIN data.
       You need the runfile MERLIN.ehex where ehex is your AIPS number 
       in 3-digit ehex e.g. for AIPS No. 895 use MERLIN.0OV
       Before starting AIPS, in the same directory, set environment 
       variable(s) for the MERLIN runfile etc. (also see DIR, DOPLOT)
       e.g.
       % setenv RUNFIL /scratch/octans_1/visitor1
       % setenv DATA  /scratch/octans_1/visitor1/FITS
       In AIPS, type
       > RUN MERLIN
       > INP MERLIN
                and when you are happy with inputs:
       > MERLIN
       You can use TPUT and TGET MERLIN but you must not alter inputs
       to other tasks/verbs after doing RUN MERLIN.  If MERLIN fails part-
       way you should remove all new files and start again or seek help. 
       All calibration and editing is stored in extension tables attatched   
       to the input file, and can be reversed by deleting the appropriate
       table. See EXPLAIN MERLIN for more details. 
       NB if you type 'RESTORE 0' you will have to re-RUN MERLIN.
          If you use INTERACTIVE settings, procedure will wait for your input.

Author: P. Diamond/A.M.S. Richards
Documentor: A.M.S. Richards June 2003
Adverbs:
  INDISK....AIPS disk to write data to (0 = any)
  DIR.......Environment variable for directory holding FITS files, e.g.
            DIR 'DATA' in above example. 
            Can be 'RUNFIL' 
            Default ' ' = PWD.   Also see DOPLOT
  DOLOAD....= 0 One multi-source file already in AIPS called TARGET.MULTTB 
                where TARGET is your TARGET; file must also contain point 
                source cal (ACAL) and (if used) phase reference source (PHCAL) 
                and flux/polarisation angle cal (PACAL,default 3C286). This is 
                normally 'tdproc' output.  Default 0
                NB All pre-existing CL, SN and BP tables are DELETED
            = 1 TARGET.FITS, ACAL.FITS, PHCAL.FITS and PACAL.FITS (as 
                required) are in separate files in DIR area
            = 2 one file (as for DOLOAD=0) called TARGET.FITS in DIR area
  TARGET....Name of TARGET source REQUIRED
            All source names must be EXACTLY as used in MERLIN observations
  PHCAL.....Phase reference source (required if DOPHSC > 0)
  PACAL.....Polarization position angle calibration source (must be in
            data file if linear polarization wanted, default 3C286) 
  ACAL......Point source cal, also BP cal if wanted. REQUIRED
  AFLUX.....= 0 Default value will be used at 1.2 - 8 GHz if 
                ACAL =  OQ208, 0552+398 or 2134+004 
                Use DOFLUX = 1 if 3C286 is present. 
            Otherwise set best known value. See DOFLUX and EXPLAIN MERLIN  
  DOPLOT....= 0 No plots
            = 1 Hard copy printouts of solution and image plots and text
               files of scan listings and some calibration details
            = 2 Plots/text sent to Tek server/screen. INTERACTIVE
            = 3 Plots/text printed to disc in DIR area.
           NB AIPS has print environment length limitation, avoid long 
              directory paths 
  DOEDIT....= 0 VPLOT is used automatically to edit visibility amplitudes
                which are >10 sigma in raw data averaged over ever 3 min.
            = 1 IBLED will be run on each source in turn.  Familiarise
                yourself with this first.  FLAG TIMERANGE flags all
                sources; other commands flag only current source. 
                STOKES FLAG 1111 avoids spurious polarization results. 
                INTERACTIVE
            =-1 No editing at all in this procedure. If there is already an 
                FG table it will be applied.
  DOPHSC....= 0  No phase reference source used.
            > 0 Options for using phase reference source PHCAL to derive 
                phase and amplitude solutions which will be transferred 
                to the TARGET.
            = 1 PHCAL is assumed to be point-like
            = 2 Derive first phase solutions using point model, map PHCAL
                for 2nd and 3rd (phase, amp & phase) solution rounds.
            = 3 Load existing image PHCAL.ICLN001.FITS from DIR area for
                first model. Highest No. CC table is used.
            For DOPHSC >1, models use merged CC down to first negative.
            Data are averaged from BCHAN to ECHAN for calibration and
            solutions are copied back to multi-source data set.
  DOPLZN....= 1 Use PHCAL to derive corrections for polarization leakage
                and PACAL to correct polarization angle.
  DOTGSC....= 0 No self-calibration of TARGET, one image is made after
                applying PHSREF solutions. Will be rubbish if DOPHSC 0.
            = 1 After applying PHSREF solutions, TARGET is imaged and CC
                down to first negative are used as model for phase-only
                self-calibration, 5 mins solution interval.  Use for weak 
                sources (typically peak snr >20 but <100).
                If DOPHSC 0 a default point model is used, see EXPLAIN
            = 2 After 1, *four more cycles of phase-only self-cal with
                decreasing solution intervals (for simple sources).
            = 3 After 1, *nine more cyles of phase-only self-cal with
                decreasing solution intervals (for medium/comples sources).
            = 4 After 3, *amplitude and phase self-cal (strong sources, 
                beware introducing symmetric or other artefacts if uv
                coverage is poor e.g. at low Dec or 22 GHz).
            All imaging uses completely natural weighting (plus final
            reweighting if DOREWT 1). All self-calibration uses data
            averaged from BCHAN to ECHAN; solutions are applied to all
            TARGET data channels. 
            You can continue manual self-cal; for wide-field TARGETS 
            you might want to use multi-channel data.
            NB Total intensity (Stokes I) images are used as models. If
               your TARGET is significantly circularly polarized (e.g.
               many OH masers) you should set DOTGSC 0 and see
               MERLIN User Guide for manual self-cal.
  DOBP......=-1 Do not do bandpass correction (default if data are in
                single channel)
            >=0 Derive bandpass corrections using ACAL (default if 
                multi-channel data).
  DOCHANS...= 0 All except end channels are averaged for all imaging (DEFAULT)
            = 1 Spectral line imaging: individual channels imaged separately 
                in final image to produce a datacube
                ONLY AVAILABLE IF DOPLOT 0
            = 2 Wide-field imaging - final single image is made from multi- 
                channel data (calibration performed on averaged data)
            In all cases the channels from ECHAN to BCHAN are averaged and
            used for all calibration and imaging during calibration.
  SYSVEL....If line source, enter TARGET velocity (km/s) in band centre
            (chan 128 for nominal 256 chans etc.) Use radio LSR convention.
  RESTFREQ..If line source, enter rest frequency (Hz) in double precision
  BCHAN.....Start channel of reference feature for line TARGET self-cal.
            Leave as 1 for continuum (default) - first ~5% chans excluded.
  ECHAN.....End channel of reference feature for line TARGET self-cal.
            Leave as 0 for continuum (default) last ~5% chans excluded.
            ** DO NOT RESTRICT CHANS at present please
  REFANT....Reference antenna. Default is Mk2, Da, Ta or Kn in order of
            preference.  Use same REFANT throughout for polarization
            imaging, use MK if LO is in the array or use closest antenna 
            with mostly good data.
  DOFLUX... = 0 Use preset (usually tdproc) flux scale.
            = 1 Refine flux scale using well-edited 3C286 and ACAL
                Currently only possible at 1.2-7 GHz; 3C286 must be present.
                AFLUX must be accurate to ~50% 
            = 2 Use secondary flux-cal to compensate for resolved ACAL
                NOT YET IMPLEMENTED
  DOUVR.....= 0 No restrictions on uv range (default)
            = 1 Start self-cal by giving a low weight to inner portions of
                uv plane to avoid confusing sources, all data is gradually
                added in during subsequent rounds of self-cal.
            Use DOUVR=0 for extended TARGETs (more than 5 - 10 beamwidths).
            At K-band DOUVR=0 is almost always most suitable.
  DOSEARCH..= 0 DEFAULT images will be centred on input positions
            = 1 TARGET images will be shifted to be centred on position found 
                for TARGET.  Use ONLY if DOPHSC >0, if the position of your
                TARGET may be > ~IMSIZ/4 away from the input position.
  DOREWT....= 1 For the final TARGET image, reweight the data from each 
                antenna in proportion to its sensitivity, see MUG (web
                ref below).  If data are well-edited and well-
                calibrated this optimises signal to noise but changes the
                natural beam-size: if Lo is present the beam becomes larger;
                at 22 GHz if Ca is present the beam becomes smaller. You
                can adjust the beam-size by running IMAGR manually using
                suitable values of UVWTFN, ROBUST, BMAJ, BMIN, etc.
  IMSIZE....Target image size.  Minimum size for reliable deconvolution
            of complex/extended sources is 512x512 pixels (default).  
            Use 512x1024 or larger at low Dec, use larger for larger 
            TARGETS/poor uv coverage. 
  BMAJ......Major axis (mas) of beam to be used for final TARGET image.
  BMIN......Minor axis (mas) of beam to be used for final TARGET image.
  BPA.......Position angle (N->E) of beam to be used for final TARGET image.
            Default for BMAJ, BMIN, BPA is beam fitted using natural weighting.
            If you want to change by more than ~10% consider running IMAGR
            manually with different UVWTFN, ROBUST etc.
  DOTV......=-1 Default - no interactive imaging
            = 1 For TARGET imaging, IMAGR starts in interactive mode.
            = 2 PHCAL and TARGET imaging start in interactive mode.
----------------------------------------------------------------
See the MERLIN User Guide for more information about manual processing.
MUG http://www.merlin.ac.uk/user_guide/

AFLUX and DOFLUX

If your input flux scale is inaccurate by >~50%, UVMOD should be used
to improve it before running the MERLIN procedure.

At 1.2 - 8 GHz, if you know the flux density AFLUX of your ACAL on
MERLIN scales to ~50%, e.g. extrapolate to your epoch from from
http://www.merlin.ac.uk/user_guide/collect_cal_flux.txt, and 3C286 is
present, then DOFLUX = 1 will use the shorter baselines to refine the
flux scale and apply the solution to all sources.  

If AFLUX=O & ACAL = OQ208/1404+286, 0552+398/DA193 or 2134+004, a
default AFLUX value will be used; you should set DOFLUX 1 if 3C286 is
present.  This will give a flux scale accurate to a few percent.  

For other ACALs or very high/poor accuracy consult MERLIN staff.
22 GHz flux densities are available courtesy of H Tersranta, Metsahovi.


OUTPUT FILES

TARGET.MULTTB 
contains all the input sources concatenated into one file with OUTPUT
TABLES depending on the options selected:
AN (anten): If DOPLZN 1 this contains polarization corections
FG (flag):  Any input tables preserved and used; higher number tables
            contain accumulated flags, so highest no. contains all.
BP (bpass): If doband > -1 and data are multi-channel
CL (calib): 1   Blank template
            2   Global amplitude correction per antenna/polarisation 
                if DOFLUX 1, otherwise also blank template
            3,4 Phase-only PHCAL solutions if DOPHSC > 0
            5   Amp&Phase PHCAL solutions if DOPHSC > 0
                Also polarization PA correction if DOPLZN 1
            6,7,8 If DOTGSC > 0 then these are equivalent to
                TARGET.MULTSC CL 2,3,4 (see below).

All the files will have an HI (history) file which can be inspected
using verb PRTHI to see the settings used in its ancestral tasks.

TARGET.MULTSC is made by applying any relevant BP, CL and AN
corrections and splitting out the TARGET from TARGET.MULTTB.  
If DOTGSC > 0 then 
CL 2:  First self-cal phase corrections 
       - if DOPHSC > 0 these were derived using the CC from the first
         TARGET map after applying the PHCAL phase corrections so the
         TARGET position is as accurate as possible;
       - if DOPHSC 0 these were derived using a default point model so
         the TARGET position will appear to be at the input
         coordinates regardless of the true position.
CL 3:  CL 2 + final phase-only corrections if DOPHSC > 1
CL 4:  CL 3 + amp&phase corrections if DOPHSC = 4

TARGET.SPLIT is the final split file made from TARGET.MULTTB applying
all calibration; if DOCHAN >0 then all except the end channels will be
kept separate; otherwise they are averaged. If DOREWT > 0 then the
appropriate antenna weights are applied, see MUG web ref. above.

TARGET.IBM001 is the last beam made
TARGET.ICL001.* are the final CLEANed images, the highest number *
being the most calibrated if DOTGSC > 0 (see notes above on position).
The final image is made from TARGET.SPLIT.

TARGET.POLI and .POLA are the polarized intensity and angle images if
DOPLZN > 0
PHCAL image names follow the same convention.

If DOSEARCH 1, inspect the final ICL001.* header and history file to see
if a large shift (>~20 beams) was applied in IMAGR; if so, you are
advised to use UVFIX instead of using a shift during imaging.

Calibration solutions for the ACAL and PACAL etc. are not all retained
(apart from CL2) as they are not applicable to other sources; inspect
the plots to check these.

Some SN tables are preserved as follows:
PHCAL.TASAV 
SN 1: Phase-only solutions 

ACAL.TASAV  - only present if DOFLUX > 0
SN 4: Time-constant amplitude correction (no phase solutions), used to
      make TARGET.MULTTB CL 2 and applied to all data thereafter  


NOTES

If you are using an old version of AIPS (e.g. last century) some
adverbs e.g. 'nplot' are different which may affect printout and a few
tasks e.g. BPASS, CLCAL may not work as desired - you are advised to
download the latest frozen version of aips (currently 2005) or check
your results very carefully.
