B2FITS B2FITS converts output data files (PCR files) from the JPL/Caltech Block-2 VLBI Correlator into AIPS-compatible UV-FITS format. The output UV-FITS file is a multisource file sorted in 'TB' order (AIPS nomenclature) and duplicate data points are removed. (Versions of B2FITS earlier than 4.0 produced an AIPS single-source file.) The file produced by B2FITS can be read into AIPS using the AIPS task FITLD or UVLOD. B2FITS produces a listing file which contains information about the input files, the experiment parameters, and the output file. PCR files have a VMS-specific format, so B2FITS must be run under the VMS operating system. The output FITS files are portable and can be transferred to other machines by tape or by a binary network file transfer protocol (e.g., binary ftp). Example $ B2FITS input = C50G2_163_0600 output = C50G2_CTA102_C.UVF listfile = C50G2_CTA102_C.LIS imname = C50G2_CTA102_C imclass = UVF spikelim = 0.05 source = CTA102 refday = 160 stations = ONSA, BONN, WSRT, JBNK2, BOLOGNA, HART, HSTK, NRAO, IOWA, FDVS, PIETOWN, VLAE8, OVRO / Parameters Parameter INPUT must be specified; the others are optional. End the list of parameters with a slash (/). -- File names (INPUT, OUTPUT, LISTFILE) INPUT = "filename" : the name of the input Block-2 PCR file(s). Wild cards are permitted (e.g., INPUT = VLBPROC:[SCU...]*.PCR), but the total number of files specified must not exceed 100. See the note below for a method of extending the list of input files. If disk, directory, or file type are not specified, B2FITS assumes the default disk and directory VLB_PCR and the default file type .PCR. OUTPUT = "filename" : a name for the new FITS-format file. If this is not specified, a filename of the form xxxx.UVF is used, where xxxx is derived from the source name. LISTFILE = "filename" : a name for the listing file. The default file name is B2FITS_LOG.LIS, and the default file type is .LIS. B2FITS Page 2 -- Data selection parameters (EXPERIMENT, SOURCE, STATIONS, START, STOP, SPIKELIM, BADCHAN, INVALIDS): Use these parameters to select a subset of the data from the input files. You can select only one source from one experiment. To determine the experiment, source, and station names in the input files, use program B2PS. EXPERIMENT="name" : B2FITS will extract data for the specified experiment from the input file (the experiment name is specified in the setup blocks for the Block-2 correlator). If EXPERIMENT="*" is specified (the default), B2FITS will extract data for all experiments that it finds in the input files. SOURCE="name" : B2FITS will extract data for the specified source from the input file. If SOURCE="*" is specified (the default), B2FITS will extract data for all the sources it finds in the requested experiment(s) in the input files. STATions = name1,name2,... (up to 32 station names) : B2FITS will extract data for the specified stations (antennas) from the input file. This parameter should normally be specified. The order of the stations fixes the way they will be numbered in the FITS file (and hence in AIPS); it is permissible to include names of stations for which there are no data in the input file. NOTE: if you intend to merge together two or more datasets from B2FITS using AIPS task DBCON, you MUST specify the same STATIONS list in all the B2FITS runs. If STATIONS="*" is specified, B2FITS will extract data for all the stations it finds for the requested experiment and source; the stations will be numbered in the order in which it finds them. START = day,hh:mm:ss STOP = day,hh:mm:ss : select data between the specified UT start and stop times; "day" is a day-number (day of year). The default is to select all data. SPIKELIM = x.xx : threshold for "spike" detection; default 1.0. Spikes are data points with large correlation coefficients, usually caused by hardware errors. If the correlation coefficient in Sin or Cos of any frequency bin exceeds the threshold, the integration is rejected. BADCHAN = baseline1,channel1, baseline2,channel2, ...: this parameter tells B2FITS to ignore all data from selected hardware channels. This may be useful if one or more channels are malfunctioning and the data are duplicated in another channel (or another input file). "baseline" specifies the hardware baseline number (1 through 6) and "channel" specifies the hardware channel number (1 through 28). Up to 14 baseline-channel pairs can be specified. INVALIDS = number (default 0.5) : For each integration on each baseline, B2FITS checks the number of "invalid bits" relative to maximum possible (8 million bits per 2 second integration), B2FITS Page 3 and rejects the integration if the fraction exceeds this threshold. Only a single threshold may be set for each run of B2FITS. "Invalid bits" occur due to (1) time code and sync information encoded on the tape; (2) tape decode problems; and (3) certain hardware operations. The "expected" number for perfect (MKII) tape playback is about 0.15, but can be lower depending on the baseline orientation. The default INVALIDS = 0.5 should rarely result data discarded. For good tape playback, INVALIDS = 0.25 or 0.3 should discard data only when bursts of dropouts occur (or sometimes during tape syncing). Incorrectly recorded tapes (e.g., head-switch in middle of frame!) may be recoverable, but may require INVALIDS = 0.8 or higher. -- Parameters for AIPS (STOKES, OBSERVER, USERNO, IMNAME, IMCLASS, IMSEQ, REFDAY, TAI-UTC, EPOCH) STOKES = n : as the Block-2 PCR files do not specify the polarization of the data, but AIPS does, you should specify the polarization with this parameter. Possible values for circularly-polarized feeds are: -1 (RR), -2 (LL), -3(RL), and -4 (LR). See the AIPS programmer's manual for other options. The default is STOKES=-2 as most VLB network experiments are observed in LCP. OBSERVER = "name" : may be used to give the name of the observer. The default is the experiment name as specified for correlation. USERNO = n : may be used to specify the AIPS user number, if desired. This is rarely if ever needed. IMNAME = "name" IMCLASS = "class" IMSEQ = n : these three parameters can be specified to indicate to UVLOD what the AIPS filename should be, if desired. If they are not specified, they are not recorded in the output file. You can supply values when you run UVLOD if you wish. REFDAY = n : specifies the "reference day number" for the output file. The value (n) is a day-of-year (1 = January 1, 365 or 366 = December 31). If REFDAY is omitted or set to zero, B2FITS uses the day number of the earliest observation found in the input files as the reference day number. REFDAY can be abbreviated to REF. If you run B2FITS on a single experiment in several separate pieces, specify the same REFDAY in each B2FITS run. Otherwise, the resulting AIPS datasets with different reference days cannot be combined. Usually, REFDAY should be the first day of the experiment. TAI-UTC = m : specifies the Delta-AT correction, the difference TAI minus UTC, where TAI is International Atomic Time and UTC is Universal Coordinated Time. The time-tags on the data from the Correlator are UTC, while those on the data in the FITS file are TAI, as required by AIPS. The correct value, for past years, can be found on page K9 of the Astronomical B2FITS Page 4 Almanac; it is always an integer, and it can jump on Jan 1 or Jul 1 of each year when leap seconds are inserted in UTC. If you do not specify this correction (or specify 0), the value that B2FITS uses will probably be correct. [Versions 2.7 and earlier used an approximate value (Year - 1973 + 12), which is incorrect by up to 5 seconds.] EPOCH = DATE or EPOCH = 1950 : specifies whether B2FITS should write the apparent coordinates of date or the mean coordinates of epoch B1950.0 in the header of the FITS file. EPOCH=1950 (the default) is recommended to avoid problems in AIPS (but note that if you use this option, the B1950 coordinates must have been supplied at correlation time). Input file list If the required input files cannot be specified with a single VMS file specification (possibly including wild cards), VMS "search lists" can be used to extend the list of file names. Define a VMS logical name for the input files, and specify the logical name as the value of the INPUT parameter, e.g.: $ DEFINE PCRFILES CITSCR:[SCU.PASS1]*.GPR,CITSCR:[SCU.PASS2]*.GPR $ B2FITS INPUT = "PCRFILES" ... The DEFINE command defines a list of input file specifications, separated by commas. For more information on search lists and the DEFINE command, see the VMS manuals. Note especially the following two restrictions: 1. Specify disk and directory in all the elements of the search list; they aren't inherited from one to the next. 2. Specify at least one wild card in every element (wild cards are *, % , and [in directories] ...); the search for more matching files stops after the first name that doesn't include a wild card. Apart from these two restrictions (which are peculiarities, rather than bugs, in VMS), this technique should work for any program that accepts wild cards in its input file specification (e.g., MERGE, LIST, GPS). Dividing an experiment into pieces It is possible to divide an experiment into several pieces, process each piece separately with B2FITS, and combine the resulting files into one database within AIPS using the AIPS task DBCON. If you plan to do this, beware of the following: B2FITS Page 5 1. If you run B2FITS in several separate pieces, use the same reference day number (REFDAY) in each B2FITS run. Otherwise, your sub-array data with different reference days cannot be merged. To check what reference day was actually used by B2FITS, look at the B2FITS log file; or examine a FITSLIST listing of the B2FITS output file - the reference date is parameter DATE-OBS. 2. If two B2FITS files are to be combined, they must both have the same antenna tables. You ensure this by giving the same antenna list (STATIONS parameter) in each run of B2FITS. If you specify an antenna for which there are no data, B2FITS will not be able to find the antenna coordinates, and will set them to zero. Then when you merge this dataset with another which contains data for the antenna, you may find that DBCON picks up the incorrect (zero) coordinates for the antenna instead of the correct ones. This usually doesn't matter as far as AIPS is concerned, but the CITVLB programs will complain. One solution for this problem is to insert the correct coordinates using VLBEDIT after you have copied the data into Merge format. 3. Specify DOARRAY = TRUE in task DBCON (see the EXPLAIN file for DBCON). Scratch Files B2FITS uses the VMS SORT utility to sort the data into TB order. This utility creates two anonymous work-space files. The maximum size of each of these files (in bytes) is NVIS * 4 * (7 + 2*NFRQ) where NVIS is the number of visibility points and NFRQ is the number of frequency channels. As an example, if NFRQ is 4, then 1024 visibilities occupy 120 disk blocks (1 block = 512 bytes). One hour of 2-second integrations on 8 antennas (28 baselines) gives 50,400 visibilities, which would occupy about 6000 disk blocks. The two scratch files can be smaller than this, but the exact size will depend on how much memory is available when your job runs, and on how well-sorted the data are to start with. By default, these two files will be put on the SYS$SCRATCH disk, but their locations can be changed by defining logical names SORTWORK0 and SORTWORK1, e.g., $ DEFINE SORTWORK0 CITSCR $ DEFINE SORTWORK1 VLBPROC $ B2FITS ... Copying a FITS-format file to tape Use a procedure similar to the following: this example uses tape drive MTA0 at 1600 bpi. A different density (800 or 6250) can be specified on the MOUNT command if required, but /FOREIGN, /BLOCKSIZE=28800 and /RECORDSIZE=2880 MUST be specified. The SET MAGTAPE/SKIP=END command positions the tape for writing after the last file previously recorded on the tape. OMIT this command if you want to start writing at the beginning of the tape. B2FITS Page 6 $ ALLOCATE MTA0: (mount your tape on MTA0:) $ MOUNT/FOREIGN/DENSITY=1600/BLOCK=28800/RECORD=2880 MTA0: $ SET MAGTAPE/SKIP=END MTA0: $ COPY 0814.UVF MTA0: $ COPY 3C273.UVF MTA0: ... $ DISMOUNT MTA0: $ DEALLOCATE MTA0: The above commands produce a tape with a blocking factor of 10 (10 logical records per physical block on tape). Smaller blocking factors are permissible but are less efficient in use of tape. FITS-format tapes and disk files can be examined with program FITSLIST. Limitations 1. Up to 32 antennas are accepted. 2. Up to 100 input files are accepted (but only one input file specification). 3. The (u,v,w) coordinates are not computed by B2FITS. You must use the AIPS task UVFIX to compute them before running FRING or other AIPS tasks. 4. Data selection by frequency is not yet implemented. 5. Combination of Mark-III channels into a single dataset is not yet implemented. 6. All the input data must be from the same year of observation; data obtained in different years (or with different values of TAI-UTC) cannot be mixed. History Version 1.0: 1986 Jun 1 - new program (TJP). Version 1.1: 1986 Aug 27 - do not quit on invalid configuration. Version 1.2: 1986 Aug 28 - convert character parameters to uppercase. Version 1.3: 1986 Oct 6 - skip records to find PRC table. Version 1.4: 1986 Oct 15 - more information about spikes. Version 1.5: 1986 Oct 22 - add LISTFILE parameter. Version 1.6: 1986 Dec 19 - add TAI-UTC correction. Version 1.7: 1986 Dec 22 - change scaling of time tags in FITS file; unit is now 1/20 sec. Version 1.8: 1986 Dec 23 - new format for phase model table. Version 1.9: 1987 Jan 13 - better error checking on output. Version 2.0: 1987 Feb 17 - do not write uvw in scratch file. Version 2.1: 1987 Apr 20 - fix bug: TAI-UTC was ignored. Version 2.2: 1987 Jun 29 - report correlator program version; handle new phase model format. B2FITS Page 7 Version 2.3: 1987 Nov 5 - new selection of data in READSCRATCH. Version 2.4: 1987 Nov 24 - add BADCHAN parameter. Version 2.5: 1988 Jul 5 - hardware baseline order changed from 12 13 14 23 24 34 to 12 13 23 14 24 34. Version 2.6: 1988 Sep 12 - add EPOCH parameter. Version 2.7: 1989 Jan 31 - add correln time to output, etc. Version 2.8: 1990 Apr 5 - allow antenna names longer than 8 chars; use correct TAI-UTC; check COFFLCD flags. Version 2.9: 1990 Aug 3 - allow up to 14 BADCHANs. Version 2.10: 1990 Oct 21 - add INVALIDS parameter; check correlator flags better. Version 2.11: 1990 Nov 27 - display operator comments. Version 3.0: 1992 Apr 29 - default OBSERVER=expt; check UT1-UTC etc. Version 4.0: 1992 Nov 12 - write multisource file.