AIPS HELP file for M3TAR in 31DEC24
As of Wed Nov 6 7:45:51 2024
M3TAR: Task which reads Haystack MKIII VLBI format "A" TAR's
INPUTS
INFILE Experiment info file name
IN2FILE A-file name - see HELP
INTAPE Tape drive number
NFILES Number of TAR's to skip
REFDATE Reference date. 'dd/mm/yy'
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) .ge. 1 => 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
M3TAR
Task: This task reads MKIII VLBI data from Haystack "A" tapes,
when they come as standard UNIX TAR's.
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 M3TAR).
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 TFILE.
If IN2FILE = ' ', all scans will be read from the
tape.
INTAPE.....Tape drive from which to read data.
NFILES.....Number of Tape ARchives to skip on the tape.
REFDATE....Reference date 'dd/mm/yy', ' ' => first found
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.
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) .ge. 1 means do not make Fractional Bit Shift
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.
(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
M3TAR : Creates an AIPS uv data set from Haystack MKIII A TAR's.
DOCUMENTOR : W. D. Cotton, NRAO/CV
RELATED TASKS : TFILE
PURPOSE
M3TAR creates an AIPS uv data set from a Haystack MkIII
"A tape" in the form of UNIX TAR.
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 M3TAR starts up, it
will list the stations it found in INFILE.
The first time M3TAR 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 M3TAR 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, M3TAR 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
M3TAR. 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. M3TAR 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