In the context of this function, a “contrast” means a linear combination of factor levels (regardless of the dummy coefficients that are used to code those levels in fitted models). For a factor f with three levels f1, f2, f3, this could be a single level (e.g. f ~ f1), a “pairwise” contrast (e.g. f ~ f1 - f2), an average (e.g. f ~ (f1 + f2 + f3) / 3), or any other linear combination. Such arithmetic operations are usually applied to the values of a dependent variable, conditioned to the value of the represented factor, but those symbolic representations, as if the levels of the factors were themselves combined, are useful abstractions that may come in handy to define hypotheses about the effects of the factor.
This function takes one or more formulas of that type, and returns matrices of the linear coefficients that define such contrasts. For the previous examples, it would return the column matrices list(f=matrix(c(f1=1, f2=0, f3=0))), list(f=matrix(c(f1=1, f2=-1, f3=0))), and list(f=matrix(c(f1=0.333, f2=-0.333, f3=0.333))), respectively. The factors must be defined in the data frame, list, or environment given in data, with the name provided in the right hand side of the formulas. By default this is the parent.frame, which in normal interactive use is the global environment.
The contrast matrices are returned in a named list, where the names are the represented factors, as required by the arguments levels and custom of the functions testFactors and testInteractions, respectively. When more than one formula is given for the same factor, all the corresponding columns of coefficients are bound into a single matrix.
Other ways of representing contrasts, allowed by testFactors and testInteractions, can also be mixed with the formulas as input arguments. Such alternative contrast definitions are just appended without changes in the returned list, after the matrices created from the formulas. (Notice that if other coefficient vectors or matrices are explicitly entered, these will not be combined with the ones calculated from formulas.)
In case of having the contrast definitions stored in a list, that list can be entered as the argument contrast.definitions. This option is recommended if the contrast definitions are mixed with named elements which could create a conflict with data, normalize, or contrast.definitions itself (although this is unlikely to happen specially if all the definitions are given as formulas). In any event, only one alternative of entering the definitions is allowed. If contrast.definitions is given, all the other definitions are ignored with a warning.