.help listdata Jan96 xanadu.xronos
.ih
NAME
listdata  -- List on the screen the content of the input file. 
.ih
USAGE
listadata  file(s)+options window 
.ih    
DESCRIPTION
This task lists on screen a summary header and the data points of input file(s) 
for one time series. The input file format is FITS using the BINTABLE extension. 
Both binned data format and event format are input. For each data point the 
following is printed on the screen : time associated with the bin N as fractional 
day, and the h:m:s:ms of that day, the integration time (set -1 for event list),
count/s, error and fractional exposure (set to 1 for event list). Changing the 
"tchat" parameter to higher values causes the FITS header to be printed as well. 
To list only part of the data Phase, Intensity and Exposure windows (See WINDOW) 
can be used for screening. A range of data rows can be selected using the 
input option "frN" and "lrM" where n and M are the first and the row to be print 
on the screen.
.ih
WINDOWS 
If any window is required during the analysis, a window file containing the relevant 
windows must be created with the application XRONWIN, before running a XRONOS task.
There are 4 different types of windows :
.nf
 * Time Windows  : consist of up to 1000 time intervals                  
 * Phase Windows : consist of an Epoch, a Period and up to 10 phase intervals
 * Intensity Windows : consist of up to 10 intensity in bin, newbin and interval
 * Exposure Windows : consist of up to 1 exposure in bin, newbin and interval 
.fi
Intensity and Exposure Windows can be specified independently for: (i) Bins ,
(ii) New Bins , (iii) Intervals. When dealing with more than one time series, 
Intensity and Exposure Windows must be specified separately for each series. 
Time and Phase windows are applied to Bins. Intensity and Exposure windows are 
applied first to Bins, then Newbins and finally to Intervals as specified.
For time and phase windows, only those bins whose center time is within 
the start and stop of a time window or phase window (for a specified epoch and period) 
are accepted. Intensity windows must be ordered with increasing intensity
and if set for newbins can be used in conjunction with "Special Newbin Windows"
(see below).
Exposure Windows consist of a minimum and a maximum exposure level. Units are such that 1
means 100% exposure. The Newbin Exposure is obtained by propagating the bin exposures to
each newbin. For example, if in a 30 s newbin the total exposure (due to the sum of the
individual exposure of the bins contributing to the given newbin) is 18 s then its exposure
is 60%. The Interval Exposure is the ratio of accepted to expected newbins: for example, if
a 128 newbin long interval contains only 32 accepted newbins, then its exposure is 25%. Many
XRONOS application use some default exposure windows, which are designed to avoid analysing
data sets which are too inhomogeneous with respect to their statistical properties. The
minimum default Exposure windows in an Interval is set to 0.0 in the lcurve, efold and efsearch
and to 0.5 (i.e. 50% exposure ) in all the other tasks. Note that exposures can be higher
than 100% (e.g. if the newbin time is not a multiple of the bin time, then "beats" are
generated which might bring the exposure of a newbin to values >100%; or if two or more
input files for the same time series overlap in part, some of the newbins will be more than
100% exposed).
IMPORTANT NOTE WHEN TIME WINDOWS ARE SET IN THE WINDOW FILE: 
The time used within XRONOS tasks is Truncated Julian Days 
(TJD= JD-2440000.5) if either (1) the keyword MJDREF is present in the header 
or (2) if the TIMESYS value is one of the following strings MJD or JD or TJD.
If (2), the time values are expected to be stored as JD, MJD or TJD in the header 
keywords and in the TIME column in which case the MJDREF keyword is not used (it should not be present). 
When Time windows are set using XRONWIN, they must be compatible with 
the values in header of the timing keywords and/or the values in the TIME column.

An additional window type called "Special Newbin Window" can be set directly from the parameter
file. Special Newbin Windows are used to exclude the parts of a light curve which immediately
follow or precede a burst or a background event which has been rejected by intensity windows in
newbins. The Special Window operates on newbins in conjunction with intensity windows (in newbins)
and are specified by changing to positive values the parameters 'spwinbefore' and 'spwindowafter'.
Their use is the following: if e.g. spwinbefore is set =10, all newbins, whose center time is
within 10 second before the center time of a newbin rejected by intensity windows, will also be
rejected; if e.g. spwindowafter is set =20, all newbins, whose center time is within 20 second
after the center time of a newbin rejected by intensity windows, will also be rejected.
 
