Build a base contrast mask

contrast_mask() is the extension point for new contrast types: it returns a base contrast matrix with one row per base condition (no basis expansion) and one column per contrast column. The unified driver contrast_from_mask() handles basis expansion, basis filtering and packaging into a contrast object compatible with contrast_weights.event_model().

Usage

contrast_mask(x, term, ...)

Arguments

x

A contrast_spec object.

term

An event_term against which the mask is computed.

...

Additional arguments passed to methods.

Value

A list with elements:

• weights : numeric matrix, n_base_conditions x n_contrast_cols, row names = base condition names.

• condnames : character vector of base condition names.

Details

To register a custom contrast type:

1. Define a constructor that produces a list with class c("my_spec", "contrast_spec", "list").

2. Implement contrast_mask.my_spec() returning the base weights.

3. Implement contrast_weights.my_spec() as a one-liner:

   contrast_weights.my_spec <- function(x, term, ...) {
     contrast_from_mask(contrast_mask(x, term, ...), x, term)
   }

The built-in spec classes (pair_contrast_spec, oneway_contrast_spec, poly_contrast_spec, ...) implement contrast_weights() directly, so they do not require contrast_mask() methods.

Examples

term <- event_term(
  list(condition = factor(c("A", "B"))),
  onsets = c(0, 2),
  blockids = c(1, 1)
)
spec <- structure(
  list(name = "A-B"),
  class = c("example_contrast_spec", "contrast_spec", "list")
)
contrast_mask.example_contrast_spec <- function(x, term, ...) {
  condition_names <- conditions(term, drop.empty = FALSE)
  weights <- matrix(
    c(1, -1), ncol = 1,
    dimnames = list(condition_names, x$name)
  )
  list(weights = weights, condnames = condition_names)
}
contrast_mask(spec, term)
#> $weights
#>             A-B
#> condition.A   1
#> condition.B  -1
#> 
#> $condnames
#> [1] "condition.A" "condition.B"
#>