epfold

             timing tools

             epfold,time,rate,raterr=raterr,pstart=pstart,pstop=pstop,
                    nbins=nbins,sampling=sampling,/chisq

             time : a vector containing the time in arbitary units
                    (usually to be assumed seconds)
             rate : a vector containing the countrate; if not given,
                    the times are assumed to come from individual events
             pstart:   lowest period to be considered
             pstop:    highest period to be considered

             gti: at the moment for event data only: gti[2,*] is an
                  array with the good times from the event selection,
                  gti[0,*] are the start times, gti[1,*] the stop
                  times. Obviously, use the same time system for time
                  and gti (i.e., also barycenter gtis!). Needed for
                  the computation of the exposure time of the phase
                  bins, if not given, the time of the first and the
                  last event is used instead.
             gap: array containing bad bins (e.g., gaps in the
                  lightcurve). computed in pfold with timegap or from
                  the gtis if not given, and possibly returned if an
                  undeclared variable is passed through the gap keyword
             raterror: a given error vector for the countrate. If not
                       given and we are not working on events,
                       raterror is computed using Poissonian
                       statistics.
             nbins:    number of phase-bins to be used in creating the trial
                       pulse (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
             trial_period : array contains the trial periods. If set,
                            pstart is the smallest trial period and
                            pstop the longest.
            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 timegap.pro for further
                       explanation). Only used if no gti is given.
             pdot,pddot: period derivative and 2nd period derivative
                       (NB: these are NOT stepped, so they make only
                       sense, e.g., when epfold is called from a
                       two-parametric period search)
             time0:    epoch for folding

             fitchi   : fit a Gauss distribution to the chi^2 and use
                        the center of the gauss to determine the
                        period, instead of using the maximum of the
                        chi^2 distribution. This is mainly needed by
                        eperror.pro. In case this keyword is set
                        chierg will be 3 dimensional array and the
                        fit result is stored in
                        chierg[2,*]. maxchierg[1] still contains the
                        maximum chi^2 and NOT the chi^2 of the fitted
                        period !!
             chatty   : if set, be chatty
             fchatty  : chatty keyword for pfold
             mjd      : if set, time is assumed in days, but the
                        period will be in seconds anyway (apart from
                        mjd being set, period is in the same units as time)

             chierg   : 2D-array, chierg[0,*] contains the trial
                        period, and chierg[1,*] the respective chi^2
                        value.

             maxchierg: 2 dim. array, maxchierg[0] contains the
                        period of maximum chi^2, and maxchierg[1] the
                        respective maximum chi^2
             persig   : uncertainty of that period, from triangular
                        approximation, not to be interpreted in a
                        statistical sense!
             gap      : see above (optional inputs)

             none

             none

             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 pstart and
             pstop, and the period interval has to be resonable
             large.

             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 pstart and
             pstop 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
             routine, since the values are only asymptotically chi^2
             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

 $Log: epfold.pro,v $
 Revision 1.28  2007/11/24 15:48:06  wilms
 small changes in mpfitexpr code (but it still does not work)
 Revision 1.27  2005/06/08 19:34:59  wilms
 correct computation of TGes (total exposure) in case the mjd keyword
 is set (TGes is always in seconds)
 Revision 1.26  2005/05/14 20:59:25  wilms
 added mjd keyword
 Revision 1.25  2004/11/26 08:37:49  wilms
 we now assume that for event data the events are given from a pure
 poisson process, i.e., their standard deviation is the sqrt of the
 mean count rate.
 Revision 1.24  2004/11/25 17:56:17  wilms
 modifications such that epfold works with the pfold modifications,
 where we now return bins set to NaN in the case that the exposure time
 of the bin is zero.
 chierg is now set to nan if we cannot compute a profile for a given
 period (I do not think this ever happens, though, so this is only the
 case for the most bizarre situations).
 Revision 1.23  2004/11/01 21:27:27  wilms
 added fchatty keyword
 Revision 1.22  2004/09/13 16:00:03  wilms
 remove subtraction of time[0] from lightcurve since that matters
 if time0 is set and we have a pdot. This better didn't change any
 results...
 Revision 1.21  2004/09/07 17:32:08  wilms
 added pdot and pddot keywords
 Revision 1.20  2004/09/06 20:55:41  wilms
 * removed major bug in which gaps in lightcurves were not properly
   taken into account, leading to spurious features in chi^2(P).
 * Added gap keyword.
 * Various cosmetic cleanups
 Revision 1.19  2004/09/06 18:34:38  wilms
 nicer debugging output when chatty=1
 Revision 1.18  2004/08/03 15:58:00  goehler
 fix of special case when gti array contains only single entry.
 Revision 1.17  2004/07/20 17:25:35  wilms
 now correctly compute tges for events data (is last time minus first
 time, not total exposure)
 Revision 1.16  2004/05/24 18:02:58  wilms
 better chatty output, some cosmetic changes
 Revision 1.15  2004/05/24 12:10:21  wilms
 removed "@mpfitexpr" since this function is loaded automatically, so
 no action is needed within the code (if it is NOT loaded
 automatically, something is wrong with the IDL-setup)
 Revision 1.14  2004/03/16 13:58:11  goehler
 change/fix: replacement of mpevalexpr with actual computation using the "execute" function
             this circumvents some problems of the mpfitexpr package.
 Revision 1.13  2004/03/16 09:12:56  rodina
 Add @mpfitexpr string
 Revision 1.12  2004/03/15 14:10:44  rodina
 replacement of gaussfit with the better converging
 mpfitexpr routine.
 Revision 1.11  2003/07/10 13:57:54  goehler
 fix: if rate is given (as input inrate) no gti determination
      needed. Problem of asking for "rate" variable existence instead of
      inrate.
 And: Set start/stop time as gti if none given (+warning).
 Revision 1.10  2003/07/02 09:28:06  wilms
 Ljuba Rodina/Joern Wilms, IAAT: added support for event data epoch folding
 ----- EARLIER HISTORY --------
             Version 1.0, Michael Koenig IAAT
             Version 1.1, 1998/04/04, Markus Kuster IAAT
             Version 2.0, 1998/07/01, Joern Wilms, IAAT
             Version 2.1, 1998/07/20, Joern Wilms, IAAT
                Now use clearer formula for chi^2
             Version 2.2, 1999/08/05, Joern Wilms, IAAT
                * make use of dt keyword of new pfold
                  (slight speed improvement)
                * removed significance keyword
                  (caused too much trouble)
             Version 2.3, 2000/11/28, SB,
                  add maxchierg optional output
             Version 2.4, 2001/01/08, SB,
                  add linear optional input/keyword
             Version 2.5, 2001/03/07, SB,
                  add trial_period optional input
             Version 2.6, 2001/07/30, Markus Kuster, IAAT
                  add fitchi keyword
   --------- SWITCH TO CVS LOGGING ----, see above!

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