; BDF2AIPS
;---------------------------------------------------------------
;! Read EVLA ASDM/BDF data into AIPS
;# TASK UV VLA
;-----------------------------------------------------------------------
;;  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
;-----------------------------------------------------------------------
BDF2AIPS  LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
BDF2AIPS:  Verb to read EVLA ASDM/BDF data into AIPS
DOWAIT           -1.0        3.0   > wait for and display output
DOCRT            -4.0      132.0   > 0 display output on
                                   terminal, else message file
ASDMFILE                           Full path name to ASDM dir.
OUTNAME                            Output UV file name (name)
                                     blank => BDF2AIPS
OUTCLASS                           Output UV file name (class)
                                     blank => UVEVLA
OUTDISK           0.0       9.0    Output disk drive #
DOUVCOMP         -1.0       1.0    >=0 => write compressed data
CLINT             0.0              CL table interval (min)
                                     0 -> 0.25
CONFIG            0.0              Select this "configuration"
                                     # - see BDFLIST output
NCHAN             0.0              Select only data with this
                                     # spectral channels/window
NIF               0.0              Select only data with this
                                     # spectral windows 0 -> any
BAND                               Select only frequency band
                                     ('L','C',...) blank => any
CALCODE                            Select only scans with this
                                     value of CALCODE
----------------------------------------------------------------
BDF2AIPS
Type:  Verb
Use:   The OBIT package of astronomy software written by Bill Cotton
       of NRAO Charlottesville is available at some institutions.  If
       it is available and in your $PATH, then you may use this verb
       to load the contents of an ASDM/BDF format data set into AIPS.
       Use BDFLIST first to see how to set some of the control
       adverbs.

       The input adverbs are saved with a TPUT equivalent when this
       verb is invoked.

       The log and run file for each execution of BDFLIST and BDF2AIPS
       will appear in your $HOME area.
Adverbs:
  DOWAIT.....A log file is written into your $HOME area from the obit
             task.  If DOWAIT <= 0.0, AIPS does not wait for the OBIT
             task BDFIn and you will need to look at the log file with
             more, less, cat, or an editor.  If 0 < DOWAIT < 2, the
             messages from BDFIn will appear as the OBIT task generates
             them.  If DOWAIT >= 2, AIPS will wait for BDFIn to finish
             and then echo the log file under control of DOCRT.
  DOCRT......>  0  Use the terminal, the full length of the log file
                   lines will appear so widen it at least a little.
             <= 0  Write log file to message file at level 0 (no echo
                   to the terminal).  Some messages may get truncated.
             DOCRT is not used when DOWAIT < 2.
  ASDMFILE...The full path name to and including the top directory of
             the ASDM/BDF data.  Two 64-character strings may be used
             for long names.  The ASDMFILE(2) will be appended to the
             non-blank portion of ASDMFILE(1) to generate the name
             used.  The code will also manage when ASDMFILE(1) begins
             with either '$xxxx/' or 'xxxx:' where xxxx is a logical
             (environment) variable.  The filename sent to OBIT will
             be the translation of $xxxx followed by a '/' followed by
             an remaining non-blank characters in ASDMFILE(1) followed
             by ASDMFILE(2).
  OUTNAME....Output UV data file AIPS name - 12 characters.
             ' ' => 'BDF2AIPS'
  OUTCLASS...Output UV data file AIPS name - 6 characters.
             ' ' => 'UVEVLA'
  OUTDISK....Output UV data file AIPS disk.
  DOUVCOMP...If true (DOUVCOMP >= 0) the output data are written in
             compressed format which can result in a substantial
             reduction in disk space needed.  This can cause some loss
             of spectral dynamic range (storage is integer 0 - 32767)
             and a really bad data value can destroy all good data
             values.  The real differences in weights between IFs and
             polarizations and spectral channels within a record are
             also lost.
  CLINT......CL table interval in minutes.  0 => 0.25
  CONFIG.....ASDM files often contain more than one "configuration"
             numbered from 0 to N.  Configurations may differ in
             observing band, number of spectral windows, number of
             spectral channels in the spectral windows, etc.  Use
             BDFLIST to see what configurations are in your data set.
             BDF2AIPS can load only one configuration at a time.  Used
             with NCHAN and overrides BAND.
  NCHAN......If > 0, load only spectral windows containing NCHAN
             spectral channels.  At present, all spectral windows
             contain the same number of spectral channels in any one
             configuration.  However, this will change.  When it does,
             BDF2AIPS may have to be run multiple times for a single
             configuration to get all spectral windows.
  NIF........If > 0, load only configurations with this number of
             spectral windows (called "IFs" inside AIPS).
  BAND.......If not blank, load only data having the specified
             observing band.  Recognized values:
               '4','P','L','S','C','X','Ku','K','Ka','Q','W'
             Selection by band is risky as EVLA bands overlap which may
             result in the exclusion of some data.  Note lower case
             letters - get them by e.g. BAND='Ka <CR> where <CR> is
             the Enter key.
  CALCODE....Select only scans with the specified source calibrator
             code if not blank.  'NONE' and '-CAL' => none (i.e. not a
             calibrator).  '*' => anything other than none (i.e. a
             calibrator).  Otherwise if any character matches the
             first character in the Field Table code, the scan is
             selected.

