The FaseBinner Family of Tools
------------------------------

Arnold Rots
28 March 1997
Updated 20 March 2001

1. Purpose
----------

The FaseBinner tools provide the capability to bin observations
of a periodic signal into a two-dimensional histogram of phase versus
energy with sufficient accuracy to allow absolute timing down to a
level of 10 us, as well as some basic analysis of such histograms.

The output files can be used in Xspec.


2. Input Data
-------------

The following data can be processed, mostly from the raw XTE files.

PCA:
  Single EA event mode
  GoodXenon, after processing by xenon2fits
  Binned mode
  Single-bit mode
  Pulsar-fold mode

HEXTE:
  Event mode
  Binned mode (either histogram or multi-scalar)

Note that the FaseBinner will automatically take out time marker
pseudo-events, will mask out HEXTE off-source data, and will allow
selection of layer 1 only for GoodXenon data.  Shortly, it will
support handling of GoodXenon propane data.  Also, all clock
corrections and barycenter corrections are applied in the process.


3. Tools
--------

3.1. faseBin

This is _the_ phase binner.  Barycenter corrections and clock
corrections are applied automatically if and when needed.

Input parameters:

inFile:   An input data file, or the name of a file containing a list
          of input data files; supported data modes are listed in
          section 2.  Note that the GTI extensions are not applied.

outFile:  Output file name; if no extension is given ".pha" will be
          appended (default: faseBin.pha).

orbitFile: Name of the applicable orbit ephemeris file; note that only
          one file can be provided; these files cover 34 hours,
          starting at midnight UTC.

source:   B or J name of the object; this is intended for finding it
          in the radio pulsar database.

gtiFile:  GTI file to be used (default: none).

respFile: Name of response matrix file to be put into the header
          (default: none).

nphase:   Number of phase bins (default: 100).

radioOffset: Offset (in s) to be applied to radio data; this is the
          dispersion measure correction for the Crab and Vela pulsars
          (default: 0.0).

binary:   Binary pulsar? (default: no).

layer1:   Use only layer 1 for GoodXenon data? (default: yes).

propane:  Use only propane data for GoodXenon data? (default: no).
          This is either propane or xenon, not both.

Note that faseBin requires multiple files to be commensurate in their
data formats as far as pha channel binning is concerned, since this
binning is not touched.  I.e., the pha channel "CPIX" keywords have to
be identical.  The fB file that is created spans phases from 0.0 to
2.0. 


3.2. fBsub

Subtracts a baseline (unpulsed contribution) from the histogram.
Since the baseline and the errors are kept in the fB file, there is no
harm in running this tool on its own output.

Input parameters:

inFile:   Input file name; this needs to be an fB file.

outFile:  Output file name; if no extension is given ".pha" will be
          appended (default: fBsub.pha).

phaseRange: Range of phases (phaseMin phaseMax) to be used to
          determine the unpulsed contribution.  phaseMax should be
          greater than phaseMin and may exceed 1.0.


3.3. fBadd

Adds several fB files together, provided they are commensurate.  This
tool is useful for combining data from different days which cannot be
combined in any other way since they require different orbit ephemeris
files.

Input parameters:

inFile:   Input file name or the name of a file containing a list of
          input file names; these need to be fB files.

outFile:  Output file name; if no extension is given ".pha" will be
          appended (default: fBsub.pha).


3.4. fBfsum

Allows averaging of fB files in phase, by summing rows together.

Input parameters:

inFile:   Input file name; this needs to be an fB file.

outFile:  Output file name; if no extension is given ".pha" will be
          appended (default: fBsub.pha).

phaseBins: step, start, stop (in bins); step is the number of phase
          bins (rows) to be averaged into the new bin (default: 5);
          start is the first row to include (default: first row in
          file); stop is the last row to include (default: last row in
          file).


3.5. fBssum

Allows averaging of fB files in energy and performs some phase
analysis.  Out put is to the terminal.

inFile:   Input file name; this needs to be an fB file.

chanBins: A list of start channels for energy ranges, plus the final
          end channel; if none are given, the entire energy range is
          summed together; if only one number is given, that is taken
          as the start of a single range that is to end at the highest
          channel number; otherwise, ranges will be contiguous.

phaseParms: Start and stop phase for peak analysis, and threshold in
          terms of fraction of the peak (default: 0.25); if not
          provided, this analysis will not be carried out.

hRatio:   Calculate hardness rations? (default: no); if yes, the log
          of the ratios of the rates in adjacent energy ranges (as
          specified by chanBins, if more than one) are tabulated.

This tools provides, for each of the specified energy ranges:
  In the specified phase range (if specified):
    The zeroth through third moments of the peaks, based on points
      exceeding the threshold
    The peak bin
    A second order fit to the peak
  The baseline (unpulsed) count rate
