NAG Library Routine Document
g04daf (contrasts)
1
Purpose
g04daf computes sum of squares for a userdefined contrast between means.
2
Specification
Fortran Interface
Subroutine g04daf ( 
nt, tmean, irep, rms, rdf, nc, ct, ldct, est, tabl, ldtabl, tol, usetx, tx, ifail) 
Integer, Intent (In)  ::  nt, irep(nt), nc, ldct, ldtabl  Integer, Intent (Inout)  ::  ifail  Real (Kind=nag_wp), Intent (In)  ::  tmean(nt), rms, rdf, ct(ldct,nc), tol, tx(nt)  Real (Kind=nag_wp), Intent (Inout)  ::  tabl(ldtabl,*)  Real (Kind=nag_wp), Intent (Out)  ::  est(nc)  Logical, Intent (In)  ::  usetx 

C Header Interface
#include nagmk26.h
void 
g04daf_ (const Integer *nt, const double tmean[], const Integer irep[], const double *rms, const double *rdf, const Integer *nc, const double ct[], const Integer *ldct, double est[], double tabl[], const Integer *ldtabl, const double *tol, const logical *usetx, const double tx[], Integer *ifail) 

3
Description
In the analysis of designed experiments the first stage is to compute the basic analysis of variance table, the estimate of the error variance (the residual or error mean square), ${\hat{\sigma}}^{2}$, and the (variance ratio) $F$statistic for the $t$ treatments. If this $F$test is significant then the second stage of the analysis is to explore which treatments are significantly different.
If there is a structure to the treatments then this may lead to hypotheses that can be defined before the analysis and tested using linear contrasts. For example, if the treatments were three different fixed temperatures, say
$18$,
$20$ and
$22$, and an uncontrolled temperature (denoted by
$\mathrm{N}$) then the following contrasts might be of interest.
The first represents the average difference between the controlled temperatures and the uncontrolled temperature. The second represents the linear effect of an increasing fixed temperature.
For a randomized complete block design or a completely randomized design, let the treatment means be
${\hat{\tau}}_{i}$,
$i=1,2,\dots ,t$, and let the
$j$th contrast be defined by
${\lambda}_{ij}$,
$i=1,2,\dots ,t$, then the estimate of the contrast is simply:
and the sum of squares for the contrast is:
where
${n}_{i}$ is the number of observations for the
$i$th treatment. Such a contrast has one degree of freedom so that the appropriate
$F$statistic is
${\mathrm{SS}}_{j}/{\hat{\sigma}}^{2}$.
The two contrasts ${\lambda}_{ij}$ and ${\lambda}_{i{j}^{\prime}}$ are orthogonal if $\sum _{i=1}^{t}}{\lambda}_{ij}{\lambda}_{i{j}^{\prime}}=0$ and the contrast ${\lambda}_{ij}$ is orthogonal to the overall mean if $\sum _{i=1}^{t}}{\lambda}_{ij}=0$. In practice these sums will be tested against a small quantity, $\epsilon $. If each of a set of contrasts is orthogonal to the mean and they are all mutually orthogonal then the contrasts provide a partition of the treatment sum of squares into independent components. Hence the resulting $F$tests are independent.
If the treatments come from a design in which treatments are not orthogonal to blocks then the sum of squares for a contrast is given by:
where
with
${\tau}_{\mathit{i}}^{*}$, for
$\mathit{i}=1,2,\dots ,t$, being adjusted treatment means computed by first eliminating blocks then computing the treatment means from the block adjusted observations without taking into account the nonorthogonality between treatments and blocks. For further details see
John (1987).
4
References
Cochran W G and Cox G M (1957) Experimental Designs Wiley
John J A (1987) Cyclic Designs Chapman and Hall
Winer B J (1970) Statistical Principles in Experimental Design McGraw–Hill
5
Arguments
 1: $\mathbf{nt}$ – IntegerInput

