RELEASE NOTES FOR FTOOLS V4.2 November 20, 1998 ===== SUMMARY ===== This document contains information about the FTOOLS package, version 4.2, with emphasis on changes to the package since the last release, FTOOLS version 4.1. For online information, please see our website at: http://heasarc.gsfc.nasa.gov/docs/software/ftools/ftools_menu.html For correspondence regarding the subpackage XRONOS ONLY, please send email to email@example.com. PLEASE DIRECT ALL OTHER CORRESPONDENCE TO: firstname.lastname@example.org. For online information on the HEASARC, including other software packages such as XANADU, please see: http://heasarc.gsfc.nasa.gov/ ===== SUPPORT FOR WINDOWS ===== By far the most significant new development in FTOOLS V4.2 is the addition of support for the MS Windows NT/95/98 operating system family. This was accomplished by layering the FTOOLS on top of the Cygwin tools, a UNIX-like API for Windows. For more information on the Cygwin Project, see their web site: http://sourceware.cygnus.com/cygwin The Windows version of the FTOOLS is available in binary form only; it was built from source at the HEASARC using the versions of the GNU development tools which are bundled with the Cygwin tools. The source code is identical to the UNIX version, and may be separately obtained for reference, but installation from source code is not supported. For information on installing the Windows version of FTOOLS 4.2, please see the file INSTALL.WINDOWS. ===== YEAR 2000 (Y2K) COMPLIANCE ===== With release 4.2, we believe that the FTOOLS are ready for 2000. In particular, we have transitioned them to the new format for FITS dates, YYYY-MM-DD. All programs and library routines should now understand both this and the old DD/MM/YY format (which in accordance with the FITS standard will be interpretted as 19YY, usually), but in general they will write only new-format dates. Our intention is that old data files should be usable without conversion; please let us know if you run into trouble. Date/time keyword pairs (e.g., DATE-OBS/TIME-OBS, DATE-END/TIME-END) have *not* been combined into the full FITS date/time format ("yyyy-mm-ddThh:mm:ss.s"); they will remain as separate keywords for the date and the time. However, the file-creation DATE keywords and many HISTORY keywords *do* now use the combined format. Date keywords that are merely copied from an input file are not usually converted to the new format, so in some cases it is possible to have, for instance, DATE-OBS in the old format and DATE-END in the new one. A few FTOOLS will write old-format dates for 1900 <= year <= 1998, and new-format ones for other years; these include sf2pha, ascii2pha, eaddmap, fesdb2rdf, fbbft2pha, and fbdrm2rmf. ascalin will write HISTORY keywords with old-format dates until we can wean its author off CFITSIO version 1. FTOOLS for some old, long-inactive missions, such as Vela-5B, will continue to write old-format DATE-OBS and DATE-END strings (although new-format file-creation dates). This is so that users' seldom-used, non-FTOOL, analysis programs will not have to be changed. Since these missions ended long before 2000, we believe that there is no possibility of misinterpretation or an overflow. Where these FTOOLS take user-input dates, either format may be used. These changes required modifications in many source files throughout the FTOOLS. While we think we found them all, it is possible that we missed some. If you find any incompatibilities or stray old-format dates, please send the details to us at email@example.com, and we wish you an enjoyable Millenium. ===== SPECIFIC CHANGES ===== For each of the FTOOLS subpackages below are listed the tools which are new in v4.2 as well as brief descriptions of the major changes to preexisting tools. After the FTOOLS package is installed, more information on any FTOOL can be obtained by typing "fhelp
". Type "fhelp ftools" to obtain a full listing of all the tools available in v4.2, or "fhelp " to list all of the tools in a particular subpackage. ===== CFITSIO/FITSIO ===== This release of ftools uses the new CFITSIO 2.0 library which provides the following new features to all the ftools tasks: Any FITS file on the internet can be opened by giving the full ftp or http URL. Rows in FITS tables may be filtered/selected on the fly as they are read by CFITSIO using a user-supplied expression. The application program then only sees the selected rows. Columns in FITS tables may be created, modified, or deleted on the fly when the file is opened based on a user-supplied expression. Columns in a table may be binned/histogrammed on the fly as the file is opened. The application program then only sees the binned image and not the original table. IRAF format image files (.imh files) may be read, as well as FITS files. A FITS file may be opened more than once simultaneously by a program, and data may be read or written to two or more different extensions in the file at the same time. Numerical overflows when reading FITS keywords now result in a returned error status instead of being ignored. Type 'fhelp filenames' for more information about the extended filename syntax now supported by all the FTOOLS tasks. ===== FV ===== ===> New since v4.1 <=== - Internet support has been added. Files can be read via the http and ftp protocols. Ftp sites can be browsed with the "Open File" dialog box. - Filename completion has been added to the "Open File" dialog box. Type the initial characters of a file name and press TAB. Fv will look for a file starting with those characters. - Basic fv functions (open, display, and plot data) can be controlled with simple TCL scripts. - New, empty FITS files can be created. Empty extensions of any of the 3 types (image, ASCII Table, Binary Table) can be appended to existing files. - Checksum keywords can be created or updated when a file is modified. - Keyboard shortcuts (ctrl-c and ctrl-v) have been added for copying and pasteing data in the table display window. - When displaying an image in POW, double-clicking the image will cause fv to open the corresponding FITS extension as a table and highlight the clicked pixel. - POW can create contour maps of images. - More curve plotting options have been added to POW. Each curve can have its own line style/width, point shape/size, and color. - The Edit Graph dialog boxes have been modified to make them simpler, more intuitive, and more powerful. One can easily control the contents of a given graph, the plotting styles of its curves, and the axis parameters (label, bounds, etc) from a single window. - Graphs containing images can be rescaled to arbitrary sizes in both the X and Y directions. (No more snapping to integral magsteps.) - Removed restriction on the production of mosaics from images with different pixel sizes. ===== ASCA ===== (*) For complete details and up-to-date information on using FTOOLS v4.2 to analyze ASCA data, please refer to: http://heasarc.gsfc.nasa.gov/docs/asca/ahp_proc_analysis.html ===> New since v4.1 <=== gis2bitfix - Perl version of gis3bitfix.e tool, fixes science files affected by the GIS3 3 bit LSB error ===> Bug Fixes and Minor changes since v4.1 <=== addascaspec - Now works with previously added response files. ascaarf - Fixed bug in generating arfs for GIS at 64x64 resolution. Fixed bug that caused a crash if the GIS WMAP region was expanded to the whole detector (256 bins). ascaeffmap - Fixed bugs in generating efficiency maps for SIS. correctrdd - Fixed a bug in writing an output keyword, RDDCOR_V. mkfilter2 - If Euler angles can't be set from the attitude file, set them to `undefined' (-99.999) instead of user input angles. Get the orbital element epoch from the HK file header, not the filename. Warn if orbit file extrapolated more than 15 days. Fixed a bug in calculating the sun elevation that could give sqrt() domain errors. Spell header comments correctly. ===> Major changes since v4.1 <=== mkfilter2 * Extrapolate the attitude file up to the time given by new parameter `attmargin' (default 32 seconds) * New parameter `redosatf' (default yes) gives user option to not recalculate the SIS saturation flags (previously always were) * Output .mkf file START column now 23 characters wide and contains a FITS-standard new-format date/time string. MJD-OBS and checksum keywords are written. ===== CALTOOLS ===== ===> No changes since v4.1 <=== ===== EINSTEIN ===== ===> No changes since v4.1 <=== ===== EXAMPLES ===== ===> No changes since v4.1 <=== ===== EXOSAT ===== These are new tools to analyze the EXOSAT CMA data reformatted in FITS format. These tools work on the EXOSAT CMA FITS files as available in the HEASARC archive. Further information about the EXOSAT mission, archive and software will be available in the near future from http:://legacy.gsfc.nasa.gov/docs/heasarc/missions.html ===> New since v4.1 <=== automerge -- Create a list of compatible event files for a given observation, and output a merged event file by running exomerge. cmadead -- Correct EXOSAT CMA lightcurves and images for deadtime. exoleuv -- Estimate the stellar UV count rate for different CMA filters exomerge -- Merge files from a given observation. The output can be used in xselect. exopha -- Create one channel spectrum for the EXOSAT CMA exovig -- Give the vignetting correction factor for the EXOSAT LE tkexomerge -- Create a list of event files via tk interface & run exomerge ===== FIMAGE ===== ===> Major changes since v4.1 <=== f2dhisto * Rewritten in C to support new command-line filtering and improve speed 2-3 times * cpprim and cphead parameters no longer supported ===== FUTILS ===== ===> New since v4.1 <=== cphead -- Copy keywords from an HDU of an input file to an HDU of an output file. fcollen -- Modify the vector length of a column in a binary table extension of a fits file. fcopy -- Copy the contents of a FITS file to a new file (for use with new command-line filtering). fdiff -- Display differences between pairs of fits file. xfverify -- Verify that a FITS file conforms to the FITS Standard. (This is a faster, more capable replacement for fverify.) ===> Major changes since v4.1 <=== fcalc * New arithmetic parser implemented, speeding operations by 10-40 times * File-based filters for SAO regions and GTI extensions added (see help file for details) * Expression can evaluate to BIT or STRING values fhisto * Rewritten in C to support new command-line filtering and improve speed 2-3 times * cpprim and cphead parameters no longer supported fselect * New arithmetic parser implemented, speeding operations by 10-40 times * File-based filters for SAO regions and GTI extensions added (see help file for details) * % done progess report eliminated (due to speedup and problems with FITS file piping) ===> Bug Fixes and Minor changes since v4.1 <=== fdump -- Unsigned integer columns with huge values handled properly ffilecat -- Output filename column retains extension number and any command-line filtering commands. fmemsort -- Bug Fix: Heap sort on table with 1 row no longer crashes fmerge -- Bug Fix: Column data types D and 1D now considered equal fsort -- Bug Fix: Null values recognized ===== GRO ===== ===> New since v4.1 <=== bcmppha -- This ftool reads a standard OGIP PHA-II (multiple spectra) file as its input, and writes a PHA-I file (single spectrum) as its output. The output spectrum is an average over a user-specfied set of rows spectra) from the input file. The purpose is to construct source and background spectral data files for analysis of CGRO BATSE gamma-ray burst observations. emapgen -- This ftool constructs counts maps from an EGRET photon list (qvp fits file). The user can select energy ranges, bin sizes, time intervals and several other parameters. This program is directly based on the EGRET science team program MAPGEN. ===== HEASARC ===== ===> New since v4.1 <=== gtisum -- This tool is designed to report on the total amount of good time in any or all of the GTI extensions in a valid FITS file. Valid GTI extensions are designated by the presence of a HDUCLAS1 keyword containing the string "GTI". ===> Major changes since v4.1 <=== extractor - Fixed detector images so that CTYPE do not imply RA & Dec and comments do not mention degrees. Added support for regions in WCS coordinates (as written by eg SAOtng). Changed the way the WMAP is handled in the case when the region filter is not in detector coordinates - now no longer has the problem that pixels with no events are flagged as outside the selected region. Added Y2K compatibility. Fixed bug that always zeroed out the first channel of the output spectrum. Fixed bug in WMAP when WMAP binning differs from image binning. If a GTI filter file only has one table then assume that it is the correct one whatever the EXTNAME value. Sped up GTI filtering. Fixed bug causing WMAP CDELT to be set incorrectly to the image CDELT. ===== OSO8 ===== These are new tools which allow to extract lightcurves for the B and C detectors on the OSO8 Goddard Cosmic X-ray Spectrometer Experiment. These tools work on the OSO8 rate data files in fits format as available in the HEASARC archive. Further information about the OSO8 mission, archive and software will be available in the near future from: http:://legacy.gsfc.nasa.gov/docs/heasarc/missions.html ===> New since v4.1 <=== osofindfast -- Give a file list of the OSO8 raw rate files for a given sky position. osorat -- extract a lightcurve from the OSO8 GCXSE B or C detectors for a given sky position. ===== ROSAT ===== ===> No changes since v4.1 <=== ===== TIME ===== ===> Major changes since v4.1 <=== maketime * New arithmetic parser implemented, speeding operations by 10-40 times * File-based filters for SAO regions and GTI extensions added (see help file for details) * (Bug) Lines longer than 80 characters in expression file (@expr) will not get truncated in the HISTORY keywords. ===> Bug Fixes and Minor changes since v4.1 <=== fltime -- Bug Fix: TSTOP keyword properly set to last GTI STOP and TELAPSE keyword calculated properly mgtime -- User warned about empty GTIs which are ignored ===== VELA5B ===== ===> No changes since v4.1 <=== ===== XRONOS ===== ===> No Major changes since v4.1 <=== ===> Bug Fixes and Minor changes since v4.1 <=== rbf2fits -- Y2k update earth2sun -- leap seconds update - Add half bin integration time to TSTART and TSTOP keywords in the lcurve output. ===== XSELECT ===== The latest version of the Xselect user's guide is available online at: http://heasarc.gsfc.nasa.gov/ftools/xselect/xselect.html Added support for XTE PCA Standard2 data. Main change is to add detector option to the filter command to allow the user to select PCUs, layers, and anode sides. Added preliminary support for XMM EPIC. No longer require an @ in front of the filename of a list of files for the read command. ===== XTE ===== For complete details and up-to-date information on using FTOOLS v4.2 to analyze RXTE data, please refer to: http://heasarc.gsfc.nasa.gov/docs/xte/xhp_proc_analysis.html ===> New since v4.1 <=== closereturn --- Uses the method of close returns to aid the user in detecting unstable periodic orbits embedded in the evolution of a time series. Uses light curves as input and displays the result as a two dimensional image, as well as stores the image in an output file. decodeevt -- Decodes event keywords in XTE Science Event files and generates an output file with separate columns for TIME, CHANNEL, PCUID, ANODE, and PROPANE. dyenspec -- Generates dynamic energy spectrum for each row of the input XTE Science Array data (mode 2), and then displays this two dimensional image on the screen as well as stores the image in an output file. Users can look at the spectrum for each row by clicking on the image. ===> Major changes since v4.1 <=== fasebin: fbadd: fbfsum: fbssum: fbsub: Fixed bug that caused wrong channel-binning for some Event modes; now can use JPL DE405 ephemeris though default is still DE200; Linux-specific bugs fixed. fcollect/xtederive/xtefilt: Can collect scalar quantities from PCA science files and cycle over multiple files. Calculates the additional quantities TIME_SINCE_SAA and ELECTRON[0-4] when the new appidlist is used (ck. "xtefilt -h") (THESE CHANGES WERE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998) TSTART/TSTOP now always correspond to first and last values in "Time" column. TIMEPIXR keyword now present in filter files. Now handles mixed production and realtime data in the same directory. hxtlcurv: This tool has been disabled in FTOOLS v4.2 due to incompatibilities with the current version of hxtdead. A revised version will be released as part of an update to FTOOLS v4.2 in the near future. Please check our web site for up-to-date information on the release schedule for software updates. pcabackest/runpcabackest: Uses an additional parameter, "saafile". (CHANGE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998) CALDB removed as default for model files parameter (see http://rxte.gsfc.nasa.gov/docs/xte/whatsnew/software.html for model file instructions); "syserr" parameter is now hidden and not recommended; correction applied for slow gain drift; fixed bugs on DEC Alphas; interpolation to 256 channels improved; documents which saa_history file used. pcarsp: Added options to specify alternate RA/DEC, in case of off-source pointings. rddescr: Bug fixed which caused the tool to produce error messages and generate an incorrect output ascii channel file whenever the CPIXn keyword was longer than one line in the FITS header of the input .pha file. (CHANGE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998) sbmerge: Major revisions related to making output acceptable to SAEXTRCT (1DELT2, 1CTYP2, TDDES2, ModeSpecific); XeCnt counts handled differently. ===> Bug Fixes and Minor changes since v4.1 <=== Fixed pervasive bug performing formatted writes without specifying field width; this only affected FTOOLS compiled from source distribution by users with the most recent versions of g77 (ie, Linux only). In the XTE subpackage this applied to hxtarf, xpcaarf, pcaclrsp, and xtecol only. addshots: Removed case-sensitivity in input parameters. correctlc: Made more robust; documentation improved. fxbary: Bug fixed which caused crashes on some systems. (CHANGE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998) mkgtif: Bug fixed which caused crashes on some systems. (CHANGE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998) pcaclrsp: xtecol: Time format increased to allow Time .ge. 1e08; bug fixed in handling null values while accumulating avg and std dev; fixed bug related to CALDB access pcadtlc: IRIX-specific bug fixed; TUNIT2 keyword added to output file. pcarmf: Bug in retrieving energy-to-channel info from CALDB fixed. sa2phaII: Change in handling of 1CPIX keyword; changed EXPOSURE computation. trans2fits: Bug fixed in Check_and_Write_Info subroutine which caused crashes in some circumstances.