DOCUMENTATION FOR FITS IMPORT/EXPORT PROGRAMS FOR UNIPOPS. (21 Feb 1992) 1. Importing and Exporting FITS Format Tapes or Files to/from UniPops: ---------------------------------------------------------------------- The following 3 commands write or read FITS format files: uni2fits - create Single-Dish FITS file from UniPops file. fits2uni - create UniPops file from SD-FITS file. readfits - list SD-FITS headers or a scan summary. They are user-friendly front-ends to the programs: u2f -- creates SD-FITS file from UniPops file using standard input and standard output f2u -- creates UniPops file from SD-FITS file using standard input and standard output These two programs probably should never be user directly by the general user; instead one should use "uni2fits", "fits2uni", or "readfits." All the programs can be used while running UniPops or outside of UniPops. If you are in UniPops, precede each command with the word "system". That is, when in UniPops, type, for example: system uni2fits but, at the Unix prompt, type: uni2fits 2. Running "uni2fits", "fits2uni", and "readfits" -------------------------------------------------- When you type "uni2fits", "fits2uni", and "readfits", you are asked a series of questions, most of which are self-explanatory. For example, you must give the name of the UniPops data file (usually LDATA, LSAVE, or LKEEP) to be used for input (uni2fits) or output (fits2uni). When running "uni2fits", you may select a range of scan numbers to be included. You can also select only line data or continuum data from the input file. If you are writing or reading tape, you must enter a device name for the tape drive. Device names, listed in the following table, depend on which workstation and what kind of tape you are using. If your workstation is not in this list, see if the local tape drive is labeled or seek the help of a UniPops Guru. Tape Drive Device Name ----------------------------------------------------------------------- location workstation 9-track 9-track exabyte SUN cartridge 1600 BPI 6250 BPI -------- ------------ -------- -------- -------- ------------- 140-ft Nath rst9 rst17 rst0 NA Jy Lab Etamin NA NA NA NA Jy Lab Gallina NA NA NA rst0 Jy Lab Lodestar NA NA NA rst0 Jy Lab Fomalhaut rst1 rst1 NA NA -------- ------------ -------- -------- -------- ------------- CV U U U U U -------- ------------ -------- -------- -------- ------------- Tucson U U U U U ------------------------------------------------------------------------ NA = Not Available; U = Unknown 3. Running "u2f" and "f2u". ------------------------------ The scripts "uni2fits", "fits2uni", and "readfits" are user-friendly front-ends to the "u2f" and "f2u" programs. Basically, "uni2fits", "readfits", and "fits2uni" asks the user a set of questions and passes the answers to "u2f" or "f2u". The "u2f" and "f2u" programs do all of the real work in converting the files. If you want, you can use "u2f" and "f2u" directly but we suggest that you use the intermediary "uni2fits", "fits2uni", and "readfits" programs. Nevertheless, if you MUST use "u2f" or "f2u", you should first get documentation about the "u2f" and "f2u" programs by typing either: "f2u ?", or "u2f ?" For example, typing "u2f ?" produces the following instructions: u2f version 1.1 (17Feb92), run: Fri Feb 21 13:07:04 1992 u2f: convert a UNIPOPS file from std input to a FITS binary table on std output. Usage: u2f -L|C|LC [-n max] [-t npts] [-v|-f] [-s s1 s2] -L -C -LC : select line, continuum, or both. -n max : maximum records per FITS table. -t npts : truncate scan to length npts. -s s1 s2 : scan number range. -v : 1st axis is veloc; -f for frequency. Further explanation of "-n" and "-t" is in order. The default is not to use either option. In the default case, the input data is converted to FITS form and written to a temporary disk file until the end of the input is reached. After this, the program knows how many scans are in the file, and the maximum scan length. The program can write this information in the FITS XTENSION header, and can truncate the scan length to the minimum necessary, before writing the output onto standard out. Finally, the temporary file is deleted. The "-n" option is a "real time" option in which the data is passed to the output file continuously as the input file is read. Each FITS XTENSION header will contain up to "max" scans. If the number of input scans is greater than "max", a new binary table will be started for each "max" scans. The last table may contain fewer than "max" scans, but the header will always indicate the number of scans = max. Since the program can't predict the maximum scan length, it pads all scans out to the maximum allowable size (2048 points) with Infinities, unless one gives the "-t" option, in which case all scans are made "npts" points in length. Typing "f2u ?" produces the following instructions: f2u version 1.1 (25Oct91), run: Fri Feb 21 13:10:39 1992 f2u : read a FITS file from std input. Usage: f2u -u|-sum|-head|-dump [n] -u | -U : convert to UNIPOPS format. -sum or -s : 1-line summary to stdout. -head or -h : list full headers on stdout. -c : #of scans in file to stdout. -dump or -d : list headers and 5 table rows, starting at n. 4. Format of SD-FITS --------------------- The format that "f2u" and "u2f" reads or writes respectively is based on the binary tables extensions to FITS. At a meeting in Green Bank in October 1989, representatives from many observatories from around the world with single-dish telescopes agreed upon a single-dish FITS format (SD-FITS) which we have implemented for UniPops. At present, the binary tables extension to FITS is in the process of being ratified by national and international committees. We know of one other observatory (IRAM) that has produced a SD-FITS reader and writer. A draft copy of a paper by Bill Cotton describing the binary tables extensions to FITS is available. We are in the process of writing a description of the UniPops implementation of SD-FITS. 5. Notes for installation of FITS programs f2u and u2f at UNIPOPS sites: -------------------------------------------------------------------- 1. in the file U2f_trans, find the line near the end of the file that contains: "Written at NRAO, Green Bank, W.Va." and change it to something appropriate for your site. 2. The file "U2f_trans" must be readable by anyone and should be installed in the directory: $popsdir/utiltiies Where $popsdir is an environmental variable containing the pathname for all the UNIPOPS utility programs.