AIPS HELP file for MK3IN in 31DEC24
As of Thu Apr 25 15:00:19 2024
MK3IN: Task which reads Haystack MKIII VLBI format "A" tapes
INPUTS
INFILE Experiment info file name
IN2FILE A-file name - see HELP
INTAPE Tape drive number
NFILES Number of files to skip
REFDATE Reference date. 'yyyymmdd'
TIMERANG Timerange selected
SOURCES Source selection list
DOUVCOMP -1.0 1.0 1 (T) => compressed data
DOCONCAT -1.0 1.0 1 (T) => append data to old
files (use with caution).
OUTNAME Output UV file name (name)
OUTCLASS Output UV file name (class)
OUTSEQ -1.0 9999.0 Output UV file name (seq. #)
OUTDISK 0.0 9.0 Output UV file disk unit #.
APARM Control information
(1) = CL table time
increment (min).
(2) = Maximum tape parity
error rate (0=> 0.01)
(3) = Maximum dropout rate
accepted (0=> 0.5)
(4) <0.5 => full FBS corr.
>0.5 => phase-only FBS
>1.5 => suppress FBS
(5) = No of files to read
from tape (0=> to EOT)
(6) 0 => apply all error
checks to data
1 => ignore CRCC errors
2 => ignore slip sync
3 => ignore both CRCC
and slipped sync
(7) > 0 = separate sidebands
(8) > 0 = accept data with
LO offset
(9) = Print level (0..4)
*** DEBUG ***
(10) = 1=> dump headers
2=> dump header, data
HELP SECTION
MK3IN
Task: This task reads MKIII VLBI data from Haystack "A" tapes.
An ASCII experiment file is read from disk to assign
antenna numbers and obtain other information. Any type
52 (Haystack FRNGE output) records are written to an AIPS
HF table (see EXPLAIN MK3IN).
Adverbs:
INFILE.....Name of ASCII experiment information file.
Eg., disk$res:[username]STATIONS.DAT under VMS or
MYVLB:STATIONS.DAT under UNIX
IN2FILE....Name of ASCII file containing list of scans to
be read from an 'A' tape. This file can be
generated by hand, or using the task AFILE.
If IN2FILE = ' ', all scans will be read from the
tape.
INTAPE.....Tape drive from which to read data.
NFILES.....Number of files to skip on the tape.
REFDATE....Reference date 'yyyymmdd', ' ' => first found. ('dd/mm/yy'
is accepted too, but deprecated.) Better get it right!!!
Data may not be in time order on the tape and the default
reference date is the first date found. Data on days
before the reference data will have negative times and will
be rejected by the default TIMERANG as well as causing
other troubles displaying the data. (Task FXTIM may be
used to correct the times if you have this problem.)
The reference day used should be one for which there is
actual data or the antenna table will end up with incorrect
data (a warning message is given in this case).
TIMERANG...Range of UTC times to be read wrt REFDATE. 0=>all.
If any part of a scan is selected then that whole
scan is read. See EXPLAIN MK3IN for details.
SOURCES....Sources to be included in or excluded from the
output file. If the first character of any
element is "-" then all named sources are excluded
otherwise all named sources are included. Names
should correspond to those used in the Mk3
experiment file. If all entries are blank then
all sources are selected.
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.
DOCONCAT...If true (>0) then data is to be appended to an
existing file if possible. Possible output files
can be selected by OUTNAME, OUTDISK and OUTSEQ.
Use this option with CAUTION.
OUTNAME....Output UV file name (name). Standard behavior
with default 'MKIII DATA'.
OUTCLASS...Output UV file name (class). Standard defaults.
OUTSEQ.....Output UV file name (seq. #). 0 => highest unique.
OUTDISK....Disk drive # of output UV file. 0 => highest disk
with space for the file.
APARM......Task control information.
(1) = Time increment in CL table entries in min.
0 => 2 min. <0 => use PRT (near center) time
only
(2) = Maximum parity error rate on the
MKIII data tapes for good data. 0=> 0.01
(3) = Maximum dropout rate on the MKIII
data tapes for good data. 0=> 0.5
(4) <0.5 => make full amplitude-phase
Fractional Bit Shift (FBS) correction.
>0.5 => make phase-only FBS correction.
>1.5 => do not make FBS corrections.
(5) = Number of file to read from tape 0=> to EOT.
(6) = Data rejection criteria
0 => apply all MK3 error checks
1 => ignore CRCC errors in sync blocks
2 => ignore slipped sync errors (XS/YS)
3 => ignore both CRCC and slipped sync
(7) If > 0 then separate sidebands into different
IF. This may fail if it exceeds the max.
number of IFs.
(8) If > 0 then accept data with an LO offset,
otherwise terminate job. Note that no
correction is yet made for LO offsets.
(9) = Print level 0=> Source hdr per scan;
1=> include scan error summary and
correlator model summary; 2 => list
each correlator separately; 3 => print
COREL file names; 4=> error summary per
correlator module serial no.
(10) = flag indicating a dump of the raw data is
requested on Fortran unit 9.
0 => no dump
1 => header records only
2 => headers plus data (type 51 records)
EXPLAIN SECTION
MK3IN : Creates an AIPS uv data set from Haystack MKIII A tapes.
DOCUMENTOR : W. D. Cotton, NRAO/CV
RELATED TASKS : MK3TX, AFILE
PURPOSE
MK3IN creates an AIPS uv data set from a Haystack MkIII
"A tape".
COMMENTS
INFILE:
A separate external file MUST be created by the user (and
text editor) containing the names of 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'
Note: no case conversion is done so the case should match the
antenna name as given on the tape. When MK3IN starts up, it
will list the stations it found in INFILE. Task MK3TX should
help in the determination of the antenna names used.
The first time MK3IN is run on data from an experiment,
antenna names 'ANY' may be used and any antennas found (up to
the number of 'ANY's in STATIONS) will be accepted. If more
data is to be read from other tapes then the STATIONS array must
be filled in using the values in the AN table. The order of the
antenna names in STATIONS defines the antenna numbers used
inside the AIPS data base. To insure that a given antenna is
always given the same number be sure to update the values in
STATIONS after any execution of MK3IN in which a new antenna has
been added as a result of an 'ANY' in the STATIONS list.
The times in the data set can be either in UTC or IAT. To
use IAT the correction from UTC to IAT (IAT-UTC) should be given
as the parameter TIMEOFF as in:
TIMEOFF=23.0
If no value of TIMEOFF (or 0.0) is given then the time system is
assumed to be in UTC.
The Stokes parameter range of the output file is set using the
parameter:
STOKES= subset of {'RR','LL','RL','LR'}. The default Stokes is
'LL'.
If polarization sensitive data is to be read in this is
indicated by the parameter DOPOL=1; if data are all of the same
Stokes' type this is indicated by DOPOL=-1 (the default).
The MKIII correlators usually indicate different
polarizations by using frequency codes; as these codes are not
entirely consistent they may be entered using FREQCODE as:
FREQCODE='R','L','r',l' (where R=RR; L=LL; r=RL; l=LR).
If DOPOL=1 the defaults are 'R','L','r' and 'l' else any
frequency code is selected.
The following are optional parameters in the experiment
file, and will default to the values found for the first scan.
NO_LAGS - Number of XC lags in output file (only correlation
functions with this lag range will be translated;
autocorrelation functions with half this range).
NO_IF - Number of IF's in the output file.
SIDEBAND - 'DOUBLE' => concatenate video converter USB, LSB
to form one IF (default).
Enter the delimiter character (/) at the end of the experiment
information.
The experiment definition may be followed by an optional
list of antenna aliases. This comprises a line containing
the keyword ALIASES and a delimeter character (/) followed
by a list of paired strings. If the first string of any pair
matches an antenna name in the input data then the antenna
name will be replaced by the second string. This is done
before matching the antenna names against the antenna list
given in the experiment definition.
Here is an example experiment definition file using aliases.
STATIONS='TDRSE', 'USUDA', 'DSS43'
/
ALIASES /
'TDRS1' 'TDRSE'
'TDRS2' 'TDRSE'
'TDRS3' 'TDRSE'
'TDRS4' 'TDRSE'
/
In this experiment data from TDRSE was correlated using four
different names. With the alias list given, MK3IN will recognize
all four names as referring to the same telescope and will name
this telescope TDRSE in the AIPS data file.
Examples:
INFILE='disk$res:[username]stations.dat' (VMS)
INFILE='MYAREA:STATIONS.DAT' (Unix)
where MYAREA is an environment variable set before
starting AIPS:
percentsetenv MYAREA /mnt/username.
Note: All file names used on a Unix system must have only
uppercase characters in the name.
The abbreviations used in the error summary have the following
meaning:
Code Desc
MOD Correlator module serial number (0 => module sum).
CS Correlate suppress
TS Tapes out of sync
AP AP array overrun
PP No PP update
YS Y slipped sync.
XS X slipped sync.
CL No X clock or no Y clock.
TM Unexpected tape time.
CRCC CRCC error in remote station sync block,
reference station sync block.
XP X parity errors exceed parity error rate
for good data.
YP Y parity errors exceed parity error rate
for good data.
XD Fewer than allowed fraction of the nominal
number of bits are correlated within the AP
in the cos channel (set by maximum dropout rate).
YD As for XD but applies to the sine channel
correlation count (ignored for AC functions).
MT Module termination status bad (ie operator
reports error condition).
3A MKIIIA error condition.
TOT Total number of module output records read.
Each column indicates the percentage of module output records
with the appropriate error condition. The field Nvis=nnn
indicates the number of full correlation functions passed by
MK3IN. The field Good=xx percent indicates what percentage of
correlation functions was passed.
Multiband Observing
A special problem occurs when data at different observing
bands are observed simultaneously, e.g. S/X geodetic style
observations. MK3IN will read all data and place them in the
same file. For purposes of calibration and imaging these must
be seperated into seperate files using UVCOP.
FRNGE output
The output of the Haystack baseline fringe fitting routine
FRNGE is copied to the AIPS table of type HF. The labels of the
column are the names of the entries in the Haystack
documentation. The contents of this table with a description
from Haystack documentation are given in the following:
Col # Label Type(dim) Description
1 XY C*2 Baseline code, 1 char per antenna.
2 UTC TAG I(6) UTC time tag (YMDHMS) EPOCH for delay
and rate .
3 VLB2 UTC I(6) UTC of FRNGE processing (YMDHMS)
4 ARCHIV I(4) ARCHIV
5 SAMPRATE I Sample rate in kbits/sec
6 FR/PP I no. frames per parameter period
7 PASS NO. I Pass number
8 NO. CHANELS I #U/L sideband pairs included in this
processing (i.e. # of discrete LO
frequencies)
9 NO. OF AP I(28) #Accumulation periods by sideband by
channel
10 RECTRACK I(2,2,14) Track # table in order of:
Station #, Refer/partn Sideband, Channel #
11 COREL VERSION NO. I COREL version #
12 UTCM TAG I(6) UTC time tag (YMDHMS) EPOCH for
"central" EPOCH
13 LU OF PRINTOUT I LU of printout (for FRNGP)
14 REF. TAPE DRIVE NO. I Reference tape drive number
15 REM. TAPE DRIVE NO. I Remote tape drive number
16 SPECIAL OPTIONS I Special options NAME(211)
17 INTEGER PARM(250) I Integer value of PARAM(250) [=999
for special PCAL by AP]
18 CORELXTNT I(2,14) COREL extent# from which each
track is taken.
19 CALBYFRQ I(3,2,14) Phase-cal amp, phase and freq by
station and channel normalized as follows:
AMP 0 to 10000(in voltage) -1=manual cal
PHS -18000 to +18000
frq kHz
20 PROCUTC I(2,14) COREL processing UT (YDDD) by
sideband and channel.
21 ERRORATE I(2,2,14) Tape error rate by station,
sideband and channel encoded as:
1000*LOGT(error rate) (=-32000 if no errors)
22 INDEX I(2,14) COREL index #s by sideband and
FRNGE CH#
23 FRNGE ERROR CODE I FRNGE error code 0=OK NE.0 Don't use
24 SBDOFFST FLAG I flag 1=this run had sideband fixup.
25 STAR ID C*8 Radio source name
26 BASELINE ANT1 C*8 First antenna name of baseline
27 BASELINE ANT2 C*8 Second antenna name of baseline
28 CORELFILE C*6 COREL correlation output
file name
29 TAPEID ANT1 C*8 first raw-data tape ID label
30 TAPEID ANT2 C*8 second raw-data tape ID label
31 VLB2PRG C*6 FRNGE program version YYMMDD
32 RUN CODE C*8 Run code, e.g. "329-1300"
33 FRNGE QUALITY CODE C*1 FRNGE quality code 0=no good,
1=very poor, 9=very good, A=has FRNGE error
code=1,B=2 etc.
34 FREQ. GROUP CODE C*2 Frequency group code
35 ORIG. COREL FILE NAME C*6 Original COREL file name
36 TAPE Q CODE C*6 Tape Q code
37 REF OCCUPATION CODE C*8 Ref station occupation code
38 REM OCCUPATION CODE C*8 Rem station occupation code
39 RFREQ D(14) LO frequencies (MHz) by channel
40 REF FREQ D RF freq (MHz) to which phase is
referred
41 DEL OBSV D Observed group delay in
microseconds equals single band delay if only
one freq. processed. DELOBSV=T2-T1, T1=time
of arrival at site 1 (reference site) as
measured by the site clock at site 1, T2=time
of signal arrival at site 2 as measured by
site clock at site 2. The signal in question
is the one which arrives at site 1 at a UTC
time equal to that given as the UTC epoch.
42 RATOBSV D Observed delay rate (usec/sec)
corrected for the phase cal rate.
43 NB DELAY D Narrow-band group-delay (usec)
44 DGPD D group delay ambig. (usec)
45 BTE0 D apriori clock (usec)
46 EPOCH0 D ref. st. clock epoch (usec)
47 DEL OBSVM D observed delay at central epoch
48 RAT OBSVM D observed delay rate at central epoch
49 DLY2 D phase delay at EPO+1 sec
50 DLY3 D phase delay at EPO-1 sec.
51 AMBYFRQ R(2,14) Amp and phase by channel 1=100 percent
phase=-180 to 180 deg. residual to COREL and
uncorrected for PCAL rate.
52 PHASECAL R(2) Phase cal rate by station (usec/sec)
53 DELRESID R Delay residual to COREL a priori.
54 DELSIGMA R Calculated delay error (usec)
55 RATRESID R Delay-rate residual to COREL a priori
(usec/sec) corrected for phase cal rates.
56 RATSIGMA R Calculate delay-rate error (usec/sec)
57 COHERCOR R Coherent multi-freq correlation
coefficient. (1=100 percent correlation)
58 TOTPHASE R Total observed fringe phase (deg)
59 UVF/ASEC R(2) Fringes per asec in N-S and E-W
60 STARELEV R(2) Calculated star elevations run reference
time by station (deg).
61 AAMP FRNGE R amplitude from incoherent addition of
frequency channels.
62 URVRSEC R(2) Rate derivatives mHz/sec arc
63 SRCHPAR R(6) Search parameters
64 DEPSBRES R Single band delay residual (usec)
65 SNR R Signal to noise ratio in sigma.
66 PROB R Probability of a false detection.
67 INCOH R Incoherent segmented fringe amp. in
units of 10,000.
68 EARP R total phase refered to an epoch at
time the signal reaches the center of the
earth.
69 REARP R Residual phase corrected to earth
centered epoch
70 START R Start time in seconds past hour
71 STOP R Stop time in seconds past hour
72 EPD R Epoch offset from center of run in
sec.
73 DUR R Effective run duration in seconds.
74 DELSS R Single-band delay error in microsec.
75 QB R Ratio of min to max data accepted in percent
76 DISCD R percent data discarded
77 TOTPM R Total phase at central epoch
Notice about using DAT tapes
The current practice at the MkIII correlators (3/92) appears
to be to copy entire 9 track archive tapes INCLUDING the EOI
(double file mark). Strictly speaking, data after an EOI
mark is inaccessable and on some systems (Suns?) this may be
true in practice. If MK3IN does not recover all of the data
that you expect then tell it "GO" a second (or further) time
WITHOUT rewinding the tape until it no longer finds any data.