% @(#)delay_tsa.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:20:12
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 
%.COPYRIGHT (c)  1992     European Southern Observatory and Warsaw Observatory
%.IDENT     delay_tsa.hlq
%.AUTHOR    Alex Schwarzenberg-Czerny, ESO and Warsaw Observatory 
%.KEYWORD   MIDAS, help files, DELAY/TSA
%.LANGUAGE  LAYEX
%.PURPOSE   Compute chi2-time lag function
%.VERSION   0.0               June 1992
%.RETURNS   None  
%.ENVIRON   TSA context
%-----------------------------------------------------------------------------
\se
SECTION./TSA
\es\co
DELAY/TSA                                15-SEPT-1992 A. Schwarzenberg-Czerny
\oc\su
DELAY/TSA intab1 intab2 outtab start step nsteps [func,mode] [parm]
	compute chi2-time lag function
\us\pu
Purpose:
          Compute chi squared-time lag function for two time series.
          Minima of the chi2 indicate a possible physical association
          of two time series delayed by the corresponding lag.
          Individual measurements must be given with their variances.
          This command requires as input the autocovariance function 
          of the observations in analytical form. The algorithm is described
          in Ap.J. 385, 404. We use here the full algorithm (fitting
          both mean and difference at the same time), not the abrigated version
          fitting difference only. However, the results of the two versions
          do not differ significantly according to our and author's tests.
          Note that the whole method (not the code) is not yet 
          finally tested, thus use it with care.   
          Both algorithms involve inverting the observation covariance 
          matrix of size equal to the number of observations, for each time 
          lag, a quite time consuming operation and thus are slow.
\up\sy
Syntax:
          DELAY/TSA intab1 intab2 outtab start step nsteps func parm
\ys\pa
          intab1 = name of the table containing 1st set of observations with 
                   their variances. The table must contain columns :TIME :VALUE 
                   and :VAR in DOUBLE PRECISION. For numerical reasons it is 
                   advisable to subtract mean from :VALUE.
\ap\pa
          intab2 = same for 2nd time series.
\ap\pa
          outtab = name of the output table containing chi squared vs. time 
                   lag. 
\ap\pa
          start  = start value of time lag in the output table
\ap\pa
          step   = step of time lags in the table
\ap\pa
          nsteps = number of time lags in the table
\ap\pa
          func   = code for the analytical form of the autocorrelation
                   function of the observations. The user may choose
                   to use one of the predefined formulae (LIN,... IPO) 
                   suppling just parameters or to specify USi, where 
                   i=0,1,...9 and supply his/her own code for the function 
                   TSADELUR0.
                   The options are
\\{\tt
                   LIN     ACF(x) = A + B*x              (default)
\\
                   POL     ACF(x) = A + B*x +C*x**2 +.... (up to 12 coeff)
\\                 
                   POW     ACF(x) = A + B*x**C
\\
	           EXP     ACF(x) = A + B*exp(C*x)
\\
	           LOG     ACF(x) = A + B*LOG(C*x)
\\
                   IPO     ACF(x) = A + B/(x-x0) + C/(x-x0)**2 + ...
\\
                   where A=PARM(1), B=PARM(2),  ...., x0=PARM(12),
\\
                   except for IP0 where x0=PARM(1), A=PARM(2), ...
\\
                   URi     ACF(x) = user defined function TSADELURi
\\}
                   The head of the user supplied function must be the 
                   following:
\\{\tt
                   DOUBLE PRECISION FUNCTION TSADELURi(TLAG,PARM)
\\
                   DOUBLE PRECISION TLAG,PARM(12)
\\
                   .........................
\\}
                   The computed value of TSADELURi must depend only
                   on ABS(TLAG) and (optionaly) on PARM(1), PARM(2),.....
\ap\pa
          mode   = code for the algorithm to be used:
                   NOR - Both mean value and difference between the sets are 
                   determined by covariance matrix weighted least squares. 
                   This new improved algorithm is recommended (default). 

\ap\pa
          parm   = parameters for the function used
                   1) from command line: a,b,c,d,....(max.12)
                   2) from keyword: "K(iname)", e.g. KINPUTR
                   Default values are 0,1,0,0,... 
\ap\sa
See also:
          SHOW/TSA, COVAR/TSA, INTERPOLATE/TSA
\as\no
Note:
          The analytical form of ACF function can be created using 
          output of COVAR/TSA and MIDAS FIT package. 
\\      
          Since this command can take long time to execute, call it first 
          for just one time lag to get an estimate of the computation time. 
\\   
          A progress report is printed every one 10th of the total
          number of lags. It lists lag, std.dev. of the fit (its square constitutes
          chi**2 per degree of freedom), fitted mean and difference between 
          the samples, and their errors. 
\on\exs
Examples:
\ex
          DELAY/TSA DATA1 DATA2 CHI2 0. 1 1 EXP 0,1,-0.25
          gives you an estimate of the computation time just for 1 lag
\xe\ex
          DELAY/TSA DATA1 DATA2 CHI2 ? ? 200 UR7 KINPUTR
          computes the function for 200 lags. The parameters are the same than
          before (0,1,-0.25) and the command  uses the user defined function
\\{\tt
          DOUBLE PRECISION FUNCTION TSADELUR7(TLAG,PARM)
\\
          DOUBLE PRECISION TLAG,PARM(12)
\\
          TSADELUR7=PARM(1)+PARM(2)*EXP(PARM(3)*ABS(TLAG))
\\
          END
\\}
          The results should be the same as before.
\xe\sxe