.help fasebin Mar97 ftools.xte
.ih
NAME
fasebin -- The Phase Binner
.ih
USAGE
.nf
fasebin orbitfile sourcename datafile outfile gtifile respfile roff
        nph binary l1only propane debug clobber
.fi
.ih
DESCRIPTION
The FaseBinner tools provide the capability to bin RXTE 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.
.nf

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

Note that fasebin automatically removes time marker pseudo-events,
masks out HEXTE off-source data, allows selection of layer 1 only
for GoodXenon data, and handles GoodXenon propane data (when present).
Also, all clock corrections and barycenter corrections are applied in
the process.  It is a single tool that is capable of converting raw
XTE data files directly into analysis results without much user
intervention.

Note that fasebin requires multiple files to be commensurate in their
data formats as far as energy channel binning is concerned, since this
binning is not touched.  I.e., the pha channel "CPIX" keywords have to
be identical.  The user, therefore, has no control over the energy
channel binning: it is set by the input file(s).

The phase binning is performed by calculating the absolute phase of
each event or time bin from the input data file(s) and depositing the
event(s) in the appropriate phase/channel output bin.  The user can set the
number of desired phase bins per period.  Absolute phase is calculated
by referencing the time of arrival to the timing ephemeris provided in
the radio pulsar database.  The barycenter corrections are based on
the JPL DE-200 solar system ephemeris.  Where possible, all known XTE
clock corrections are applied, yielding a timing accuracy of 10 micro
seconds (subject to the accuracy of the instrument data configuration
used and of the radio database entry, of course).

The reliance on the radio pulsar database (see below under System Files)
implies that fasebin only works for pulsars that are included in
that database.  However, it is possible for the user to insert his/her
own entries in a private copy of that database, thus allowing the
binning of pulsars without a radio counterpart.  One should keep in
mind, though, that the absolute timing is only as good as the database
entries.  Since "absolute" is defined as "relative to the
radio pulse", this concept is ill determined for non-radio pulsars.

The results are written to a PHA-Type-II FITS file, subtype fB, which
can be processed by the other tools in the phase binner family and by
Xspec.  The files contain error estimates for each count rate value
and exposures for each phase bin, both of which are rigorously
propagated through the tools, .  The fB files created by fasebin span
a phase range from 0.0 to 2.0.

It is important to note that the phase values attached to each phase
bin refer to the center of the bin, and that exposure times represent
the true exposure time for each individual phase bin; i.e., the sum
of the exposures over phases 0.0 through 1.0 yields the total
observing time.  Consequently, the count rates reported for phase
bins are the rates one would observe if one were to follow those bins
all the way around the pulsar.  However, dead time corrections are
not applied.  Fasebin allows for a single GTI table file to be applied
to all input data files, but it does not apply the GTI tables
contained in the data files.  On the whole, this is not a severe
restriction, though.  If one creates a good GTI table based on the
filter file, one will have caught most of the information contained
in the piggy-back GTI tables.  In addition, analysis of pulsed
signals is largely insensitive to the imperfections that GTI tables
aim to screen out.

Fasebin allows the user to specify more than one input data file, but
only one orbit ephemeris file.  As a result, the files produced by
fasebin cannot cover much more than one day.  If one wants to combine
data from different days, one should use fbadd to do so.  Unpulsed
radiation can be subtracted using fbsub.  fbfsum allows the user to
add phase bins together without having to run fasebin again.  And
fbssum performs energy channel rebinning and phase analysis, but only
prints its results out in ASCII.  The fB files contain sufficient
information in their headers to allow makepcarsp to construct an
appropriate response matrix.
.fi
.ih
PARAMETERS
.ls orbitfile [string]
Name of the applicable orbit ephemeris file; note that only one
file can be provided; these files cover 34 hours, starting at midnight UTC.
.le
.ls sourcename [string]
B or J name of the object; this is intended for finding it in the 
radio pulsar database.
.le
.ls datafile [string] 
An input data file, or the name of a file containing
a list of input data files (i.e., @filelist).
.le
.ls outfile = faseBin.pha [string]
Output file name; if no extension is given ".pha" will be appended.
.le
.ls gtifile = none [string]
GTI file to be used.
.le
.ls nph = 100 [integer]
Number of phase bins.
.le
.ls (l1only = yes) [boolean]
Use only layer 1 for GoodXenon data?
.le
.ls (respfile = none) [string]
Name of response matrix file to be put into the header.
.le
.ls (roff = 0.0) [double]
Offset (in sec) to be applied to radio data; this is
the dispersion measure correction for the Crab and Vela pulsars.
.le
.ls (binary = no) [boolean]
If the source is a binary pulsar, set this to 
"yes" to search the binary orbit table.
.le
.ls (propane = no) [boolean]
Use only propane data for GoodXenon data?
(Setting this to "yes" overrides the l1only parameter.)
.le
.ls (debug = no) [boolean]
Turn on debugging output.
.le
.ls (clobber = yes) [boolean]
Should a pre-existing output file be overwritten?
.le
.ls (mode = ql) [string]
FTOOLS internal -- users should not need to change.
.le
.ih
EXAMPLES
.ih    
NOTES:
.nf
*TRUNCATION ERRORS*
The basic photon counting logic is integer-based.  Hence, there is
a danger of truncation errors occurring when the phase bins are
chosen smaller than the data bins, in Binned, Single-bit, or
Pulsar-fold mode.  The code tries to protect against this happening,
but cannot be fully guaranteed.  If you suspect that events have
lost in the phase binning operation (e.g., by comparing the total
number of events), you may want to try running fasebin with fewer
phase bins.

*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.
 
JPLEPH:
This file contains a FITS version of the JPL DE-200 ephemeris.  It
will be upgraded as appropriate to the next JPL ephemeris.
 
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 be necessary 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.  The address of the
ftp site is pulsar.princeton.edu; the file can be found in the directory
/gro; and the name of the file at the Princeton site is
actually jcat; do not use psrtime.dat from pulsar.princeton.
 
psrbin.dat:
This ASCII file contains the orbit ephemerides for binary pulsars from
the radio pulsar database.  The same comments apply here as for
psrtime.dat, except that the name at the ftp site is really psrbin.dat.
 
tdc.data:
This ASCII file contains the XTE clock correction parameters.  Updates
may be obtained from the XTE ftp site or web page.
.fi
.ih
BUGS
.le
.ls Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
FBADD FBSUB FBFSUM FBSSUM
.endhelp