BDF2AIPS is also a stand-alone script you may run outside AIPS.  Its
help file is appended below

BDF2AIPS
Type: Stand-alone service program

Use:  BDF2AIPS is a script that will read an EVLA ASDM/BDF format data
      area and convert it to an AIPS disk file residing on one of the
      AIPS data areas of your current computer.  It does this by
      invoking a task in the obit software package written by Bill
      Cotton.  That package must be available on your system and the
      script ObitTalk must be in your path.  If you do not have obit,
      it may be obtained from www.nrao.edu and should install fairly
      easily.

      You should use BDFLIST first to list the contents of your
      ASDM/BDF format data.  It will provide information on
      "configuration number" which is essential in defining which data
      you wish to load.

      BDF2AIPS is a script that is run at the command line (i.e.,
      outside of AIPS).  It will ask you a few essential questions.
      They are:

      1. "BDF dir-path :"
            Give the full path name to the directory containing the
            ASDM and BDF data.  These data may be obtained from the
            NRAO archive.
      2. "AIPS usrnumb :"
            Give the AIPS user number you wish to use for these data.
      3. "AIPS outname :"
            Give the OUTNAME to be attached to the data file.
      4. "AIPS outdisk :"
            Give the disk number on which to write these data.
            OUTCLASS='UVEVLA'; OUTSEQ=0 will be used.
      5. "Only SpWs with this number of channels are selected, others
          ignored."
         "Default/blank is the #chans in 1st SpW. #chans select : "
            Enter 0 or just hit return and the number of spectral
            channels in the selected data will be those of the first
            data matching the other keywords.  This prompt will be
            needed when the number of channels is allowed to vary
            between spectral windows within a single "configuration".
      6. "ASDM array configuration to select : "
            Enter the "configuration number" >= 0 of the desired
            configuration (ASDMs often contain multiple sets of
            spectral windows of different size, frequency, etc.).
            Use BDFLIST to list the contents of your data to tell you
            which configuration number to select.
      7. "Only scans with this number of SpWs is selected, others
          ignored"
         "Default/blank is the #SpWs in 1st scan. #SpWs select : "
            This question is asked only if you answer question 6 with
            a simple carriage return.  Enter the number of spectral
            windows (IFs in AIPSpeak) of the data configuration you
            want to load.  0 or carriage return => any matching the
            other keywords.
      8. "Default band is the one in 1st PpW."
         "Recognized: 4,P,L,S,C,X,Ku,K,Ka,Q,W,blank"
         "Band select : "
            This question is asked only if you answer question 6 with
            a simple carriage return.  Enter the letter code for the
            desired band.  Note that bands overlap in the EVLA and the
            ASDM does not identify which receiver was used so there is
            some ambiguity.

       BDF2AIPS will make the output file including a number of
       standard AIPS extension files.  The CL table will have an
       interval of 15 sec and the data are not compressed.  The latter
       decision is made to avoid loss of dynamic range which could
       arise if there is significant RFI or a very strong spectral
       line.  Sources with identical names and coordinates but
       different CALCODEs will be treated as different.  This helps
       with calibration, but may cause difficulties when it comes time
       to run SPLIT.

       BDF2AIPS is a simple script and you may make a copy of it and
       modify any of the parameters in your private copy to suit
       yourself.  You may select output FITS format files instead
       (DataType) or change OUTCLASS (outClass), CL interval (calInt),
       compression (Compress), or source naming with CALCODEs
       (doCode).  If you select FITS output you must set x.outFile
       to the desired output path name.

       BDF2AIPS will write a log file and a run file in your /tmp area
       with the time included in the name.  This file is echoed to the
       screen as BDF2AIPS finishes and will remain in /tmp until it is
       automatically deleted by the operating system.
----------------------------------------------------------------
