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 xanprob@athena.gsfc.nasa.gov. PLEASE DIRECT ALL OTHER
CORRESPONDENCE TO:
ftoolshelp@athena.gsfc.nasa.gov.
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
ftoolshelp@athena.gsfc.nasa.gov, 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:://heasarc.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:://heasarc.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://heasarc.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.