On entry: $t$, the number of treatment means.
Constraint:
${\mathbf{nt}}\ge 2$.
 2: $\mathbf{tmean}\left({\mathbf{nt}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the treatment means,
${\hat{\tau}}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,t$.
 3: $\mathbf{irep}\left({\mathbf{nt}}\right)$ – Integer arrayInput

On entry: the replication for each treatment mean,
${n}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,t$.
 4: $\mathbf{rms}$ – Real (Kind=nag_wp)Input

On entry: the residual mean square, ${\hat{\sigma}}^{2}$.
Constraint:
${\mathbf{rms}}>0.0$.
 5: $\mathbf{rdf}$ – Real (Kind=nag_wp)Input

On entry: the residual degrees of freedom.
Constraint:
${\mathbf{rdf}}\ge 1.0$.
 6: $\mathbf{nc}$ – IntegerInput

On entry: the number of contrasts.
Constraint:
${\mathbf{nc}}\ge 1$.
 7: $\mathbf{ct}\left({\mathbf{ldct}},{\mathbf{nc}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the columns of
ct must contain the
nc contrasts, that is
${\mathbf{ct}}\left(\mathit{i},\mathit{j}\right)$ must contain
${\lambda}_{\mathit{i}\mathit{j}}$, for
$\mathit{i}=1,2,\dots ,t$ and
$\mathit{j}=1,2,\dots ,{\mathbf{nc}}$.
 8: $\mathbf{ldct}$ – IntegerInput

On entry: the first dimension of the array
ct as declared in the (sub)program from which
g04daf is called.
Constraint:
${\mathbf{ldct}}\ge {\mathbf{nt}}$.
 9: $\mathbf{est}\left({\mathbf{nc}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the estimates of the contrast,
${\Lambda}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,{\mathbf{nc}}$.
 10: $\mathbf{tabl}\left({\mathbf{ldtabl}},*\right)$ – Real (Kind=nag_wp) arrayInput/Output

Note: the second dimension of the array
tabl
must be at least
$5$.
On entry: the elements of
tabl that are not referenced as described below remain unchanged.
On exit: the rows of the analysis of variance table for the contrasts. For each row column 1 contains the degrees of freedom, column 2 contains the sum of squares, column 3 contains the mean square, column 4 the $F$statistic and column 5 the significance level for the contrast. Note that the degrees of freedom are always one and so the mean square equals the sum of squares.
 11: $\mathbf{ldtabl}$ – IntegerInput

On entry: the first dimension of the array
tabl as declared in the (sub)program from which
g04daf is called.
Constraint:
${\mathbf{ldtabl}}\ge {\mathbf{nc}}$.
 12: $\mathbf{tol}$ – Real (Kind=nag_wp)Input

On entry: the tolerance, $\epsilon $ used to check if the contrasts are orthogonal and if they are orthogonal to the mean. If ${\mathbf{tol}}\le 0.0$ the value machine precision is used.
 13: $\mathbf{usetx}$ – LogicalInput

On entry: if
${\mathbf{usetx}}=\mathrm{.TRUE.}$ the means
${\tau}_{i}^{*}$ are provided in
tx and the formula
(2) is used instead of formula
(1).
If
${\mathbf{usetx}}=\mathrm{.FALSE.}$ formula
(1) is used and
tx is not referenced.
 14: $\mathbf{tx}\left({\mathbf{nt}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: if
${\mathbf{usetx}}=\mathrm{.TRUE.}$ tx must contain the means
${\tau}_{\mathit{i}}^{*}$, for
$\mathit{i}=1,2,\dots ,t$.
 15: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{ or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit, the recommended value is
$1$.
When the value $\mathbf{1}\text{ or}1$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Note: g04daf may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry,  ${\mathbf{nc}}<1$, 
or  ${\mathbf{nt}}<2$, 
or  ${\mathbf{ldct}}<{\mathbf{nt}}$, 
or  ${\mathbf{ldtabl}}<{\mathbf{nc}}$, 
or  ${\mathbf{rms}}\le 0.0$, 
or  ${\mathbf{rdf}}<1.0$. 
 ${\mathbf{ifail}}=2$

On entry,  a contrast is not orthogonal to the mean, 
or  at least two contrasts are not orthogonal. 
If ${\mathbf{ifail}}={\mathbf{2}}$ full results are returned but they should be interpreted with care.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
The computations are stable.
8
Parallelism and Performance
g04daf is not threaded in any implementation.
If the treatments have a factorial structure
g04caf should be used and if the treatments have no structure the means can be compared using
g04dbf.
10
Example
The data is from a completely randomized experiment on potato scab with seven treatments representing amounts of sulphur applied, whether the application was in spring or autumn and a control treatment. The oneway anova is computed using
g02bbf. Two contrasts are analysed, one comparing the control with use of sulphur, the other comparing spring with autumn application.
10.1
Program Text
Program Text (g04dafe.f90)
10.2
Program Data
Program Data (g04dafe.d)
10.3
Program Results
Program Results (g04dafe.r)