AIPS HELP file for VLBIN in 31DEC24
As of Fri Apr 26 18:49:08 2024
VLBIN: Task which creates uv data from NRAO-DECODE VLBI data.
INPUTS
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.
HELP SECTION
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)
EXPLAIN SECTION
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).