epfold

           performs epoche folding on data set(s) withing certain
           period ranges. Tries to look for periods.

           cafe

         epfold[,range][,subgroup][,group][,/add]

           range    - (optional) Defines range of data points to fold. This can
                      be either:
                       - Data point range, denoted by the data
                         point number:
                         <n1>[-], while ,  are positive
                         numbers. Data point numbers start from zero.
                         Open intervals can be represented with a
                         "*" instead of the number.
                         If only one number is given, a single
                         data point will be referenced.
                         If <val2> is less than  all but the
                         interval <val2>.. are referenced.
                       - X value range, denoted by float point numbers:
                         <val1>-, while , 
                         represents X values defining the interval to
                         reference. Open intervals can be represented
                         with a *  instead of the value. If <val2> is
                         less than <val1> all but the interval
                         <val2>.. is referenced.
                       - Vector of data point indices. The vector is
                         denoted with [val,val,...,val] (indgen may
                         be used also).
                       - Boolean expressions with X/Y values. All
                         values for which this expression is true are
                         referenced. The expression may contain
                         algebraic formulas combined with comparison
                         operators "lt", "le", "eq", "gt", "ge" as used in IDL
                         comparisons. For each data point a keyword
                         is defined which has meaning and can be used
                         for the boolean expression:
                                 x - The x-column value.
                                 y - The y-column value.
                             error - The error column value.
                          selected - True when the data point is selected.
                               def - True when the data point is defined.
                               x1  - Multi column first column value.
                               x2  - Multi column second column
                                     value.
                               x3  - Multi column third column value.
                         To avoid interference with functions which
                         also can be used a lower/upper case
                         distinction  is made. IDL funktions should
                         be upper case.
                      Default is the entire data set to fold.
           subgroup - (optional) The data set (subgroup) for which the model
                      should be applied. This can be either the
                      subgroup number or the file name representing
                      the data set. It is possible to set more than
                      one subgroup, either with numbers in brackets
                      ([]) separated with ","; or denoting filenames
                      with wildcards ("*").
                      Default are all subgroups in currently used
                      group.
           group    - (optional) The data group for which folding
                      should applied.
                      Default is the current group. Must be in
                      range [0..29].

          pmin      - Lowest period for range.  Default: 1
          pmax      - Highest period for range. Default: 100
          nbins     - Number of bins to use for folding. Default: 20.
          sampling  - how many periods per peak to use   Default:10.
          linear    - if set, use a linear trial period array with
                      step equal to the value of linear
          tolerance - parameter defining the lower limit for the gap
                      length; the reference is the time difference
                      between the first and second entry in the time
                      array; tolerance defines the maximum allowed relative
                      deviation from this reference bin length;
                      default: 1e-8; this parameter is passed to timegap
                      (see timgap.pro for further explanation).
          lstat     - Use L-Statistic instead of Chi^2 for
                      chierg[1,*]; Davies, S.R., 1990, MNRAS 244, 93
          events    - Consider input to contain events only. In this
                      case only the time (x) axis is used and folded
                      as single events.
                      To work properly the data sets must not contain
                      any gaps which are not acknowledged by to be
                      outside of the good time interval (s.b.).
          gti       - Good time interval (for events only). Must be
                      2-D array with of the form: gti[2,*]. It
                      defines the start (gti[0,*]) and stop
                      (gti[1,*]) time of event times (x) to be used
                      for the epfold process.
                      If not given it will be computed under
                      following assumptions:
                      1.) start and stop of each data set define the
                          outer gti boundary.
                      2.) ignored data points define inner gti
                          boundaries.
          pdot      - Take period derivative into account. If a
                      single value is given this one will be
                      computed. If pdot is of the form pdot = [a,b]
                      then the period derivative will be scanned from
                      in the range a..b. The number of steps are
                      defined with pdotnum (s.b.).
          pdotnum   - Number of steps to perform if pdot defines a
                      scanning interval a..b.
          pddot     - Second derivative of period to be taken into
                      account.
          time0     - Epoch for folding, needed when usind
                      pdot/pddot.
          verbose   - Show progress information.

           All data points given as input are summed up within a
           histogram according their x value modulo a period. The
           period must be set before.
           Dataset name/File name of the product are "EPFOLD", if
           more than one pdot is scanned (pdotnum>1) the dataset name
           is "EPFOLD_PDOT".

           Creates/Overrides first subgroup in the result group.

           The input lightcurve has to be given in count rates (not
           in photon numbers). To prevent convergence problems of
           the fit (only if keyword /fitchi is set), the maximum of
           the chi^2 distribution has to be in between pmin and
           pmax, and the period interval has to be resonable large.

           The command calls the procedure epfold.pro.
           This subroutine performs a period search using epoch
           folding. For each trial period, a pulse profile is
           generated using pfold. This profile is then tested for
           constancy using a chi^2 test. The maximum chi^2, i.e., the
           maximum deviation, is the most possible period. This is
           done for all periods between pmin and pmax using a
           grid-search operating on the minimum possible period that
           can still be detected (given by p^2/t).
           Caveat: The significance of the found periods SHOULD NOT
           be tested using the chi^2 value obtained from this
           distributed (see Davies, 1990, Schwarzenberg-Czerny, 1989,
           Larsson, 1996) Read (and understand) the references before
           using this routine!

           Davies, S.R., 1990, MNRAS 244, 93
           Larsson, S., 1996, A&AS 117, 197
           Leahy, D.A., Darbro, W., Elsner, R.F., et al., 1983,
           ApJ 266, 160-170
           Schwarzenberg-Czerny, A., 1989, MNRAS 241, 153

           > set, pmin=20
           > set, pmax=300
           > epfold
           -> Search periods within a range from periods=20..300 for
           -> data in current group.

           $Id: cafe_epfold.pro,v 1.16 2005/02/15 10:40:40 goehler Exp $

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]