Xronos
EFOLD (Jan96)                 xanadu.xronos                EFOLD (Jan96)



NAME
    efold  -- Creates folded lightcurves and plots up to 4  simultaneous
    time   series.  For  multi-time  series,  ratio  and  sum  are  also 
    calculated.
    
    
USAGE
    efold nser file(s)+options window sepoch dper  nphase  nbint  nintfm
          plot plotdev plotdnum outfile
    
    
DESCRIPTION
    This  task  calculates  folded  lightcurves,  plots  and outputs the
    results (in a FITS file). Up to 4 simultaneous time  series  can  be
    input  (See FILELIST and INPUT FILE OPTIONS) and ratios and sums are
    calculated (for more that 2 input series).  The  input  file  format
    is  FITS  using  the BINTABLE extension. Both binned data format and
    event format are input. Time, Phase, Intensity and Exposure  windows
    (See  WINDOW)  allow  for  data screening. Input data can be divided
    into Intervals and  Frames  (See  GENERAL  XRONOS  TERMINOLOGY).  In
    folding  applications  the  newbin  time  corresponds  to  the  time 
    duration of a phase  bin  in  the  folded  light  curve,  internally
    calculated  after  input  a number of phase bins. Folded lightcurves
    from different intervals can be averaged in one or more frame.   The
    standard  plot output is normalised counts/sec versus phase, but for
    multiple time series the hardness  and  colour-colour  diagrams  are
    available  where appropriate. The plotting is performed through PLT,
    and further plot manipulation or data fitting can be done  from  the
    PLT  prompt  (See  also PLOT).  The analysis results are written, if
    specified, into a FITS file (See OUTPUT file).  The error  bars  are
    calculated   after   averaging  folded  lightcurves  from  different 
    intervals in a frame, either using the  standard  deviation  of  the
    mean  values  of  each  phase  bin  or propagating the error in each
    phase.  The first method is used  if  the  number  of  intervals  is
    higher  than  the  value  set for the "errorbars" parameter (default
    =5).   Different  normalizations  can  be  used   for   the   folded 
    lightcurve   by   changing   the   parameter   "normalization"  (See 
    normalization).
    
    
normalizationS
    The  "normalization"  paramater  has  the  following  meanings  (and 
    values) :
     * =0  folded light curve are normalised to counts/s
     * =1  (d/f) folded light curves are normalised by dividing by 
           the average source intensity in the frame (normalised intensity)
    If  other  values than those listed above are used, they are treated
    as  =0.  Note  the  hardness  ratios  are  not   affected   by   the 
    normalization flag.
    
    
GENERAL XRONOS TERMINOLOGY
    Within  XRONOS  tasks,  BINS and NEWBINS control the binning used in
    the analysis, INTERVALS the  subdivision  of  the  time  series  and
    FRAME the grouping of the output results:
    
    BINS  :  these  are the time bins of the time series being analysed.
    More than one input file can have different bin durations, e.g.  two
    consecutive  time series, one with 0.5 s bins and the other with 2 s
    bins. The original bin time is the value stored in  the  input  file
    in  the  keyword  TIMEDEL.  If the data are stored in each row as an
    array with 1CTYPn = 'TIME', the original bin is  set  to  the  value
    stored in the keyword 1CDLTn (where n is the column number).
    
    NEWBINS  :  these  correspond  to  the  time resolution at which the
    analysis is carried out.  Note that: (i) newbins cannot  be  shorter
    than  the  longest  bin  duration of the time series being analysed;
    (ii) in many XRONOS applications (e.g. powspec, autocor,  crosscorr)
    the  newbin  duration  is  forced  to  be an integer multiple of the
    longest bin duration.
    
    INTERVAL : an interval is defined by  the  number  of  newbins  over
    which  the  analysis is carried out. Note that in applications using
    FFT algorithms (e.g. powspec,  autocor  and  crosscor  set  in  fast
    mode) the number of newbins in an interval is a power of 2.
    
    FRAME  :  a  frame  consists  of  the  average of the results of the
    analysis  of  one  or  more  contiguous  intervals.  Note  that   in 
    'lcurve',  'efsearch'  and  'lcstats' a frame consists always of one
    interval.
    
    
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    "    "    "         "    "    "     "  "   "          " 
    
    
    
