pfold

       folds a lightcurve with a given period or frequency and returns
       the resulting profile

       lightcurve

 pfold, time,rate,profile,period=period,nbins=nbins,time0=time0, $
           proferr=proferr,gap=gap,nogap=nogap,tolerance=tolerance, $
           phbin=phbin,ttot=ttot, raterr=raterr,chatty=chatty,npts=npts, $
           quantiles=quantiles, statquant=quant,dt=dt,gti=gti, $
           pdot=pdot,pddot=pddot

       time    : the starting time of each rate bin (seconds, unless
                 mjd keyword is given)
       rate    : the count rate of each bin (counts/second,
                 independent of the mjd keyword!)
                 if the rate argument is omitted, the code assumes
                 EVENT data instead, and time is the time at which
                 each event was detected)

       period  : period on which to fold (seconds)
       freq    : frequency on which to fold (Hz)
                    -- only one of period and freq can be given
       pdot, pddot: Pdot and Pdotdot (pulse period derivatives)
                 if pddot is set, pdot needs to be defined as well
       nudot, nuddot: nu_dot and nu_dotdot (frequency derivatives)
                 if nuddot is set, nudot needs to be defined as well
       nbins   : the number of phase bins to use
       time0   : use time0 instead of the first entry in the
                 timecolumn as zerotime of phase bin, same units as
                 time
       gti     : an array of good time intervals
                     gti(0,*) contains the starttimes,
                     gti(1,*) contains the stoptimes.
                 if given, the exposure time per phase bin (ttot) is
                 computed from this information. alternatively, for
                 lightcurves, the gap detection can be used.
       raterr  : uncertainty of the counting rates in rate(*)
       dt      : width of each time bin
       gap     : An array containing the indices of gaps in the
                 lightcurve (i.e. time(gap(2)) is the starting time
                 of the 3rd gap in the lightcurve). These bins are
                 ignored in the epoch folding.
                 If nogap is not set and no gti is given, the code determines
                    gap using the subroutine timegap and returns gap
                 If nogap is not set and a gti is known, the gti is
                    used to determines the bad bins and returns these
                    in gap
                 A result of these options is that for a given
                 lightcurve the gaps are only determined once.
      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)
                 Be aware that tolerance needs to be set to a higher
                 value if a lightcurve is barycentered after it is
                 binned. Only used if gti is not given.

       nogap   : If set, data are assumed to NOT contain any
                 gaps. Has only influence for lightcurves.
       quantiles: If set, return the 1st,2nd, and 3rd quantile in
                 keyword statquant (only for lightcurves)
       mjd     : if set, then time argument is in days, not seconds.

       profile : the pulse profile (counts/sec)

       proferr : Array containing the statistical uncertainty of each
                 bin of the profile. computed from raterr for
                 lightcurves, for event data, Poissonian errors are
                 assumed.
       phbin   : array containing the start-phase of each bin of the
                 profile
       ttot    : array containing the total observing time
                 accumulated in each bin of the profile
                 note that ttot is not 100% exact if pdot/pddot are
                 nonzero
       npts    : total number of rate points in each bin of the
                 profile, or total number of events in each bin.
       statquant: a 2d array, quant(0,*) contains the 1st, quant(1,*)
                 the 2nd, and quant(2,*) the 3rd quantile for each
                 pulse point; only for lightcurve data

      * it is assumed that the period/frequency are only changing
        slowly, such that it can be assumed that during one gti
        interval the period is close to constant. For all relevant
        astronomical objects this seems to be the case. In other
        words, when the GTI is known, then ttot (the exposure time of
        each phase bin) is computed using the period as determined
        for the middle of the GTI interval as the correct period.
        Note that the phase of each phase bin is determined correctly
        (using getphase)

       nbins=128
       period=1.7
       pfold,time,counts,profile,283.,nbins=nbins,period=period
       phase=findgen(nbins)/(nbins-1)
       plot,phase,profile

 $Log: pfold.pro,v $
 Revision 1.16  2006/02/14 17:54:47  wilms
 now also works in the case that the period is an integer variable
 Revision 1.15  2005/05/14 20:55:39  wilms
 added mjd keyword
 Revision 1.14  2004/11/22 07:59:45  wilms
 further improvement on handling of phase bins with no exposure (now
 also returns NaN for binned data).
 Revision 1.13  2004/11/21 19:10:10  kuster
 - fixed bug for phase bins with zero integration time (event list mode)
 - change print to message in chatty mode
 Revision 1.12  2004/11/01 21:05:57  wilms
 timezero warning only if chatty is set
 Revision 1.11  2004/09/13 16:02:56  wilms
 cosmetic changes only
 Revision 1.10  2004/09/07 17:26:50  wilms
 * added options to fold on frequency instead of period
 * added ability to have time dependent period (pdot and pddot and
   nudot, nuddot options)
 * switched phase handling over to getphase
 Revision 1.9  2004/09/06 20:54:04  wilms
 added treatment of GTIs and also greatly improved general treatment of
 gaps for the case of lightcurves.
 Revision 1.8  2004/05/24 18:03:30  wilms
 simpler computation of npts for events
 Revision 1.7  2003/06/30 10:26:25  wilms
 complete rewrite (Ljuba/JW), now also allows event lists
       Version 1.0: Derived from foldlc, Joern Wilms, 1998/05/14
       Version 1.1: J.W., 1998/08/09, added quantile keyword
       Version 2.0: J.W., 1999/08/04:
          * now use the histogram function for determining the
            countrates contributing to each phase bin
            (speed improvement roughly a factor of 20%)
          * compute width of time bins only if desired
            (slight speed improvement)
       CVS Version 1.2: JW/PR, 2001.07.20
          code now produces exact results in case time-time0 is negative
       CVS Version 1.3: MK, 2001.10.18
          added keyword tolerance
       Version 1.4: JW, 2002.02.12
          repaired tolerance keyword. now calls with tolerance eq
          0. are possible
       Version 1.5: JW/SF, 2002.08.15
          correction of code in the example
       Version 1.6: JW: CHANGE TO CVS LOGGING

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