Studying periodic and aperiodic variability

• programs require on input XAS time profiles as generated by the accumulation programs
• most programs produce on output one or more files, either in XAS ASCII or preferably XAS binary table format.
• programs are controlled by a particular set of XAS environment variables

• discrete Fourier transform (on non-equispaced data) according to Deeming

• discrete Fourier transform (on non-equispaced data) according to Scargle

• discrete Fourier transform (on non-equispaced data) according to Ferraz-Mello

• fast Fourier transform (requires equispaced data)

• shifted/scaled spectral window according to Deeming (obsolescent)

• overlay plotting of shifted/scaled spectral window (new, with auto-computation)

• folding period search

• folding at fixed period

• phase folding of a light curve at fixed period

• plotting of power spectra or periodograms

• overlay of reference period

• plotting of folded light curves

• Fourier transform (Deeming method)

  The program produces a power spectrum of a time series (and optionally the spectral window) in an user selected frequency range, according to the method of Deeming [2] for non-equispaced time series.

  fourdeem [tfile {band} ffile fp1 fp2 fpn

  The frequency range fp1-fp2 can be divided into linear steps of size fpn or in fpn logarithmically spaced bins, according to the spacing environment variable.
  Other environment variables controlling this program are described below

• Fourier transform (Scargle method)

  The program produces a power spectrum of a time series (and optionally auxiliary info) in an user selected frequency range, according to the method of Scargle [3] for non-equispaced time series (this method uses a different normalization of the power spectrum, while the shape is unchanged).

  fourscar [tfile {band} ffile fp1 fp2 fpn

  Arguments and environment variable usage is as for the Deeming program

• Fourier transform (Ferraz-Mello method)

  The program produces a power spectrum of a time series (and optionally auxiliary info) in an user selected frequency range, according to the method of Ferraz-Mello [4] for non-equispaced time series (DCDTF, date-compensated discrete Fourier transform).

  fourferr [tfile {band} ffile fp1 fp2 fpn

  Arguments and environment variable usage is as for the Deeming program. In addition, since this method allows an easy computation of the significance of the peaks from the power, variable poweraxis allows to replace the arbitrary power with such probability.

• Fast Fourier transform (FFT)

  The program produces a power spectrum of a time series (which must be equispaced and have a power-of-2 number of bins N) in a fixed frequency range starting at 0, with N/2 linear frequency steps (the step is equal to the inverse of the duration of the timeseries).

  fourfft [tfile {band} ffile

  The program does not check at all that the data are equispaced, and it does not use the bin times at all (but just the binsize). If the number of bins is not a power of 2, only the (first) closest lower power of 2 bins ara used.
  The resulting power spectrum is normalized according to Leahy [5], i.e. a pure Poisson noise source will have a mean power of 2 and a variance of 4.

• Shifting and scaling a spectral window

  This program is not recommended for use. Use plotwin instead !
  The program takes a Fourier spectrum ffile produced by the Deeming program (preferably with linear spacing), and copies the spectral window into file fofile, shifting the spectral window such that the peak (origin) coincides with an user defined frequency pkfreq, and scaling it by an user defined height pkpowr. The window is replicated left and right in the frequency range f1-f2 with the original spacing.

  showin [ffile pkfreq pkpowr f1 f2 fofile

  The resulting file (in form of a Fourier spectrum containing also dummy columns) can then be overplotted onto a Fourier spectrum using command fplot. This is superseded by the next command.

• Overlay plotting of spectral window

  This program is used to compute and overplot the spectral window (computed as in the Deeming program), shifting it such that the peak (origin) coincides with an user defined frequency pkfreq, and scaling it by an user defined height pkpowr. The window is replicated left and right in the frequency range f1-f2 with nstep linear steps.

  plotwin [ {pkfreq pkpowr|CURSOR} {f1 f2|CURSOR} nstep

  Usually the peak position, height and extrema are given graphically with the mouse (CURSOR case). In all cases a Fourier spectrum shall be displayed by the graphics server. The program will retrieve the name of the associated time profile via XAS environment.

• Folding search

  This program performs the traditional period search by folding a light curve repeatedly at different periods (in range p1-p2 with step pstep). The folding is done on nphbin phase bins. The folded light curve is tested against the hypothesis that the source is constant via a chi-square test.

  foldsearch [tfile {band} ffiles p1 p2 pstep nphbin

  The program produces two output files. A chisquare vs period periodogram ffiles.chisquare and a folded light curve ffiles.folded (folded at the presumed "best" period, i.e. the highest chi-square)

• Folding a light curve

  This program folds a light curve at a fixed period on nphbin phase bins, and produces an output file ffiles.folded. Two identical cycles are repeated (phase range 0.0-2.0).

  folding [tfile {band} ffile period  nphbin

• Inserting phases in a light curve

  The purpose of this procedure is to replace the times in a light curve with the corresponding phases for an user specified period. Phase zero is assumed to correspond to the first time bin in the light curve. This can be done using the following shell/IDL procedure :
  • copy tfile.time ffile.folded
  • idl
    • xasread,'ffile.folded',a
    • p=period
    • phi= (a.data.time-a.data(0).time) mod p
    • phi=phi/p
    • cyc=floor((a.data.time-a.data(0).time)/p)
    • phi=phi+cyc
    • a.data.time=phi
    • a.ttype1='PHASE'
    • a.binsize=a.binsize/p
    • xaswrite,'ffile.folded',a
    • exit

• Plotting power spectra or periodograms

  Power spectra and chi-square periodograms can be plotted using the standard XAS graphics (and associated environment variables). Provisionally the display and overtrace commands with a fourier arguments are not supported, and one must explicitly use the forms :
  • fplot [ ffile
    defaults to a .fourier spectrum
  • fplot [ ffile.fourier
    fully equivalent to the above
  • fplot [ ffile.chisquare
    mandatory for a periodogram
  • xasset overwrite y ; fplot [ ffile[.type]
    for overplotting of any type of file

  Note also that one can choose whether to plot versus frequency (customary for power spectra) or versus period (customary for chisquare periodograms) for both kind of files (since they contain both) using the freqaxis variable.

  Caveat!When plotting periodograms (vs frequency) the automatic setting of x-axis extrema, and the histogram mode plotting may be confused by the fact that data are present in increasing period order. Better specify xaxis extrema manually, and using datastyle Solid.

• Plotting a reference period

  A silly program to overplot on an existing Fourier spectrum or periodogram a marker at a given period and at n of its harmonics (P, P/2 ... P/n).

  harmogrid [n {period|CURSOR} 

  The period is always specified as such, in seconds, even if the plot on the screen is vs frequency. It might however be specified graphically with the mouse.

• Plotting folded light curves

  Folded light curves can be plotted with the standard display and overtrace commands, provided one uses the full specification, e.g.

  display time [ ffile.folded

  The time profile plotting program will recognise presence of phase on the X-axis, and ignore current timeaxis settings.

Special file formats

• Fourier spectra proper (of type .fourier) produced by the Fourier programs. They have 5 or 6 columns (the 6-th column is included only if the writeaux environment variable is enabled) :
  1. frequency (in Hz) at the centre of each bin
  2. half width of frequency bin (in Hz)
  3. period (in s) at the centre of each bin
  4. half width of period bin (in s)
  5. power spectrum (in arbitrary units) or associated probability (only for the Ferraz-Mello method and if poweraxis is set to Significance)
  6. auxiliary information, different according to program. This can be a multidimensional column, which is not handled by all XAS utilities (but can be accessed via IDL for debug purposes)
     • in the Deeming case, it contains the spectral window
     • in the Scargle case, it contains the sum-of-sines and cosines correcting terms
     • in the Ferraz-Mello case, it contains the c1, c2, a1 and a2 correcting terms

• Periodograms (of type .chisquare) produced by the folding search program. A variant of the above format where the last two columns change meaning :
  5. the chi-square
  6. the average constant value (cts/s) against which constancy is checked
  Note that these files are naturally ordered for increasing period. See caveats for plotting them.

• Folded light curves (of type .folded) are produced by folding programs. They include two identically repeated cycles (phase 0.0-1.0 and 1.0-2.0) of a folded light curve. The format is the same of the standard XAS time profiles where only 3 columns are used :
  1. phase replaces the time column (start phase of bin)
  2. the bin size is not present as a column, but as a header keyword
  3. the data value in cts/s
  4. its error

• Phase folded light curves (of any type, .folded is recommended) are produced by "manual" phase folding, i.e. manipulating a pre-existing time profile, and replacing the time column with a relative phase/cycle number w.r.t. the time of the first bin (i.e. a number from 0.0 to n.x where n is the cycle). The file preserves the number of columns of the input file.

Dedicated environment variables

• zerogap : controls if zero-content bins are treated as gaps
• expolimit : controls bin rejection based on exposure fraction
• spacing : linear or logarithmic spacing (power spectra)
• fourout : output in XAS or ASCII format
• writeaux : allow writing auxiliary info in XAS Fourier files
• poweraxis : power spectrum (Ferraz-Mello only) in arbitrary units or significance
• freqaxis : X axis in frequency or period (plotting programs)
• lastplot : used internally also to store light curve name associated to a Fourier file plotted

References