.ih 
FILELIST and INPUT FILE OPTIONS
To input multiple files for each time series, a file containing the list of files is 
needed (Filelist). The Filelist is input in the program as '@Filelist'.
The format of this file list is ascii and contains one filename+options 
per line. Files from different times series are separated by '///' mark. 
Below is an example of the Filelist containing 2 files for 3 different times series. 
.nf
 file1_ser1
 file2_ser1
 ///
 file1_ser2
 file2_ser2
 ///
 file1_ser3
 file2_ser3
.fi
The Input File Options (up to 10) can be specified for each file in the same input string.
They consist of 2 characters followed by a numerical constant (up to 8 character long).
There are two groups of options. The first allows data selection within a FITS 
extension. The available options within this group are :
.nf
 frN= start reading input file from row number N (first row)
 lrN= stop reading input file from row number N (last row) 
 vxN= use column number N as x-axis (i.e. time axis, default name is TIME)
 vyN= use column number N as y-axis (default names are COUNT or RATE)
 vsN= use column number N as error for y-axis (default name is ERROR)
 veN= use column number N as exposure (default name FRACEXP).
      If the input file is an event list, exposure is by default
      calculated using the GTI extension. In this case, N=0 
      turns off the usage of the GTI extension for the exposure 
      calculation, and N > 0 specifies the GTI extension to use.
 feN= select data (either binned or events) from channel number N (First Energy). 
      For an event list channel selection is made using the column named 'PHA'
 leN= select data (either binned or events) to channel number N (Last Energy). 
      For event list the default column channel name searched is 'PHA'.
      The option 'vcN' allows the choice of a channel column name different from 'PHA' (es. 'PI').
 vcN= use column number N for channel selection (valid only for event lists). 
 rtN= use extension N of the FITS file to read the data. The first extension 
      is N=1 (the primary array is irrelevant). To specify the extension the 
      following also can be used: filename[N] or filename+N.  
 of = The MJDREF keyword is not used. The time is calculated using the
      TIME column and the TIMEZERO keyword.
.fi

The second group of options performs algebraic operations on individual input files.
They are applied in the same order in which are specified. For event files they are applied
after the data are binned. The available options within this group are:

