******** 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.