; VLBIN ;--------------------------------------------------------------- ;! Task to read VLBI data from an NRAO/MPI MkII correlator ;# TASK UV VLBI ;----------------------------------------------------------------------- ;; Copyright (C) 1995 ;; 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 ;----------------------------------------------------------------------- ;--------------------------------------------------------------- VLBIN LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC VLBIN: Task which creates uv data from NRAO-DECODE VLBI data. INFILE Input VLBI uv file name. Eg., DBA0:[VLB.S12V]3C120.DAT IN2FILE Antennas list file. OUTNAME Output UV file name (name) blank => NONAME OUTCLASS Output UV file name (class) blank => UVDATA OUTSEQ 0.0 999.0 Output file sequence # OUTDISK 0.0 9.0 Output disk drive # SOURCES Source list BCHAN 0.0 9999.0 Begin channel (delay or freq) ECHAN 0.0 9999.0 End channel.If continuum data use 4 and 10 dly.If line data use start & stop dly channels BDROP 0.0 999.0 Drop first BDROP and last EDROP 0.0 999.0 EDROP freq chans on output. NPOINTS 1.0 Max # 1000's of visibilities ** Set misc. parameters ** DOUVCOMP -1.0 1.0 1 (T) => compressed data VLBINPRM -1.0 9999.0 1: =1 machine dly corr 2: =1 trans dly to frq 3: Num. pol. axis pix. 4: Ith pol. axis pix. 5: Reference day number (first day of entire VLB run). See HELP for more. 6: =1 FBS corrections. =2 only do amp corr 7: =1 Do not recalc u, v and w. 8: Cal table int(min). 9: =1 Van-Vleck corr. 10: additional b-factor for line data, 0=>0.64, anything else => do nothing (IMPORTANT: see HELP) 11:=1 reject autocorr data. 12: FQ entry tolerance (kHz), see HELP. 13: bandwidth (kHz) to accept, 0 => all. 14: frequency (MHz) to accept, 0 => all. 15: frequency tolerance (MHz) i.e. accept freq PARM(14) +/- PARM(15)/2 16: true sideband of data (see help), 0 => take value in DECODE header. 17: from May 1991 the NRAO MkII correlator stored autocorrelations in the wrong order, 0 => correct. 1 => leave alone. See HELP 18: Time between switch cycles (seconds) 19: number of switch cycles 20: switch cycle to accept KEYVALUE Ref. freq value for cat. header (Hz). If 0 => use value in data. TIMERANG -1.0 999.0 Start time (UT) : (1-4) = day of year, hours, mins, secs. Stop time (UT) : (5-8) = day of year, hours, mins, secs. ---------------------------------------------------------------- VLBIN Task: VLBIN reads a VLBI NRAO-DECODE format data set from a standard VAX/CONVEX disk file. VLBIN creates an AIPS uv data set. VLBIN will pass frequency channels directly from the VLB data set or transform delay channels into frequency chans. VLBIN will not pass delay channels into AIPS. Adverbs: INFILE........Input file name, 48 characters max. Eg., DBA0:[VLB.3C120]3C120CAL.DAT under VMS or MYVlB:3C120LOCAL.DAT under UNIX IN2FILE.......File containing a complete list of the VLB stns and sources used in the current experiment. OUTNAME.......Output UV file name (name). blank => NONAME OUTCLASS......Output UV file name (class). blank => UVDATA OUTSEQ........Output UV file name (seq #). 0 => highest unique OUTDISK.......Disk drive # of output UV file. 0 => highest with space SOURCE........Source name. (required) BCHAN,ECHAN...If input data set is in frequency channels, use BCHAN and ECHAN to define the range of channels to pass to AIPS. If input data set is in delay lags, use BCHAN and ECHAN to set transform window in delay channels. For 12 delay lag input, use BCHAN=4, ECHAN=10. For 32 delay lags, use BCHAN=14, ECHAN=20. VLBIN will pass the sideband specified in the VLB data headers.If input data is spectral line data in delay lags set BCHAN=1 and ECHAN= whatever the last channel is ( usually 192 ). BDROP,EDROP...Drops the first BDROP and last EDROP frequency channels from the AIPS output records. Useful when transforming delay lags into frequency and dropping off the first and last freq channels. NPOINTS.......Maximum # 1000's of input visibilities. 0 => 1 DOUVCOMP......If true (DOUVCOMP >= 0) the output data is written in compressed format which can result in a substantial reduction in disk space needed but only calibration routines are likely to interprete this data. VLBINPRM(1)...Set = 1 to calculate and apply machine delay correction. Do it. VLBINPRM(2)...Set = 1 to transform delay channel data into frequency channel data. VLBINPRM(3)...Specify the number of pixel elements on the polarization axis (1,2,3 or 4). VLBINPRM(4)...Current visibilities will be written into the VLBINPRM(4)'th pixel element on the polarization axis. VLBINPRM(5)...Specify a reference day number used to calc. the times carried in the vis. records. The day numbers in the vis. records are : day number of actual rec. time - ref. day num. Use the first day in the entire experiment, or earlier. Always use the same day number each time you run VLBIN for different sources in the same experiment. This bother allows safe merging of partial data sets by DBCON.Defaults to the day number in the first scan read in INFILE. VLBINPRM(6)...Set = 1 to enable full fractional-bit-shift corrections. Set = 2 to enable a correction for the amplitude loss only. VLBINPRM(7)...If > 0 VLBIN passes the u, v and w in the VLB data record headers. If <= 0 will recalculate u, v and w. VLBINPRM(8)...Interval (in minutes) at which to write the calibration table entries. VLBINPRM(9)...Set = 1 to enable the Van-Vleck clipping corr- ection to be done. VLBINPRM(10)..Additional b-factor. I am convinced now that b stands for bugger. If the Van-Vleck correction is all that you have done to your data then the cross-power amplitudes need to be adjusted by a further factor of 1.28 / 2 (i.e. VLBINPRM(10) = 0.64). Type EXPLAIN VLBIN for mor details. Default: 0 => 0.64 for line data, anything else = no correction VLBINPRM(11)..Set = 1 to reject all autocorrelation data. VLBINPRM(12)..FQ entry tolerance (kHz) for deciding what FQ ID number to assign to a frequency. The default (0) is that all data are given the same FQ number. If VLBINPRM(11) is negative then a new number is assigned to data that differ from any previous frequency by an amount greater than the frequency equivalent of 30km/s (i.e. the maximum Doppler shift of a source in a day). If VLBINPRM(11) > 0 then the value is assumed to be the tolerance (in kHz) desired by the user. VLBINPRM(13)..The bandwidth to accept (kHz). Useful if your input file has data with multiple bandwidths. 0 => all VLBINPRM(14)..The frequency to accept (MHz), only valid with VLBINPRM(15). VLBINPRM(15)..The frequency tolerance to accept (MHz). VLBIN will accept data with freq between VLBINPRM(14) +/- VLBINPRM(15)/2. VLBINPRM(16)..The true sideband of the data, in some cases, e.g. the VLBA, the sideband recorded in the DECODE data header is incorrect, this can lead to problems inside VLBIN since the FFT will be done in the wrong direction. Setting VLBINPRM(16) to +1 (for USB) or -1(for LSB) will override the value in the DECODE header. 0 => use the value currently there, this is sensible for most datasets. VLBINPRM(17) From about May 1991 the NRAO correlator wrote the autocorrelation data for station A into the station B slot and vice versa. The default value of VLBINPRM(17) is to switch these back to the correct order. Setting VLBINPRM(17) = 1 will leave the data as they are, that should be the value used for data correlated before May 1991. VLBINPRM(18) Users may need to use switch cycles i.e. switching between different video converters. VLBINPRM(18) specifies the switch cycle time in seconds VLBINPRM(19) Specifies the number of switch cycles VLBINPRM(20) Specifies the switch cycle to accept. Example: If the switch cycle time is 30 seconds, and there are 3 cycles (i.e. 3 different video recorders), and the user wishes to select cycle 2 then the parameters to be set are: VLBINPRM(18) = 30 VLBINPRM(19) = 3 VLBINPRM(20) = 2 KEYVALUE......The user can specify a reference frequency for the catalogue header (Hz). If = 0 use value in data. TIMERANG(1)-(4).Accept input data later than this start time: day of year,hours,minutes,seconds. (UT) TIMERANG(5)-(8)..Accept input data earlier than this stop time: day of year,hours,minutes,seconds. (UT) Default : 00d, 00h, 00m, 00.0s. - start (UT) 366d, 00h, 00m, 00.0s. - stop (UT) ---------------------------------------------------------------- VLBIN : Creates an AIPS uv data set from VLB DECODE file. DOCUMENTOR : J. M. Benson, NRAO/CV RELATED TASKS : Most of AIPS. PURPOSE VLBIN creates an AIPS uv data set from an external NRAO DECODE file. VLBIN brings VLB cross-correlation spectra into AIPS. Also, VLBIN reads delay lag data and transforms them into frequency data for the global fringe fitting task, VBFIT. COMMENTS INFILE: The complete VMS file name of the input file, eg., INFILE='UMA1:[VLB.JMB]DATANAME.DAT'. The input file may be a DECODE format VMS tape. If running on a UNIX system then the file name of the input file must be of the form: INFILE='MYAREA:DATANAME.DAT'; where MYAREA is an environment variable which points to the area containing the data file (e.g. setenv MYAREA /scr/vlbi/3c120). The name of the file in MYAREA must be in upper case. IN2FILE: A separate external file MUST be created by the user (and text editor) containing the names of ALL stations used in the current VLB experiment. The station names are entered in quotes like this : STATIONS='NRAO','VLA','OVRO','FDVS','MPI','JDRLMKII', 'OSO25','CRIMEA' When VLBIN starts up, it will list the stations it found in IN2FILE. A list of sources is also included in IN2FILE. These are the sources whose data you wish transfered into AIPS. Enter the source list like this : SOURCES='3C120','OJ287','NRAO150','3C273' Enter the delimited character at the end of the file, /. VISIBILITY PHASE: The sign of the visibility phase is flipped as it is entered into AIPS. WEIGHTS: The AIPS visibility record weights are derived from the correlator effective integration times. The integration times are multiplied by a factor of five to keep the weights between 1 and 100. AUTOCORRELATION DATA Autocorrelation data are now passed by VLBIN. Whether they enter VLBIN as AC functions or spectra, they leave as spectra with the same number of channels as the visibility data. The AC weights are set equal to 1.0. If VLBINPRM(10) is set to 1.0 then autocorrelation data are rejected. TRANSFORMING, MACHINE DELAY and FBS CORRECTIONS: VLBIN will transform DECODE data in delay lags into an AIPS file in frequency channels. To transform the delay lags, enter VLBINPRM(2)=1. To correct the visibility phases for a slowly varying machine delay term, enter VLBINPRM(1)=1. To apply a correction for the processor fractional-bit-shift error, set VLBINPRM(6)=1. If VLBINPRM(6)=2 the amplitudes only will be corrected for the loss caused by the fbs error. VAN-VLECK CLIPPING CORRECTION. If VLBINPRM(9) is set to 1 VLBIN will perform the full Van- Vleck clipping correction, according to the formula: P(t) = sin ( (pi/2) * PC(t) ) where PC(t) is the cross-correlation function of the clipped signals and P(t) is the true cross-correlation function. This correction is only done for spectral line data (i.e. #channels > 32) since it is only necessary when PC(t) is close to unity, which occurs with some non-thermal maser sources. OTHER QUANTIZATION CORRECTIONS The Van-Vleck clipping correction is applied to both auto and cross-power data. There are two additional factor to be applied to cross-power data only. One is a factor of 1.28 to correct for the effects of the 3-level fringe rotator and the bit-blanking when the digital fringe-rotator is at zero. The second is the 'mysterious' factor of two by which the data have to be divided. We do not know the cause of this factor of 2, it is however real. Therefore the full correction that should be applied to cross power data is: 1.57 * 1.28 ----------- = 1.005 2.0 In other words, the cross-power data does not really need to be adjusted at all. However in order to avoid confusion we apply the various corrections explicitly, therefore VLBINPRM(9) applies the Van-Vleck clipping correction (1.57) to both auto and cross-power data, VLBINPRM(10) applies the 1.28/2 = 0.64 correction to cross-power data only. The default is to apply this correction to line data. This is not done to continuum data because these effects are absorbed into the so- called b-factor. POLARIZATION AXIS: VLBINPRM(3) specifies the number of pixel elements in the polarization axis. VLBINPRM(4) is the pixel location that VLBIN will write the output visibilities. Watch out, VLBIN bloats the output data set when VLBINPRM(3) is greater than 1. The empty pixel locations carry visibilities with weight -99.0. BCHAN, ECHAN, BDROP and EDROP: VLBIN will transfer VLBI spectral line data (frequency channel records) directly into AIPS, or VLBIN will transform VLBI data (delay lag records) into frequency channels and write AIPS records. VLBIN will not transfer VLB delay lags into AIPS records. AIPS currently has no use for delay lag data. BCHAN and ECHAN set the range of input data channels (or lags) that will be passed (or transformed and passed) into AIPS. Thus for spectral line VLBI data which has already been transformed you might set BCHAN=1 and ECHAN=128 to pass all line channels, or BCHAN=54 and ECHAN=58 to pass only five frequency channels. BDROP and EDROP are ignored for spectral line input data. In the case of continuum VLB data, or spectral line data which has not been transformed BCHAN and ECHAN set the range of input delay lag channels to be transformed into frequency channels. The number of resulting frequency channels is one-half the delay lags transformed + 1 (Mk II VLB is single side band). Eg., if BCHAN=2 and ECHAN=12, then six frequency channels are created. Now, you may use BDROP and EDROP to delete frequency channels from the low and high ends of the bandpass. If BDROP=1 and EDROP=1, channels 2,3,4 and 5 of the original six are copied into AIPS. BDROP and EDROP should be useful in removing band-edge distortions before the global fringe fitting process. The most common transform mode to-date is to use BCHAN=4, ECHAN=10 which transforms 7 delay lags centered on lag channel # 7 into 4 frequency channels. For most Mk II spectral line data which is still in the lag domain, the most common values of BCHAN and ECHAN are 1 and 192 respectively, this will produce a 96 channel spectrum within AIPS. U, V, W and VLBINPRM(7) There are two options for generating the u, v and w values carried in the AIPS visibility records. 1) Set VLBINPRM(7) = 1, VLBIN will copy u, v and w (processor delay * obs. freq) from the data record headers in the input VLB data set. However, most of the time u = v = 0.0 in the VLB data records. Then VLBIN will calculate u and v using the precessed source coordinates and the source hour angle at Greenwich at the processor station 'A' wavefront arrival time : u = BX*SIN(SHA) - BY*COS(SHA) v = -BX*SIN(DEC)*COS(SHA) - BY*SIN(DEC)*SIN(SHA) + BZ*COS(DEC) 2) The default setting VLBINPRM(7) <= 0 forces VLBIN to recalculate u, v and w. FQ Numbers FQ numbers are assigned to data whose frequency characteristics differ from previous data, i.e. bandwidths are different, a different sideband is recorded, or the frequency itself differs by an amount greater than the maximum Doppler shift possible (i.e. a difference greater than that caused by a velocity change of 30km/s). It is also useful for the user to have some control over this selection so VLBINPRM(11) allows the definition of a frequency tolerance. The default value of this parameter, i.e. VLBINPRM(11)=0.0 will result in all data having the same FQ number; if VLBINPRM(11) < 0 then the frequency tolerance will be the maximum frequency difference due to the Earth's rotation (i.e. 10**-4 * observing frequency). If VLBINPRM(11) > 0 then the vlaue is taken to be the desired frequency tolerance in kHz. An example: if the user had observed the 1665 and 1667 MHz line of OH and wanted to just separate the two so he/she could process all of the 1665 MHz data in one pass, then VLBINPRM(11) should be set to 500.0, i.e. 500kHz, that allows a window of 1.0 MHz, and anything that lies inside the first frequency found +/- 1 MHz would be assigned the same FQ number. FREQUENCY SELECTION There is an alternative way of selecting frequncies than by assigning FQ numbers. The user can select a frequency range and/or bandwidth to accept. If VLBINPRM(13) > 0 then its value is assumed to be the bandwidth in kHz that you wish to read, if = 0 then all bandwidths are read and assigned multiple FQ values. If the user wishes to select a frequency range say from 1664.0 - 1666.0 MHz to read then he/she should use VLBINPRM(14) and (15). Set VLBINPRM(14) to be the centre of the frequency range to read (in MHz), then set VLBINPRM(15) to be 0.5 of the frequency range to be read. In the above example that would mean setting VLBINPRM(14)=1665.0, VLBINPRM(15)=1.0 REFERENCE FREQUENCY Often the user will read a series of files into AIPS and will wish to concatanate them later. This is made much simpler if the catalogue reference frequencies are the same, this may not generally be the case for spectral line experiments. You can force the reference frequency to be a certain value if KEYVALUE is not zero. KEYVALUE is a 2 element array, to set the reference frequency to 22236.91 MHz you would set KEYVAL = 22236e6,0.910.0e3. TIMERANG The TIMERANG input parameters are used to select input data within a time range. Note, the TIMERANG(1) and TIMERANG(5) day numbers are days of the year numbers. The VLBI data records keep the day specification in days of the year number. The AIPS file created by VLBIN, on the other hand, keeps day specifications in each AIPS data record in terms of a relative day number. The AIPS relative day numbers are with respect to the reference date carried in the AIPS catalog header. The reference day number is usually the first day in the observation, so the AIPS day numbers in the data records are 0, 1, 2, so forth. ANTENNA TABLES FILE: The header of the AN tables file contains information concerning the array coordinates, the source coordinates and the UT1, UTC and IAT times used. The GST, RA and DEC are given with respect to UT = 0 hr on the reference day indicated in the AN header. In fact, the GST, RA and DEC are copied from the first VLBI scan header record encountered by VLBIN. Warning: the RA and DEC were actually precessed to UT = 12 hr on the reference date (in the VLB prep-tape program). EXECUTION TIME: The cpu time required for execution of VLBIN may be estimated from the following formula : CPU (seconds) = N-total * 2E-03 + N-aips * 13.3E-03, where N-total is the total number of visibility records in the INFILE (input) data set. N-total includes the visibility records from all sources in the INFILE data set. N-aips is the number of visibility records that VLBIN will create in AIPS (you could use NPOINTS). OUTPUT FILE SIZE: The size of the AIPS uv file created by VLBIN may be estimated : Number of VAX blocks = NRECS * ( N-ran * 4 + N-cmplx * N-freq * N-pol * 4 ) / 512, where NRECS is the number of visibility records in the uv file, where N-ran is the number of random parameters per uv record (usually 5), N-cmplx is the number of words per visibility (usually 3), N-freq is the number of frequency channels (usually 4 or 6) and N-pol is the number of polarizations in the uv file (usually 1).