ADDSINE (Jan95)                ftools.xte                ADDSINE (Jan95)



NAME
    addsine  --  adds a sine curve (or a user-defined periodic function)
    to an existing timing FITS file.
    
    
USAGE
    addsine infile outfile intervals period perunit amplitude  zerophase
    noise
    
    
DESCRIPTION
    This  task  adds  a sine curve to an existing light curve.  The user
    specifies the period, amplitude, and  time  of  zero  phase  of  the
    sinusoid.  The user may also choose whether noise is put on the sine
    curve.  The user may specify  a  user-defined  pulse  shape  to  add
    instead of a sinusoidal variation.
    
    
PARAMETERS
    
    infile [file name]
        The  name of the input FITS file.  A file conforming to the OGIP
        Timing FITS File format is expected.  If no time column  exists,
        the  routine  constructs the times from the TIMEZERO and TIMEDEL
        keywords.  If a time column is  present,  then  the  sine  curve
        will  be added to every time bin falling within the desired time
        intervals.
    
    outfile [file name]
        The name of the output FITS  file.   The  format  of  this  file
        follows  the  OGIP Timing FITS File Format.  The header keywords
        from the input file are copied to the output file.
    
    intervals [string]
        The time  interval(s)  within  which  to  add  the  sine  curve,
        expressed  in  MJD.   These   intervals  are  listed as pairs of
        start and stop times.  To default to all the data in  the  file,
        use  -.   To  default an interval to the beginning or end of the
        data, omit the interval's start or stop time, e.g.  -35632.0  or
        32752.0-  .   Up to 15 time intervals may be specified.  Results
        from different intervals are output to different extensions.
    
    period [double precision real]
        The period of the sine curve, in  units  given  by  the  perunit
        parameter
    
    perunit [string]
        The units for the period, either in seconds (S) or days (D)
    
    amplitude  [real*4]
        The  amplitude  of  the  sine curve, using the same units as the
        input file.
    
    zerophase  [double precision real]
        The time of zero phase for the sinusoid, in MJD
    
    noise  [integer]
        The noise option to be used  in  producing  the  sinusoid.   The
        integer  values have the following meanings:  0 = no noise;  1 =
        Poisson noise;   2 = Gaussian  noise.   The  Poisson  statistics
        are  governed by the mean intensity as expressed in counts.  (If
        the units on the intensity column is COUNT/S, the conversion  to
        COUNTS  is  done internally using the sample size.)  If Gaussian
        noise is specified, the sigma for the Gaussian  distribution  is
        specified  using  the  sigma  parameter.  If the input file does
        not have an error column, ADDSINE currently  assumes  the  input
        data  is  noiseless.   Adding a noisy sine curve to a noise-less
        input will result in the creation of  an  ERROR  column  in  the
        ouput  FITS  file.   If Poisson noise is specified, the error is
        computed using Poisson statistics on the total counts  (input  +
        sine).   If Gaussian noise is specified, the sigma inputted here
        is applied only to the sine curve.
    
    (sigma) [real*4] 
        The sigma to be used for Gaussian noise.
    
    (profile) [string]
        Name of an optional file which  contains  a  user-defined  pulse
        shape.   The  file is a two column ascii file in which the first
        column is the phase and the second column is  the  corresponding
        normalized  intensity.  Up to 50 phase bins may be specified.  A
        linear interpolation is used  to  derive  intensity  values  for
        phases not explicitly given.
    
    (seed = -4597) [integer]
        The  initial  seed  for  the  random number generator.  Not that
        this must be a negative number.
    
    (timename = TIME) [string]
        Name of the time column to be used.  If no time  column  exists,
        then  times will be constructed based on the time bin size given
        in the header.
    
    (ratename = RATE) [string]
        Name of the intensity column to be added to.   If  ratename  not
        found in the input file, execution ceases.
    
    (errname = ERROR) [string]
        Name  of  the  column  containing the uncertainty values for the
        intensity column.  If errname  not  found,  the  input  data  is
        assumed to be noiseless.
    
    (copyprime = yes) [boolean]
        Whether  to  copy  the primary header and array to  the  output.
        (The "no" option is Not supported at this time.)
    
    (copyall = no) [boolean]
        If true, all other extensions in the input file will  be  copied
        to  the  output (only in effect when 1 input file is specified).
        However, this has not yet been implemented for ADDSINE.
    
    
EXAMPLES
    1.  Add a sine curve to all data in an input file.  The sine curve has
    a period of 2.53 s, an amplitude
    of 10 (in the units of the input file), and a time of zero phase of
    49000.  Poisson noise is added to the sine curve.
    
    addsine infile=test.lc outfile=sinetest.lc intervals=- period=2.53 perunit=s amplitude=10 zerophase=49000. noise=1 
    
    2.  Add a sine curve to the latter part of a data file.  The sine
    curve has a period of 0.367 d, an amplitude of 10 (in units of the
    input file), and a time of zero phase of 49000.  Gaussian noise is
    added, with a sigma of 3.
    
    addsine infile=test2.lc outfile=sinetest2.lc intervals=49000.4-
    period=0.367 perunit=d amplitude=10 zerophase=49000. noise=2 sigma=3.
    
    
NOTES:
    
    
BUGS
    
    ADDSINE_V3.3
    
    Please report problems to xtehelp@athena.gsfc.nasa.gov.
    
    
SEE ALSO
    fakelc  addshots