% @(#)sinefitsa.hlq	19.1 (ESO-IPG) 02/25/03 13:32:45
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 
%.COPYRIGHT (c) 1992 European Southern Observatory & Copernicus Astron. Center%.IDENT     tsasin.tex
%.AUTHOR    Alex Schwarzenberg-Czerny, ESO & Copernicus Astronomical Center 
%.KEYWORD   MIDAS, time analysis, SINEFIT/TSA
%.LANGUAGE  MIDAS
%.PURPOSE   Fit sine (Fourier) series, return residuals 
%.VERSION   0.0               June 1992
%.RETURNS   None  
%.ENVIRON   TSA context
%-----------------------------------------------------------------------------
%
%   Command parameters
%
\se
SECTION./TSA
\es\co
SINEFIT/TSA                         15-SEPT-1992 A.Schwarzenberg-Czerny
\oc\su
SINEFIT/TSA intab outtab freque order iter
	fit sine (Fourier) series, subtract it from input and return residuals
\us\pu
Purpose: 
          Fit sine (Fourier) series, optionally by nonlinear iterations with 
          correction of frequency f. The series has the form:
          S(t)=C(0)+C(1)*sin(Ph)+C(2)*cos(Ph)+...C(2*[order])*cos([order]*Ph),
          where phase Ph=2*pi*f*t. The fitted values of the coefficients C(i) 
          and their errors are displayed in the order of appearance in the formula.
          The last fitted entry is frequency. The frequency is not adjusted in the
          very first iteration so carries 0 nominal error. A line with
          details of the fitted ephemeris follows. The phase at m.t. stays
          for the phase at mean time. The frequency and this phase are
          orthogonal (principal or uncorrelated) results of the fit and thus are
          recommended for use. 

          The command constitutes also a sort of filter: takes observations
          from the input column :VALUE and returns them prewhitened (i.e. detrended)
          with the fitted series again in output :VALUE.
          So it can be used to perform a CLEAN analysis by removing consecutive
          frequencies manually step by step. Alternatively it can be used to 
          remove trends from data. The command works in two modes: start iterations or
          continue iterations, depending on parameter iter.
\up\sy
Syntax: 
          SINEFIT/TSA intab outima freque order iter
\ys\pa
          intab  = name of input table containing time series in columns
                   :TIME and :VALUE in DOUBLE PRECISION. For numerical reasons 
                   it is advisable to subtract mean from :VALUE on start. 
                   Note that the same value has to be added to the result 
                   constant (0 frequency) coefficient.
\ap\pa
          outab  = name of similar output table containing :TIME, original
                   values in :ORIG_VALUE, fitted values in :FIT and residuals 
                   from the fit in :VALUE. Outab and intab could be the same.
\ap\pa
          freque = base frequency, default and continuation value is STARTTSA.
                   Since this routine is not intended for general frequency 
                   search but is intended for refining frequencies as well as 
                   all sorts of strange detrending and filtering applications,
                   it remains user  responsibility to make sure that his 
                   initial frequency guess and  its final fit are plausible.
                   Use SCARGLE/TSA, AOV/TSA or POWER/TSA 
                   with zoomed frequency scale for that purpose.
\ap\pa
          order  = order of Fourier series (0 - only constant, 1 - pure sine
                   of base frequency, 2 - base and 1st harmonic, etc. ...
                   Default and continuation value is ORDERTSA
\ap\pa
          iter   = number of iterations to be performed. If your
                   input and output file names differ you can use the same 
                   command with frequency replaced by ? to continue the 
                   the iterations.
                   For experts only: use iter < 0 if you wish to continue 
                   abs(iter) iterations stepwise in exactly the same manner
                   as they would occurre in a single SINEFIT/TSA call.
                   In the latter case be sure that none of keywords OUTROOT,
                   STARTTSA and ORDERTSA were changed between consecutive 
                   iterations by other MIDAS commands. In practice no other TSA
                   commands nor MIDAS commands changing OUTPUTD can be 
                   used between negative iterations. Default +1. 
                 
\ap\sa
See also:
          none
\as\no
Note:
          The coefficients C(i) of the fitted series as defined above are returned
          in OUTPUTD(i). 
          
\on\exs
Examples: 
\ex
          SINEFIT/TSA LCURVE RESID 0.205 1
          will remove a given frequency from the data
\xe\ex
          SINEFIT/TSA RESID RESID 0.333
          will prewhiten with another frequency
\xe\ex
          SINEFIT/TSA LCURVE RESID 0.205 2 4
          will fit frequency, using base and 1st harmonic Fourier series\\
\\
          If necessary, you can continue 3 more iterations with
\xe\ex
          SINEFIT/TSA ? ? ? ? 3
          continues 3 more iterations. The result will differ slightly from
          SINEFIT/TSA LCURVE RESID 0.205 2 7
\xe\sxe