For each phase bin:
  The phase
  The MJD day
  The exposure
  For each specified energy range:
    The count rate
    The error in the count rate
    The logarithm of hardness ratio with the next energy range

Note that energy channels should be given in bin numbers, not in the
original instrument's pha channel numbers.


4. Output Data
--------------

The output format of all tools, except fBssum, is the fB extension of
the type II pha FITS format which can be read by Xspec.

Such a FITS file will consist of an empty primary extension and one
binary table extension which contains the data.

The binary table's header shall contain the following keywords.

    EXTNAME = 'SPECTRUM'
    TELESCOP= ''
    INSTRUME= ''
    FILTER  = 'none'
    OBJECT  = ''
    AREASCAL= 1.0
    BACKFILE= 'none'
    BACKSCAL= 1.0
    CORRFILE= 'none'
    CORRSCAL= 0.0
    RESPFILE= 'none'
    ANCRFILE= 'none'
    RA-OBJ  = 0.0            / \  Used
    DEC-OBJ = 0.0            /  | for
    EQUINOX = 2000.0         /  | barycentric
    RADECSYS= 'ICRS'         / /  corrections
    PLEPHEM = 'DE405'        / Solar system ephem used for barycenter
    TIMESYS = 'TDB'          / \ Barycentric
    TIMEREF = 'SOLARSYSTEM   / / corrections applied
    TIMEUNIT= 'd'            / Unit of TSTART/TSTOP is days
    MJDREF  = 0.0            / Start and stop time are directly in MJD
    TSTART  = 50085.0        / Start time in MJD
    TSTOP   = 50085.5        / Stop time in MJD
    DATE    = ''
    DATE-OBS= ''
    CREATOR = 'xxxxxx Version y.y'
    HDUCLASS= 'OGIP'
    HDUCLAS1= 'SPECTRUM'
    HDUVERS1= '1.1.0'
    HDUCLAS2= 'ACCEPTED'
    HDUCLAS3= 'TYPEII'
    HDUCLAS4= 'COUNT'
    HDUCLAS5= 'fB'
    POISSERR= 0
    CHANTYPE= 'PHA'
    DETCHANS= 256
    PHASEDEL= 0.01            / Phase bin size
    CPIX4   = ''              / XTE-specific
    GAINAPP = T               / XTE-specific

The binary table it self will contain one row with a single spectrum
for each phase bin present, with the following columns.

    SPEC_NUM     long          spectrum number
    PHASE        double        phase value for the row
    CHANNEL      long[nch]     array of channel numbers
                               (usually 0:nch-1)
    COUNTS       double[nch]   spectrum counts
    STAT_ERR     double[nch]   error in data; usually:
                               Error[i] = sqrt (Data[i] + Background[i])
    BASELINE     double[nch]   baseline (background) level for each channel;
                               this vector will not change between rows
    EXPOSURE     double        exposure time for phase bin
    ROWID        char[20]      "Phase <Spec_Num>*<PHASEDEL>"
    HRATIO       double[nch-1] hardness ratios (optional)

Phase values are modulo 1.  The range of values may exceed the bounds
0.0-1.0, provided that all rows with identical mod(PHASE,1.0) only
differ in their Phase value.  Note that only counts, not rates, are
permitted.  The COUNTS column shall have a proper CPIX keyword.

Note that phases refer to the center of the phase bins (as opposed to
the time stamps in XTE files which refer to the start of the bins).


5. System Files
---------------

All system data files are kept in the LHEA_DATA directory.  They can
be replaced by either making this environment variable point to a
different directory (to be discouraged) or by replacing some or all of
the files in a directory that the environment variable TIMING_DIR
points to.  The logic is that the code, for each of the system files,
will first test whether $TIMING_DIR is defined; if so, it will check
whether the file exists in that directory.  If this search fails to
deliver the desired file, it will be taken from the $LHEA_DATA
directory.


5.1. JPLEPH

This file contains a FITS version of the JPL DE-200 ephemeris.  It
will be upgraded as appropriate to the next JPL ephemeris.


5.2. psrtime.dat

This ASCII file contains the radio pulsar database as maintained at
Princeton.  Users may modify a copy of it for their own use, if so
desired, and place this in their $TIMING_DIR directory.  This may
especially come about when users have a recent timing ephemeris that
is not yet included in the $LHEA_DATA copy, when users down-load a
newer version of psrtime.dat, or when the object of interest is not
included in the radio pulsar database.

The format of the file is more or less self-explanatory, but is
further detailed at the Princeton ftp site.


5.3. psrbin.dat

This ASCII file contains the orbit ephemerides for binary pulsars from
the radio pulsar database.  The same comments as in 5.2 apply here.


5.4. tdc.data

This ASCII file contains the XTE clock correction parameters.  Updates
may be obtained from the XTE ftp site.
