ASCATAPE (OCT94) ftools.asca ASCATAPE (OCT94) NAME ascatape -- Read FITS files from NASA/GSFC/ADF supplied ASCA data distribution tapes. USAGE ascatape load_tape load_dir check_size make_dirs load_all load_min, load_raw load_merged load_clean load_aux load_prod load_optional DESCRIPTION ascatape examines the contents of ASCA data distribution tapes and then reads those files selected by the user. The tape format must conform to the NASA/GSFC Astrophysics Data Facility (ADF) standard. This standard mandates that the first tape file contain a FITS file with a single ASCII table extension describing the contents of the rest of the tape. If the tape was not made by the ADF, or does not conform to this standard, then ascatape cannot read the tape. Users may choose to unload the entire contents of the tape (which usually takes up a lot of disk space) or certain classes of files. The following file classes are supported: Minimum science data set absolute minimum file set necessary to perform ASCA data analysis. This includes all the raw science files (ft*.fits), Mkfilter files (*.mkf) and associated Xselect catalog files (*frf.cat). Raw event data files all files and file catalogs containing raw, unprocessed events along with their catalogs (ft*.fits, *raw.cat and *frf.cat). Unscreened event data files event files that have not been filtered of unwanted events along with the associated catalog files (*.unf and *unf.cat). Screened event data files event files that have been screened of unwanted events along with the associated catalog files (*.evt and *evt.cat). Necessary auxiliary data files auxiliary files needed for data analysis and/or further data processing (*.ghf, *.orbit and *.mkf). Necessary science product data set products derived from the event files (*.img, *.detimg, *.pxl and *.gif). Optional data files files not necessary for data analysis. This includes the housekeeping, FITS wrapped, calibration, attitude and processing related data files (*HK.*, *.wrap, fa*, etc...). In addition to unloading files by class, ascatape allows users to place the unloaded files in a set of ASCA GOF recommended subdirectories. Using this subdirectory structure makes for a more organized and understandable loading of the tape contents. If this option is chosen (make_dirs=yes) then ascatape creates the subdirectories 'raw', 'unscreened', 'screened', 'aux', 'telem', 'product' and 'work' under the specified load directory. All files concerning the raw events will be placed in the 'raw' subdirectory, all files concerning the unscreened events wil be placed in the 'unscreened' directory, all files concerning the screened events will be placed in the 'screened' directory, all files deemed as auxiliary will be placed in the 'aux' directory, all original telemetry data files will be placed in the 'tleme' directory and all processing product related data files will be placed in the 'product directory (forgive the run-on sentence). The 'work' directory is the intended (although not required) area where the user will perform his/her analysis. The user may construct these directories ahead of time and ascatape will make use of the existing directories instead of trying to create them. Thus, by creating the directories beforehand, symbolic links may be used to spread the loaded data over several file systems (Unix only). As a final option, ascatape allows users to find out how much disk space will be necessary to unload a given configuration of files before the files are unloaded. Since a full ASCA data tape can contain many hundreds of megabytes of files, this option (check_size=yes) is often useful for users who have limited disk space. When the check_size option is invoked ascatape will report back the number of kilobytes necessary to unload the selected file sets instead of actually unloading the selected file sets. If the reported disk requirements are satisfactory then the user may rerun ascatape with the check_size option turned off to load the files. PARAMETERS The following are the ascatape "mandatory" parameters that require answers each time the utility is run. If you do not specify them on the command line then you will be prompted for them. In case you are unsure of what files are necessary to load from tape, choosing the default values will load all the files necessary for data analysis. tape_drive [string] Name of the tape drive to read from. Note that on Unix systems the "no rewind" tape device driver must be specified. load_dir [string] [no default] Absolute directory path of the area used to load the tape files. check_size [boolean] [default = no] Set to "yes" to check the disk space requirements of the selected file sets before unloading from tape make_dirs [boolean] [default = yes] Set to "yes" to create and use the recommended default subdirectory structure under the specified load_dir load_all [boolean] [default = no] Set to "yes" to load all files from the tape (uses a lot of space). load_min [boolean] [default = no] Set to "yes" to load the minimum science data set (all ft*.fits and *.mkf files) from tape. load_raw [boolean] [default = yes] Set to "yes" to load all raw (frfread produced) event files and associated catalog files. load_unscreened [boolean] [default = no] Set to "yes" to load all unscreened event files and associated catalog files. load_screened [boolean] [default = no] Set to "yes" to load all screened event files and associated catalog files. load_aux [boolean] [default = yes] Set to "yes" to load all necessary auxiliary data files from tape. load_prod [boolean] [default = yes] Set to "yes" to load all necessary processing product data files from tape. load_optional [boolean] [default = no] Set to "yes" to be shown a further list of possible (optional) data products that may be loaded from tape In addition to the above parameters, many other "hidden" parameters exist within the ascatape utility that allow the user to load specific data file sets. To make use of these parameters you must enter them as command line arguments. load_sci [boolean] [default = no] Set to "yes" to load the minimum science data files (all ft*.fits) from tape. load_filters [boolean] [default = no] Set to "yes" to load Mkfilter files. load_hc [boolean] [default = no] Set to "yes" to load all housekeeping files. load_wrapped [boolean] [default = no] Set to "yes" to load all FITS wrapped scientific product text files. load_calib [boolean] [default = no] Set to "yes" to load all calibration files. load_att [boolean] [default = no] Set to "yes" to load all attitude files. load_proc_rel [boolean] [default = no] Set to "yes" to load all optional processing related log and list files. load_tel [boolean] [default = no] Set to "yes" to load all telemetry files. load_imkf [boolean] [default = no] Set to "yes" to load the enhanced Mkfilter file(s). load_sis0 [boolean] [default = no] Set to "yes" to load all SIS0 instrument data files. load_sis1 [boolean] [default = no] Set to "yes" to load all SIS1 data files. load_gis2 [boolean] [default = no] Set to "yes" to load all GIS2 instrument data files. load_gis3 [boolean] [default = no] Set to "yes" to load all GIS3 data files. verbose [boolean] [default = no] Set to "yes" to get runtime status information. unwrap [boolean] [default = yes] Set to "yes" to unwrap FITS wrapped data files as they are unloaded. EXAMPLES This first example shows the simplest use of the ascatape Utility. Just by typing its name ascatape will prompt the user for all necessary information. And, by accepting all the default parameter values, the user will load from tape all files necessary for data analysis: ascatape The following example loads the absolute minimum set of files from the tape necessary to analyze ASCA data: ascatape load_min=yes This next example reports back to the user the amount of disk space needed to load the SIS0, GIS3 and MKfilter files: ascatape load_sis0=yes load_gis3=yes load_filter=yes check_size=yes If the returned space requirements were satisfactory then the same command minus the "check_size=yes" would actually load the requested file sets. This final example shows how to load the science product files, not use the default subdirectories and have ascatape report what it is doing ascatape load_sci=yes verbose=yes make_dirs=no In all the examples above ascatape would prompt the user for the tape drive name, load directory name and all other mandatory parameter values; thus, it is not necessary to specify these values on the command line. BUGS This routine has been tested under Ultrix, SUN OS, and Solaris operating systems. While it should work under other OS, there is no guarantee. The weakest link in any computer system are the tape drives. Therefore, if your tape does not read correctly please make sure that the drive it is being read upon is in proper working order. Try cleaning the drive in the appropriate manner or re-reading the tape on a similar drive before giving up. 8mm tape drive systems usually require 30 seconds or more to load tapes. Therefore, when using 8mm drives please wait an appropriate amount of time between loading the tape and executing the ascatape task. Otherwise, a tape read error might result. Ascatape divides the tape files into classes by parsing the file name. If the ASCA file naming convention changes, then ascatape will not work properly. SEE ALSO