 
      CALL SEQUENCE...
       t2test  U1BAR VU1 V1BAR VV1 COV1 U2BAR VU2 V2BAR VV2 COV2 \ 
               DU DV AMP FVALUE KVALUE  DVALUE MASK INPUT OUTPUT \
                 [ -a VAL1 -lx VAL2 -ly VAL3 -kind VAL4 ]
 
 
      DESCRIPTION...
       t2test  - CONDUCT A TWO SAMPLE HOTELLING'S T**2 STATISTICAL TEST.
 
 
      AUTHORS - F. Zwiers and F. Majaess, November 06 1987.
      LAST REVISION: $Header: /data/armnraid1/cvs/RMNLIB/utils/rdiag/lspgm/t2test.ptn,v 4.14 2008/07/24 19:42:59 dugas Exp $
 
 
      PURPOSE - CONDUCT A TWO SAMPLE HOTELLING'S T**2 STATISTICAL TEST.
                UPON RETURN, THE PROGRAM REPORTS THE COMPUTED STATISTICAL
                VALUES IN FVALUE AS WELL AS RETURNING THE K-VALUE AND
                D-VALUE WHICH ARE RESPECTIVELY THE TRANSFORMED SIGNIFICANCE
                LEVELS AND THE ACCEPTANCE/REJECTION FLAG. ALSO RETURNED ARE
                THE DIFFERENCES EXPERIMENT-CONTROL OF THE TWO COMPONENTS IN
                DU AND DV AS WELL AS THE AMPLITUDE OF THE VECTOR DIFFERENCE
                IN AMP.
 
      NOTE - 1) TESTS ARE  NOT PERFORMED  WHEN ONE  OR  MORE  OF  THE
                "POOLED VARIANCES" AND/OR THE CORRELATION COEFFICIENT
                IS APPROXIMATELY EQUAL TO  THE  NOISE INDUCED  BY THE
                PACKING ALGORITHM.
             2) INTERPRETATION OF VU1, VV1,  VU2  AND  VV2  FILES  IS
                CONTROLED BY INPUT PARAMETER IVAR.
             3) MASK FILE NEED NOT BE SPECIFIED IN THE PROGRAM CALLING
                SEQUENCE. (SEE OUTPUT FILES SECTION BELOW).
 
 
      INPUT FILES...
 
       CONTROL DATASET STATISTICS FOR W1(U1,V1):
       =========================================
       U1BAR  = FIELDS OF MEANS OF THE 'U1-CONTROL' VARIABLE.
                SUM( U1(I) ) / N1, I=1,...,N1.
      (IF (IVAR.EQ.0) THEN
      (VU1    = THE VARIANCE OF U1. SUM( (U1(I)-U1BAR)**2 ) / N1, I=1,...,N1.
      (OTHERWISE,
      (VU1    = THE UNBIASED ESTIMATES OF THE STANDARD DEVIATIONS OF U1.
      (         SQRT( SUM( (U1(I)-U1BAR)**2 ) / (N1-1) ), I=1,...,N1.
       V1BAR  = SAME AS U1BAR EXCEPT FOR THE 'V1-CONTROL' VARIABLE.
       VV1    = SAME AS VU1   EXCEPT FOR THE 'V1-CONTROL' VARIABLE.
       COV1   = COVARIANCE OF THE CONTROL COMPONENTS.
                SUM( (U1(I)-U1BAR) * (V1(I)-V1BAR) ) / N1, I=1,...,N1.
 
       EXPERIMENT DATASET STATISTICS FOR W2(U2,V2):
       ============================================
       U2BAR  = FIELDS OF MEANS OF THE 'U2-EXPERIMENT' VARIABLE.
                SUM( U2(J) ) / N2, J=1,...,N2.
      (IF (IVAR.EQ.0) THEN
      (VU2    = THE VARIANCE OF U2. SUM( (U2(J)-U2BAR)**2 ) / N2, J=1,...,N2.
      (OTHERWISE,
      (VU2    = THE UNBIASED ESTIMATES OF THE STANDARD DEVIATIONS OF U2.
      (         SQRT( SUM( (U2(J)-U2BAR)**2 ) / (N2-1) ), J=1,...,N2.
       V2BAR  = SAME AS U2BAR EXCEPT FOR THE 'V2-EXPERIMENT' VARIABLE.
       VV2    = SAME AS VU2   EXCEPT FOR THE 'V2-EXPERIMENT' VARIABLE.
       COV2   = COVARIANCE OF THE EXPERIMENT COMPONENTS.
                SUM( (U2(J)-U2BAR) * (V2(J)-V2BAR) ) / N2, J=1,...,N2.
 
      OUTPUT FILES...
 
       DU     = FIELDS OF MEAN DIFFERENCES FOR THE FIRST COMPONENTS
                COMPUTED AS DU=U2BAR-U1BAR.
       DV     = FIELDS OF MEAN DIFFERENCES FOR THE SECOND COMPONENTS
                COMPUTED AS DV=V2BAR-V1BAR.
       AMP    = FIELDS OF THE AMPLITUDE OF THE MEAN DIFFERENCES
                COMPUTED AS AMP=SQRT(DU**2+DV**2).
       FVALUE = FIELDS OF 'F-VALUES' STANDARDIZED DIFFERENCES OF MEANS.
                USING N1,N2, DU,DV, VU1,VU2, COV1,COV2 AS DEFINED ABOVE,
                THIS FIELD IS COMPUTED AS FOLLOWS:
 
                  F     = FACT3*T22
 
                  FACT3 = (N1+N2-2-1)/(2*(N1+N2-2))
 
                  T22   = FACT2*SDIF/(1-ROP**2)
 
                  FACT2 = N1*N2/(N1+N2)
 
                  SDIF  = SU**2 - 2*ROP*SU*SV + SV**2
 
                  SU    = DU/S1P
 
                  SV    = DV/S2P
 
                  S1P   = SQRT( S1P2 )
 
                  S1P2  = FACT1*(N1*VU1+N2*VU2)
 
                  FACT1 = 1/(N1+N2-2)
 
                  S2P   = SQRT( S2P2 )
 
                  S2P2  = FACT1*(N1*VV1+N2*VV2)
 
                  ROP   = FACT1*(N1*COV1+N2*COV2)/(S1P*S2P)
 
                T22 IS THE TWO SAMPLE HOTELLING'S T**2 STATISTICAL VALUE.
       KVALUE = FIELDS OF 'K-VALUES' OF TRANSFORMED SIGNIFICANCE LEVELS.
                COMPUTED AS K IN:
 
                   P    = ALPHA/(5**(K-1))
 
                OR K    = LOG (ALPHA/P)+1
                             5
 
                WHICH INDICATES THAT THE OBSERVED STATISTIC IS
                SIGNIFICANT AT THE
 
                  ALPHA/(5**(K-1))
 
                SIGNIFICANCE LEVEL.
                THUS K=1 INDICATES THAT THE OBSERVED STATISTIC IS JUST
                SIGNIFICANT AT THE ALPHA SIGNIFICANCE LEVEL.
                IF PLOTTED WITH UNIT CONTOUR INTERVALS, SUCCESSIVE
                CONTOURS WILL ENCLOSE REGIONS WHERE LOCALLY IT IS
                FIVE TIMES AS UNLIKELY THAT VALUES OF THE OBSERVED
                STATISTICS ARE CONSISTENT WITH THE NULL HYPOTHESIS
                THAN IN REGIONS OUTSIDE THE NEXT LOWER CONTOUR.
       DVALUE = FIELDS OF 'D-VALUES' COMPUTED AS:
                           __
                          ! 0  IF THE NULL HYPOTHESIS IS ACCEPTED
                   D    = !
                          ! 1  IF THE NULL HYPOTHESIS IS REJECTED
                           --
       MASK   = FIELDS OF 'MASK-VALUES' COMPUTED AS:
                           __
                          ! 1  IF THE TEST WAS     CONDUCTED
                   MASK = !
                          ! 0  IF THE TEST WAS NOT CONDUCTED
                           --
 
                THE MASK FILE IS NOT RETURNED IF THE PROGRAM IS NOT
                CALLED WITH OUTPUT FILE MASK.
  
 
      INPUT PARAMETERS...
 
       ALPHA (a)    = THE SIGNIFICANCE LEVEL OF THE TEST.
       N1    (lx)   = THE NUMBER OF OBSERVATIONS IN THE CONTROL    DATA SET,
       N2    (ly)   = THE NUMBER OF OBSERVATIONS IN THE EXPERIMENT DATA SET.
                      THE ACTUAL VALUE USED ARE RATHER NX AND NY DEFINED AS
                      N1 = INT( AN1 ) AND  N2 = INT( AN2 ).
                      IF N1 >= 1 , N2 >= 1 AND N1+N2 > 3 THEN
                         N1 AND N2 FROM THE INPUT CARD ARE USED IN THE
                         COMPUTATION OF THE NUMBER OF DEGREES OF FREEDOM.
                      OTHERWISE,
                         THE N1 AND N2 VALUES NEEDED IN THE COMPUTATION ARE
                         OBTAINED FROM THE RECORD LABELS OR FROM THE IP3
                         DESCRIPTORS, DEPENDING ON THE FILE TYPE OF THE
                         U1BAR AND U2BAR FILES.
       IVAR  (kind) = A FLAG USED TO DETERMINE THE CONTENTS OF
                      VU1, VV1, VU2 AND VV2 FILES. THAT IS :
                      IF (IVAR.EQ.0) THEN
                         THE VU1, VV1, VU2 AND VV2 FILES CONTAIN THE VARIANCES
                         OF U1,  V1,  U2 AND  V2, RESPECTIVELY.
                      OTHERWISE,
                         VU1, VV1, VU2 AND VV2 FILES CONTAIN THE UNBIASED
                         ESTIMATES  OF THE   STANDARD   DEVIATIONS   OF
                         U1,  V1,  U2 AND  V2 RESPECTIVELY.
 
       READ(5,5010) ALPHA,AN1,AN2,IVAR
 5010  FORMAT(10X,E10.0,2F5.0,I5)
 
 
      EXAMPLE OF INPUT CARD...
 
 *T2TEST.      5.E-2  10.   5.    1
 
         0123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5         6         7
 
 
      EXIT CONDITIONS...
        0 NO PROBLEMS
 
      FATAL CONDITIONS...
        1 PREMATURE EOF ON STDIN
        2 PREMATURE EOF ON UNIT 11 AND/OR 16
        3 FIRST U1BAR AND U2BAR NOT THE SAME SIZE
        4 UNABLE TO READ FIRST U1BAR
        5 FOUND ILLEGAL N1 VALUE
        6 MISSING U2BAR ARRAY
        7 FOUND ILLEGAL N2 VALUE
        8 FOUND N1+N2 SMALLER OR EQUAL TO 3
        9 U1BAR AND/OR U2BAR NOT THE SAME SIZE AS FIRST U1BAR
       10 MISSING V1BAR ARRAY
       11 MISSING V2BAR ARRAY
       12 V1BAR AND/OR V2BAR NOT THE SAME SIZE AS FIRST U1BAR
       13 MISSING VU1 ARRAY
       14 VU1 NOT THE SAME SIZE AS U1BAR
       15 MISSING VU2 ARRAY
       16 VU2 NOT THE SAME SIZE AS U2BAR
       17 MISSING VV1 ARRAY
       18 VV1 NOT THE SAME SIZE AS U1BAR
       19 MISSING VV2 ARRAY
       20 VV2 NOT THE SAME SIZE AS U2BAR
       21 MISSING COV1 ARRAY
       22 COV1 NOT THE SAME SIZE AS U1BAR
       23 MISSING COV2 ARRAY
       24 COV2 NOT THE SAME SIZE AS U2BAR
 
      NON-FATAL CONDITIONS...
      101 VERY SMALL DENOMINATORS IN T**2 STATISTIC
      102 NAMES OF MEAN FIELDS DO NOT MATCH
 