.nf
 stX = Shift all Time in input file by X days 
 ssX = Shift all times in input file by X Seconds 
 muX= multiply data and errors by X (MUltiply)
 mdX= multiply data by X (Multiply Data) 
 meX= multiply errors by X (Multiply Errors
 maX= as muX but exposure is divided by X 
 diX= divide data and errors by X (DIvide)
 ddX= divide data by X (Divide Data) 
 deX= divide errors by X (Divide Errors) 
 daX= as diX but exposure is multiplied by X
 aaX= add data and errors with X (Add All) 
 adX= add data with X (Add Data) 
 aeX= add errors with X (Add Errors) 
 saX= subtract data and errors with X (Subtract All)
 sdX= subtract data with X (Subtract Data) 
 seX= subtract errors with X (Subtract Errors) 
 qaX= add to data the square of data muliplied by X and add to errors 
      the product of data and error multiplied by X 
 qdX= as above but for data only
 qeX= as above but for error only 
.fi 
Below is an example of the Filelist containing 2 files for 3 different times series
where the different options are applied to the input files for different time series.

.nf
 file1_ser1 aa4           add to data and error 4 
 file2_ser1 aa4            "      "        "    "
 ///
 file1_ser2 rt2 aa2       read 2nd extension; add to data and error 2 
 file2_ser2 rt2 aa2        "    "     "           "      "        "    "   
 ///
 file1_ser3 rt2 vy4 vs5   read 2nd extension; use column 4 and 5 for Y-axis and Error
 file2_ser3 rt2 vy4 vs5    "    "    "         "    "    "     "  "   "          " 
.fi
.ih    
PARAMETERS
.ls cfile1 (filename(s) first series+options) [string]
Input filename(s) for the first time series + options. The valid input files are in 
FITS format using the BINTABLE extension. Xronos tasks read for each time series many 
consecutive input files (up to 50). Additional flexibility is provided by Input File Options
which are used to perform algebraic operations on individual input files
(either on the 'times' or on the 'count' or 'count/s' values). The Input file Options
are also used to select columns and rows within a FITS file.
If the first character of the input string is '@', the rest of the string is taken to 
be a filename containing the list of input files (Filelist). The Filelist can contain 
filenames for more than one series. See description of "FILELIST and INPUT FILE OPTIONS".
.le    
.ls window (name of window file) [string]
Filename of the xronos window file. The window file is an ASCII file and by default 
a standard window file is used, where only exposure windows are set. 
To modify the standard file or create a new file used the script XRONWIN.
.le
.ls tchat (terminal chattiness) [integer]
Set terminal chattiness: (0-4) only little information is output in running XRONOS task
; chattiness 5 is the default value; (6-7) more details on input files, windows, intervals 
statistics, etc.; (<8) mostly for debugging purposes.
.le
.ls lchat (log file chattiness) [integer] 
Set log file and chattiness in the log file: = 0 the log file is not written; for all other 
values, information is written in the log file. The chattiness levels are the same as for 
the terminal.
.le
.ls logname (log filename) [string]
Name for the log file. The default name is xronos.log.
.le 
.ls clobber  [boolean]
Flag specifying whether or not a pre-existing file with the same name as that requested 
for an output file in the current task will be overwritten. Default value = yes.
.le
.ls (dpath = XRDEFAULTS) [string]
This string parameter gives the path to the Xronos 'defaults' directory,
which contains the default '.pco' file (used for plotting) and the
defaults window file 'default_win.wi'. Ordinarily, the user may leave this
parameter set to the string 'XRDEFAULTS', which causes Xronos to use the
environment variable XRDEFAULTS to locate these files. XRDEFAULTS is set
by the mkftools script to point to the appropriate directory for the current
distribution of Xronos (for FTOOLS v3.6 this is /ftools/xronos/defaults/).
If the user wishes to modify these files, he or she may make and edit
copies, and change the XRDEFAULTS variable appropriately using setenv,
but the original files should not be changed.
.le
.ls nser (Number of time series) [integer]
Number of input time series simultaneously processed. 
IMPORTANT NOTE: This parameter, the values of which range between 1 and 4, can be 
set by the user only in the "lcurve" and "efold" tasks (it is a query parameter
in these two cases). In the other tasks "nser" is a non query parameter, 
and should not be changed from the default setting.
.le
.ls ipow2 (Flag if power of 2) [integer]
Internal Flag used to decide if the current task must used with a power of 2 of 
number of points (ipow2=1) per interval or not (ipow2=0). IMPORTANT NOTE: This parameter 
should not be changed by the user.
.le
.ls iavgreb (Flag if average interval) [integer]
Internal Flag used to decide if the current task allows the averaging of intervals
in frame and/or the rebinning of the analysis results. If "iavgreb" is set to -1 the results
in an interval can not be either averaged or rebinned, if set to -2, the results in an interval
can be averaged but not rebinned. IMPORTANT NOTE: This parameter should not be changed 
by the user.
.le
.ls nbdf (Default No. Bins) [integer]
Set an internal default value for the number of newbins per Interval.
This value is used to calculate the default newbin integration time 
to have one interval with nbdf points. Different "ndbf" values have 
been set for different XRONOS task. IMPORTANT NOTE: With caution this 
parameter can be changed by the user.

.ih
EXAMPLES
1. List the header and all the data of myfile.lc

   > listdata cfile1="mydata.lc" window="-" 

2. List the header and the data from row 100 to 300 of myfile.lc 

   > listdata cfile1="muyfile.lc fr100 lr300" window="-" 

3. List the header and the data of myfile.lc using time window in mywindow.wi file 

   > listdata cfile1="muyfile.lc fr100 lr300" window="mywindow.wi" 
    
.ih    
SEE ALSO
efold, efsearch, crosscor, autocor, powspec, lcstats, lcurve, timeskew
xronwin, fits2qdp, ascii2lc.
.ih
BUGS
Report problems to angelini@lheavx.gsfc.nasa.gov and
xanprob@athena.gsfc.nasa.gov.  Provide a detailed description of the 
problem (with a log file if possible).
