NAME

fasebin -- The Phase Binner


USAGE

        fasebin orbitfile sourcename datafile outfile gtifile respfile roff
             nph binary l1only propane debug clobber


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.

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.


PARAMETERS

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.

sourcename [string]
B or J name of the object; this is intended for finding it in the radio pulsar database.

datafile [string]
An input data file, or the name of a file containing a list of input data files (i.e., @filelist).

outfile = faseBin.pha [string]
Output file name; if no extension is given ".pha" will be appended.

gtifile = none [string]
GTI file to be used.

nph = 100 [integer]
Number of phase bins.

(l1only = yes) [boolean]
Use only layer 1 for GoodXenon data?

(respfile = none) [string]
Name of response matrix file to be put into the header.

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

(binary = no) [boolean]
If the source is a binary pulsar, set this to "yes" to search the binary orbit table.

(propane = no) [boolean]
Use only propane data for GoodXenon data? (Setting this to "yes" overrides the l1only parameter.)

(debug = no) [boolean]
Turn on debugging output.

(clobber = yes) [boolean]
Should a pre-existing output file be overwritten?

(mode = ql) [string]
FTOOLS internal -- users should not need to change.


EXAMPLES


NOTES:

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



BUGS

Please report problems to xtehelp@athena.gsfc.nasa.gov.


SEE ALSO

FBADD FBSUB FBFSUM FBSSUM

CATEGORY

Mar97 ftools.xte