******** Release 3.6 of FTOOLS ******************** This directory contains release 3.6 of the FTOOLS package. Major changes for the package include IRAF support for Solaris, the GUI fits viewer fv, and linux support (see the file LINUX.README). PACKAGE NOTES ------------- Release 3.6 of FTOOLs contains changes/additions in these packages: ASCA package: ============= ascaarf - * uses new XRT calibration files (xrt_ea_v2_0.fits, xrt_psf_v2_0.fits) and new "filter" modification. - * Also added the AUTO argument for all calibration files, for dual CALDB/refdata access. ascaeffmap - * uses new XRT calibration files and AUTO argument for all calibration files. ascalin - * now allows manual redetermination of GIS/SIS PI values. fastwmap - * bug fix of the FTOOLS v3.5 release version faintdfe - * Fixed SIGFPE crashes on Alphas. ghkcurve - bitrate parameters are now treated correctly - New algorithm that allows combined medium- and high-rate data and correctly accounts for bitrate changes and GTIs. ldeadtime - * carry out deadtime correction for GIS light curves sisrmg - * several user interface bugs have been fixed. - Patched to Geoff Crew's level 1.0f. Converted to native cfitsio. '*' Denotes changes that have already been included in the ASCA patch 3.5.1. ASCA patch 3.5.2 did not introduce significant new features, but fixed problems in the 3.5.1 release. CALTOOLS: ======== gcorpha - shifts the PHA channels as defined by user caldbflag - a maintenance task for CALDB managers. For a given calibration data set listed within a local Calibration Index File (CIF), the task enables 1 or more CIF flags to be switched to requested values. EXAMPLES: *** New Package! *** ======== Examples, serves two purposes: 1) to provide simple examples for new users/programmers of ftools to get acquainted with standard ftool programming practices, and 2) to provide templates for ftool developers to use as a convenience when developing new ftools. There are two ftools in this package. Each of them uses the Xanadu Parameter Interface (XPI) to read a string parameter, e.g. "Hello, World", from the environment, and print it to the standard output. ctooldummy - C ftool example/template ftooldummy - Fortran ftool example/template FITS FILE VIEWER: ================ fv the FITS file viewer is now available as part of the standard FTOOLS build. It is a Tcl/Tk based GUI browser for all types of FITS files. In addition to table and header listings in spreadsheet form, it allows plotting of columns and display of images. The Tcl/Tk that it uses are part of the FTOOLS build, so you do not need to have Tcl/Tk installed elsewhere on your system to use fv. Further functionality, including writing to the FITS file, is planned for future releases. Watch the FTOOLS web page for update releases of fv. FUTILS: ====== ! New task ! finterp - A general ftool for interpolating a column from one FITS table into another. The user may interpolate any scalar or fixed length vector column, using one scalar numerical column from each table as key values. Options include linear (1st order) interpolation, or 0th order interpolation, and several options for dealing with values which are out of bounds, or undefined. fdump - Fixed bug giving blank lines when printing bit arrays. ROSAT: ===== castpart - cast modelling of the PSPC particle background spectra in sky coordinates calcbgdcor - calculates the background spectra for a given source roscc2utc - converts the spacecraft time to UTC in yy:mm:dd:hr:mm:sec pcbgdcor - Perl script to spawn PCPARPHA, PCARF, PCEXPMAP, and CALCBGDCOR XSELECT: ======= Extractor now works correctly on Solaris machines. XSELECT itself now includes updated treatment of ASCA SIS Fast mode area discrimination, based on a correction received from ISAS. XRONOS: ====== - A new environment variable, $XRDEFAULTS, is now used to locate the plotting .pco and window files. Users can set this manually at any time to use a different set of defaults. It is recommended that the user re-run mkftools after installing FTOOLS V3.6, which will cause .ftools to set $XRDEFAULTS to the directory ftools/xronos/defaults, the standard directory for these files. - In the task lcmath, a new paramater (err_mode) allows the user to choose from four different methods to evaluate errors in the output file. - The perl script flc2ascii now includes in the ascii output file the GTI extension and/or the fractional exposure column, if either of these are present in the input FITS file. XTE: === The XTE FTOOLS have undergone substantial changes since the release of FTOOLS v3.5. Because of the rapid pace of development, coupled with our desire to provide the latest versions of the software to XTE Guest Observers, we previously released two upgrades to v3.5. The current full release of FTOOLS v3.6 includes further changes to the XTE package and thus *SUPERCEDES any previous FTOOLS distribution*. Note that we do expect to continue to release XTE upgrades between full FTOOLS releases. We briefly list here the new tools and major changes to existing tools since the last upgrade (ie, XTE v3.5.2, released 10 July 1996). For a complete log of changes since v3.5.0 and answers to other frequently asked questions we urge interested persons to check the XTE-FAQ at: http://heasarc.gsfc.nasa.gov/docs/xte/ftools/xtefaq.html Mike Tripicco / Brian Elza (for the XTE FTOOLS group) ****************NEW SCRIPTS in FTOOLS v3.6**************** +++RUNPCABACKEST+++ A Perl script which takes as input a file containing a list of files that PCABACKEST is to operate upon. The script will prompt you for all of the necessary input for PCABACKEST as well as a "suffix" that is to be appended to each output file created by PCABACKEST, e.g., if an input file is FS50 and the suffix specified is "out" then PCABACKEST would create FS50_out. A list of the names of the output files will be placed into another file which is ready to be input into SAEXTRCT for farther processing. The code will also prompt you, asking if you want to run SAEXTRCT. If a list of files is input from another directory, the code will separate the filename from the pathname and use the filename only (note this will only work on UNIX based systems, i.e., those using a '/' as a path delimiter). ****************CHANGES to XTE FTOOLS since v3.5.2**************** +++FXBARY+++ 1) A problem was found if the user input a series of orbit files that were not directly applicable to the data in the file being processed but fell within the TSTART+TIMEZERO and TSTOP+TIMEZERO of that file. This was most problematic when a user created a light-curve with SA(SE)EXTRCT with a large gap in it (longer than a day or two) but input into FXBARY an orbit file for the days that were not present in the output data. The code would read the next orbit file from the time-ordered list it produced from all input orbit files and assume that orbit data was to be applied to the data in the input file, and thus extrapolate from the information in the orbit file to the time in the input file. This led to many problems, one of which (fortunately) was the code aborting with an error message. This is no longer the case; additional checking is performed to ensure this does not happen. In general, the user should only input orbit files that cover the data in the file if this is possible. However, the code will now deal with this problem correctly. ----- +++PCABACKEST+++ - Supports interpolation of binned models to improve background estimate. - Supports individual PCU's being turned off. - Error estimate calculation is optional. (Speed improvement if omitted) - Executes on DEC Alpha systems. - Allows separate estimation of internal and diffuse x-ray background. - Can search calibration database (caldb) for background models. ----- +++PCAGAINSET+++ This tool has been modified to work with a revised EDS gain/offset calibration file. The revised file now collects all of the gain/offset values for the mission into separate extensions of a single physical file instead of being in separate files. PCAGAINSET now reads this single file and determines the extension containing the EDS gain/offset values appropriate for the date of the observation. The current revised file, edsgcor_e04v00.fits, will be available in both the calibration subdirectory in the xte mission database and in caldb in /caldb/data/xte/pca/bcf/eds. Note that PCAGAINSET will work properly with the older files, but the user may get warning messages. ----- +++SA(SE)EXTRCT+++ 1) A problem that occurred for GTIANDFILES that contained only 1 row has been corrected, as well as now checking for the case where the user supplies a GTIANDFILE or TIMEINT file which contains NO DATA. Both of these cases would cause all of the data points in the files being processed to be filtered out. 2) Additional information is now written to the screen describing the GTI information that is supplied to the code. This modification was necessary as some GTI's were incorrect such that the code was using non-applicable time-ranges when filtering data. This can give rise to serious problems for SEEXTRCT (see below). Also, the TSTART+TIMEZERO and TSTOP+TIMEZERO specified in the GTI's are now rigidly enforced - these keywords should accurately describe the information in the extension, in the past users this was not the case and caused serious problems for the extractors under certain conditions. Caution: DO NOT change the TSTART or TSTOP KEYWORDS unless you know which keywords are necessary for the extractors to function. ----- +++SAEXTRCT+++ 1) The parameter "columns" now accepts as input either "ERROR" or "BACKEST" such that it will now find those columns with Errs in their name, and the "GOOD" option will automatically filter these columns out. Note that it is NOT possible to select both GOOD and ERROR in the same run. Due to the limit of 40 columns on processable data - this will NOT change in future versions. The user is instructed to run SAEXTRCT twice in this instance, otherwise many other problems can occur. ----- +++SEEXTRCT+++ 1) If "no data" is selected the code will exit properly now. 2) The timing algorithm has been reworked such that on-time is now calculated by calculating the amount of valid time that is between the TSTART+TIMEZERO and TSTOP+TIMEZERO minus all of the filtered out time-regions. As a result of this the code is MUCH more sensitive to errors in the GTI's that are input. To compensate for this sensitivity the code performs many more checks on the GTI's to attempt to ensure that they were created in a valid manner. It is still possible to confuse the code if the user modifies such parameters as TSTART and TSTOP in the GTI file, removes them, or creates them in an unsanctioned manner, i.e., a way not listed in the ABC guide for data analysis. The code assumes that all input GTI's are valid, so it is up to the user to ensure that any forced modifications performed to the GTI's result in valid XTE GTI files. As long as the information input is valid and conforms to the XTE specifications, no problems should be encountered. ----- +++XTEFILT (FCOLLECT/XTEDERIVE)+++ 1) Added a new derived quantity to the filter file, "OFFSET", which is the angle between the target coordinates and computed pointing. 2) Any I-type columns in the original HK files are written as E-type in the filter file so that FMERGE will correctly process them.