National Aeronautics and Space Administration

LISTDATA (Jan96)              xanadu.xronos             LISTDATA (Jan96)



NAME
    listdata  -- List on the screen the content of the input file.
    
    
USAGE
    listadata  file(s)+options window
    
    
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.
    
    
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 :
     * 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 
    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.
    
    
    
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.
     file1_ser1
     file2_ser1
     ///
     file1_ser2
     file2_ser2
     ///
     file1_ser3
     file2_ser3
    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 :
     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.
    
    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:
    
     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 
    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.
    
     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    "    "    "         "    "    "     "  "   "          " 
    
    
PARAMETERS
    
    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".
    
    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.
    
    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.
    
    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.
    
    logname (log filename) [string]
        Name for the log file. The default name is xronos.log.
    
    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.
    
    (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.
    
    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.
    
    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.
    
    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.
    
    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.
        
        
        
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"
    
    
    
SEE ALSO
    efold,  efsearch,  crosscor,  autocor,  powspec,  lcstats,   lcurve, 
    timeskew xronwin, fits2qdp, ascii2lc.
    
    
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).