PLOT
    The array of results from each XRONOS task can be plotted.  The  PLT
    routine  (See  also  the  QDP/PLT  manual)  provides the interactive
    plotting and fitting functions. The plotting function  is  available
    for  the  following  tasks  :  autocor,  crosscor,  efold, efsearch,
    lcurve,   powspec   and   timeskew.   For   programs   that   handle  
    simultaneously  more  than  one  time series, e.g. lcurve and efold,
    different types of analysis result can be plotted depending  on  the
    number  of  input  time  series. For two  input  time  series,  three
    different plots are provided (1) the sum of the  intensities of  the
    two input series on  the  X-axis and on the Y-axis the  count  ratio
    (ser2/ser1)  of  the  two  input  series  (Hardness-plot); (2)  Time
    (or Phase) on the X-axis and the intensity on the Y-axis for the two
    input time series; (3)  As (2)  but  also  the ratio is plotted. For
    three or four input time series two different plots  are  available:
    (1) Colour-Colour diagram that  shows  the  ratio  of  ser3/ser2  or
    ser4/ser3 on the Y-axis (for 3 or 4 input series  respectively)  and
    ser2/ser1 (always) on the X-axis; (2) Time (or Phase) on  the X-axis
    and  the intensity on the Y-axis for the 3 (or 4) input time series.
    The  choice  of  the  plot  type  is  done  by setting the parameter
    "plotnum".Note that in the 'efold' plot with Phase on the X-axis,the 
    Y-axis can be either count/s or count/s normalised by average source
    intensity. Note  that  for  the  multicolor  tasks  all  the  arrays 
    calculated by lcurve or efold are available in 'PLT>'. A color ratio 
    plot versus time or phase can be obtained as follows. At the prompt:
    Two plotting styles available:
    Colour-Colour [1] ; Intensity vs Time (or Phase)[ # of series (3 or 4)];
    Enter PLOT style number (default=1)[]
    enter the number of time series. On the screen the plot has  as many
    panels as many input series, showing the  counts  for each series on
    the Y-axis and time or phase on the X-axis.At the 'PLT>' prompt type
    'info' which gives the list of arrays available. For example  for  3
    input series the 'info' command gives :
    PLT> info
    Scales:
    Grp  Wind    Label     XData Min    XData Max    YData Min    YData Max
    1    -1  Time (s)   :  3496.    ,   8646.     :  3496.    ,   8646.
    2     2  Ser 1      :  3496.    ,   8646.     :  331.8    ,   466.4
    3     3  Ser 2      :  3496.    ,   8646.     :  415.9    ,   613.8
    4     4  Ser 3      :  3496.    ,   8646.     :  747.7    ,   1080.
    5    -1  Ser 2/Ser  :  3496.    ,   8646.     :  1.222    ,   1.325
    6    -1  Ser 3/Ser  :  3496.    ,   8646.     :  1.755    ,   1.819
    7    -1  Ser 1+2+3  :  3496.    ,   8646.     :  1495.    ,   2160.
    8    -1             :  3496.    ,   8646.     :  1.000    ,   1.000
    PLT>
    To plot the ratios (array number 5 and 6) versus time  together with
    the three input lightcurves use the following commands:
    PLT> color 1 on 5 6
    PLT> plot ver
    PLT> plot
    The final plot will contain 5 panels. The first three  are the input
    series the last two the ratios.

    A number of commands can be entered from the 'PLT>' prompt to  allow
    plot  customisation  (e.g. Add/remove labels; Plot data with various
    combinations of lines, markers, and error bars; Change  text  fonts;
    Change  X-axis  and/or  Y-axis;  Change  number  of  plotted panels;
    Define and Fit models to data). Useful QDP Commands are:
    PLT> r x xlow xhigh             * Rescale X axis 
    PLT> r y ylow yhigh             * Rescale Y axis 
    PLT> r xlow xhigh ylow yhigh    * Rescale both
    PLT> log x                      * X axis is plot in logarithmic scale 
    PLT> log y                      * Y axis is plot in logarithmic scale
    PLT> log off                    * Turn off the logarithmic axes (both X and Y)
    PLT> dev /xxx                   * Change the current plot device 
    PLT> mo ?                       * List available model
    PLT> mo cons linr               * Define model= constant plus linear 
    plt> fit                        * Fit the defined model
    PLT> hardcopy filename          * Hardcopy of the current plot (postscript)
    PLT> exit                       * EXit: to exit from the PLT subroutine type:
    The QDP/PLT software is provided and  maintained  by  Allyn  Tennant
    (Marshall  Space  Flight  Center).  The PLT software uses the PGPLOT
    Graphics Subroutine Library for plotting, written  by  T.J.  Pearson
    (California Institute of Technology).
    
    
    
OUTPUT
    The  analysis  results are output in a FITS file. Two different FITS
    layouts are available (see parameter outfiletype). The first  stores
    one  interval (or frame) of interval results per FITS table row, and
    the output file will have a single extension. The second stores  one
    interval  (or  frame)  per  FITS extension, and the output file will
    have as many extensions as the number of intervals (or frames).
    
    The output file contains, besides the array of results, a number  of
    statistical  variables  (and  errors if appropriate) associated with
    each interval (or frame)  for  each  time  series.   These  are:  1-
    average  count/s  in  frame  (in  a frame this is the average of the
    averages in  intervals);  2-  fractional  exposure  in  frame  (from
    average  of  fractional  exposures  in  intervals, the latter is the
    ratio  of  good  newbins   to   the   total   number   of   expected 
    newbins/interval);  3-variance  in  frame  (average  of variances in
    intervals); 4- expected variance in frame (average of  the  expected
    variances  in  intervals,  the  latter  is calculated from the error
    bars of the newbins);  5-  3rd  moment  in  frame  (average  of  3rd
    moments  in  intervals);  6-  minimum  count/s  in frame; 7- maximun
    count/s in frame; 8- excess variance in  frame  (average  of  excess
    variances    in    intervals,    the   latter   is   calculated   as  
    variance-expected variance); 9-  chi-square  in  frame  (average  of
    chi-squares  in  intervals);  10-rms  fractional  variation in frame
    (average of rms fractional variation in  intervals,  the  latter  is
    calculated  as the square root of the excess variance divided by the
    average.
    
    The output for 'efold' task consists of phase and  counts/s  vectors
    (with  associated  error  columns) There are as many count/s vectors
    as there are of time series analysed (therefore up  to  4).   For  2
    input  series  the  additional columns contain the ratio (ser2/ser1)
    and the sum (ser1+ser2) of the input series and their errors. For  3
    input  series  the  additional columns contain two ratios (ser2/ser1
    and ser3/ser2) and the sum (ser1+ser2+ser3) and their errors. For  4
    input  series  the  additional columns contain two ratios (ser2/ser1
    and ser4/ser3) and the sum (ser1+ser2+ser3+ser4) and  their  errors.
    The  output also contains a fractional exposure column (currently is
    filled with values  different from 1 only for 1 input series)
    
    
PARAMETERS
    
    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.
    
    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".
    
    cfile2 (filename(s) second series) [string]
        As  PARAMETER  file1  (See  description  of "Filelist format and
        Input File Options").
    
    cfile3 (filename(s) third series) [string]
        As PARAMETER file1 (See  description  of  "Filelist  format  and
        Input File Options").
    
    cfile4 (filename(s) fourth series) [string]
        SEE  PARAMETER  file1  (See  description of "Filelist format 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.
    
    epochfo (format for epoch) [integer]
        Specify  format  for  the  input  epoch of phase zero. There are
        three possible formats for "epochfo": (1)  days  ;  (2)  integer
        days  and  second (dd ss) ; and (3) days hours minute second and
        millisecond (dd hh mm ss ms). The "epochfo"  default  format  is
        set to days (1).
    
    sepoch (Epoch value) [string]
        Value  for  epoch used as phase zero in the folding. The default
        value is the integer day of the start time.
    
    perfo (period format) [integer] 
        Specify format for the input period. The  period  can  be  input
        either  as  fractional  days ("perfo"=1) or in seconds ("perfo"=
        2). The default value is set to seconds (2).
    
    dper (period value) [double]
        Value for the period used in  the  folding.  In  'efsearch'  the
        input  period  represents  the  centre of the range of the trial
        periods.
    
    dpdot (period derivative) [double]
        Period derivative.
    
    nphase (number of phases per period) [integer]
        Number of phases in the folded light  curve(s).  Typing  'INDEF'
        forces  the  task  to  use  the  default  value  (see  parameter 
        "nbdf"). NOTE: By pressing return "nphase" is set to  the  value
        found in the parameter file used in a previous run.
    
    nbint (number of points per interval) [integer]
        The  number  of  newbins  per interval used in the analysis. The
        "nbint" together with the NEWBIN duration determines the  length
        in  time  of  an  interval  and  therefore  the  total number of
        intervals  within  the  start  and  stop  time  over  which  the 
        analysis  will  be  carried out.  Typing 'INDEF' forces the task
        to use the default  value  (see  parameter  "nbdf").   NOTE:  By
        pressing  return  "nbint"  is  set  to  the  value  found in the
        parameter file used in a previous run.
    
    nintfm (number of intervals per frame) [integer]
        The results of the analysis from  individual  intervals  can  be
        averaged  to  produce  a frame.  The "nintfm" is used to specify
        the number of intervals averaged  in  a  frame.  Typing  'INDEF'
        forces  the task to use the default value (all intervals will be
        use in one frame).  NOTE: By pressing return "nintfm" is set  to
        the value found in the parameter file used in a previous run.
    
    outfile (output filename) [string]
        Name  of the output file. If only the root is given, the program
        adds an extension of 3 characters, '.fXX', where  f  stands  for
        FITS  and  XX  is  a  suffix  which  identifies the program that
        creates the output. The XX values are  :  'ac'  (autocor),  'cc'
        (crosscor),  'ef  (efold),  'es' (efsearch), 'lc' (lcurve), 'ps'
        (powspec), 'ts' (timeskew). Typing '-'  forces  the  program  to
        generate   a   default   value  for  the  output  filename  (see 
        outfileroot  parameter).  By  typing  blank  characters  at  the 
        prompt no output file will be created.
    
    outfileroot (default value) [string]
        This  parameter  used  in conjunction with "outfile" generates a
        default output  filename.  If  the  value  of  "outfileroot"  is
        'default'  and  "outfile"  is '-', the output filename will have
        the same root name of the first input file of  the  fits  series
        with a '.fXX' extension (see outfile for XX values).
    
    outfiletype (Type of FITS layout) [integer]
        Define  the  FITS  structure  for the output file. Two types are
        available.  The first type (outfiletype=1)  has  1  interval  of
        results  per FITS table row.  The output file will have only one
        extension. Each row of the results column contains an  array  of
        values  with  a  size equal to the number of points per interval
        (or frame) and a number of rows equal to  the  valid  number  of
        intervals  analysed.   The  second  type  (outfiletype=2)  has 1
        interval of results per FITS extension.  The  output  file  will
        have  as  many  extension as the number of intervals (or frames)
        analysed.  The  column  containing  the  results  has  a  single 
        element  value  in  each  row and the number of rows is equal to
        the number of points in the  interval.   The  default  value  of
        "outfiletype" is 2 (one interval per FITS extension).
    
    plot (if plot) [boolean]
        Flag  specifying  whether or not the results of the analysis are
        plotted via PLT  (default  =  yes).  NOTE:  After  plotting  the
        results   the   XRONOS   task   is   left   in  the  interactive 
        plotting/fitting  mode  (PLT>  prompt)  use  command  `exit`  to 
        return  and  finish  the XRONOS task. If the "plot" parameter is
        set = no, the other queries regarding the plotting are  disabled
        ("plotdev", "plotfile", "plotdum").
    
    plotfile (.pco file) [string]
        Name of the Plt COmmands file.  For  each  task  an  appropriate
        default  Plt COmmand file is automatically loaded by the program
        setting the parameter "plotfile" as '-'.  The  user  can  insert
        additional commands using his  own  '.pco'  file at this level (
        or within the PLT> prompt).The user commands are appended to the
        default command file and therefore executed last. The    default
        '.pco' files are   stored   in   the   directory defined by  the
        parameter 'dpath'.
    
    plotfile (.pco file) [string]
        Name  of  the  Plt  COmmands  file. For each task an appropriate
        default Plt COmmand file is automatically loaded by the  program
        setting  the  parameter  "plotfile" as '-'.  The user can insert
        his own '.pco' file at this level (or within  the  PLT>  prompt)
        but  it  is  recommended  to  look  at  the plot produced by the
        default '.pco' file beforehand.  The default  '.pco'  files  are
        stored in the directory defined by the parameter 'dpath'.
    
    plotdnum (No. of plots) [integer] 
        The  parameter  sets the number of subplots which will appear on
        the  plotting  device.   For  more  than  1  input  series,  two 
        different  plots  are  provided  which are differentiated by the
        number of final subplot. The first has TIME  or  PHASE  (default
        plot)  on  the  X-axis and as many Y-axis as the number of input
        time series (lightcurve or  folded  lightcurve).  The  parameter
        "plotdnum",  in  this  case,  should  be  set equal to the total
        number of timeseries (e.g. 1 or 2 or 3 or 4).  The  second  plot
        type  is  available  only  for  2  or more time series and gives
        either  Hardness  versus   total   Intensity   (2   series)   or 
        Colour-Colour  diagram  (3  or 4 series). To obtain this type of
        plot, the parameter "plotnum" should be set equal  1  regardless
        of the time series number.
    
    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.
        
        gapfill (running mean gap filling) [integer]
            Replace gaps in input series with running mean.  If =0  (the
            default)  data  gaps are not filled.  If =n newbin data gaps
            in input series are  filled  in  with  running  mean  values
            calculated  over n newbins. Note that a gap newbin is filled
            in only if the  corresponding  running  mean  is  calculated
            over  n/4  points  at  least  (this  means  that in order to
            bridge a gap of m newbins n must be  >1.35m).   This  global
            parameter  is  ignored  in epoch folding applications (efold
            and efsearch).
        
        forcestart (flag for start time) [boolean]
            If = yes the first interval will be forced to start  at  the
            time  of  the  first time window otherwise (=no default) the
            center time of the first qualified newbin  is  used  as  the
            start time.
        
        errorbars (Error bar Evaluation) [integer]
            This  parameter  defines  the way in which the error bars of
            the analysis results are calculated. If the  number  of  the
            intervals  per  frame  ("nintfm") is higher than "errorbars"
            value (default=5), the error bars  are  evaluated  by  using
            the   standard  deviation  of  the  average  (based  on  the 
            measured scatter). Otherwise the error  bars  are  evaluated
            by   propagating  the  theoretical  error  bars  through  an 
            averaging   process.    Note   that   for   several   XRONOS  
            applications  (e.g.  `autocor`,  `crosscor`) only the former
            way of evaluating error bars is available.  For example,  if
            "errorbars"  is  5  in  the  application `powspec`: (a) if a
            frame contains the average of  5  or  fewer  power  spectra,
            then  the  error  bars in the average power spectrum will be
            calculated  by   propagating   through   the   average   the 
            theoretical  error  bars associated with each power spectrum
            (in   turn   obtained   from   the    relevant    chi-square  
            distribution);  (b)  if a frame contains the average of 6 or
            more power spectra, then  the  error  bars  in  the  average
            power   spectrum   will  be  calculated  by  evaluating  the 
            standard deviation of the average power for each  frequency.
            By  adjusting  the value of "errorbars" it is possible, e.g.
            to evaluate error bars as in (a), also in the case in  which
            a  large  number  of intervals per frame has been specified.
            Values < 5 are not recommended (at least  5-6  measures  are
            necessary  to  reliably  evaluate  the standard deviation of
            the  average  from  the  scatter  around  it).   NOTE:   not 
            applicable for 'lcurve', 'lcstats' and 'efsearch'.
        
        exposure (flag for analysis of exposure profile) [boolean]
            If  =yes the exposure profile(s) (i.e. newbin values are set
            =1, gaps and rejected newbins are set  =0)  is/are  analysed
            (instead of the input series). Default value is = no.
        
        normalization (type of normalization) [integer]
            Flag  to  specify  the type of normalization to apply to the
            results.  This parameter is only relevant for the  following
            tasks:  powspec,  autocor,  efold,  crosscor, timeskew). The
            standard normalization corresponds to  a  value  of  1  (the
            default)  in  all  XRONOS  applications. Other normalization
            value  flags  are  described  for  each   application   (See 
            normalization).   NOTE:  not  applicable  for  'lcurve'  and 
            'efsearch'.
        
        simultaneous (flag for simultaneity) [boolean]
            If =yes a strict simultaneity is forced  between  the  input
            series  in applications which use more then one series (i.e.
            if the n-th newbin of a series is  a  gap  or  is  rejected,
            then  the  n-th  newbin  of  all  other  series will be also
            rejected). This flag is ignored in the  efold  applications.
            Default value is = no.
        
        spwinbefore (special window start) [double]
            Special  newbin  window  :  number  of  seconds before. If a
            value > 0 is used , e.g. 10.0, then all the  newbins  within
            10.0  seconds  before  a  newbin  rejected  by  an intensity
            window will also be rejected. The default  (=0)  is  not  to
            apply this type of special newbin window.
        
        spwinafter (special window stop) [double]
            Special  newbin window : number of seconds after. If a value
            >0 is used , e.g. 10.0, then all  the  newbins  within  10.0
            seconds  after a newbin rejected by an intensity window will
            also be rejected. The default (=0)  is  not  to  apply  this
            type of special newbin window.
        
        rescale (rescaling for results) [double]
            Rescaling  factor  applied  to  result variables and errors.
            The rescaling is applied  just  before  writing  the  output
            file  (this to avoid affecting the statistical variables for
            the frame). Default value for "rescale" is set to 1.
        
        offset (additive constant for results) [double]
            Additive constant summed to result variables.  Result  error
            bars  are  left  unchanged.   The additive constant is added
            just before writing  the  output  file  (this  is  to  avoid
            affecting  the  statistical  variables  for the frame). Note
            that if a rescaling  factor  is  also  specified  (different
            from  1),  then  the  results  are  first  multiplied by the
            rescaling factor. Default value for "rescale" is set to 0.
        
        flatexpo (Flag uses a flat exposure in event file) [boolean]
            This parameter sets the exposure in each bin of the   folded 
            lightcurve to be constant (=1) when dealing with event file.
            For  an   event  file  the exposure in  each  folded bin  is 
            calculated using the GTI extension to  account  for the data 
            gap in the data. If the period used in the folding  is  very 
            short compared  to  the  gaps, this calculation  slows  down 
            the program since calculates  the exposure for each "nbint".
            For  fast  periods  since  the  number of  bins effected  by 
            the gap is  quite  reduced,  it  is  possible  to speed  the  
            calculation by setting the "flatexpo=yes". This flag is only 
            valid for input event files for the efold and efsearch task. 

        fast (Flag for fast algorithm) [boolean]
            This parameter sets the  type  of  algorithm  used  for  the
            Fourier  transform.   IMPORTANT  NOTE: This parameter can be
            set by  the  user  only  in  the  `powspec`,  `autocor`  and
            `crosscor`  tasks  (it is a query parameter in these tasks).
            In all the other tasks "fast" 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.  For  a  single file data (1 time series) of length 5000 seconds,
    calculate the folded    lightcurve using a period of 37 seconds  and
    10  phase  bins  using  1352 data points    (this will correspond to
    one interval per frame). Make a plot    and output the results.
       > efold nser=1 cfile1="myfile.lc" window="-" sepoch=INDEF dper=37 
         nphase=10 nbint=1352 nintfm=INDEF plot=yes plotdev="/xw" plotdnum=1 
         outfile="-" 
    2. As above but using only 300 points per interval and  average  all
    the intervals    in one frame.
    
       > efold nser=1 cfile1="myfile.lc" window="-" sepoch=INDEF dper=37 
         nphase=10 nbint=300 nintfm=INDEF plot=yes plotdev="/xw" plotdnum=1 
         outfile="-" 
    3.  As  above  but  using  3 input series and plot the Colour-Colour
    diagram
    
       > efold nser=3 cfile1="@all.lis" window="-" sepoch=INDEF dper=37  
         nphase=10 nbint=300 nintfm=INDEF plot=yes plotdev="/xw" plotdnum=1 
         outfile="-" 
    
    
SEE ALSO
    efsearch, crosscor, autocor,  powspec,  lcstats,  lcurve,  listdata,
    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).

Xronos Home Page Xanadu Home Page Xanadu ftp site

Please send reports of errors to : xanprob@athena.gsfc.nasa.gov
HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: Thursday, 06-May-2004 13:46:59 EDT