Purpose

When working with factorial experimental designs (e.g. two conditions crossed with three time points), specifying all the relevant contrasts by hand is tedious and error-prone. The generate_contrasts family of functions in prolfqua automates this by generating contrast specifications from factor levels. These contrast strings can then be passed directly to the Contrasts class for statistical testing.

This vignette demonstrates how to:

• Generate main effect, level-specific, and interaction contrasts for a two-factor design
• Use annotation_add_contrasts to produce a combined annotation and contrast table ready for analysis

Group labelling convention

All contrast generation functions assume that the group levels in the fitted model follow the naming convention G_<primary>_<secondary>, which is produced by group_label():

library(prolfqua)

group_label("MI", "T0")

## [1] "G_MI_T0"

group_label("MINOCA", "T300")

## [1] "G_MINOCA_T300"

This means that before fitting a model, the data must contain a grouping column with levels in this format. The annotation_add_contrasts function creates such a column automatically using tidyr::unite.

Building contrasts step by step

Consider a two-factor design with disease type (MI, MINOCA) and time point (T0, T150, T300):

primary_levels <- c("MI", "MINOCA")
secondary_levels <- c("T0", "T150", "T300")

me <- main_effect_contrasts(primary_levels, secondary_levels)
data.frame(ContrastName = names(me), Contrast = unlist(me))

##              ContrastName
## MINOCA_vs_MI MINOCA_vs_MI
##                                                                                           Contrast
## MINOCA_vs_MI (G_MINOCA_T0 + G_MINOCA_T150 + G_MINOCA_T300)/3 - (G_MI_T0 + G_MI_T150 + G_MI_T300)/3

me2 <- main_effect_contrasts(secondary_levels, primary_levels)
data.frame(ContrastName = names(me2), Contrast = unlist(me2))

##              ContrastName
## T150_vs_T0     T150_vs_T0
## T300_vs_T0     T300_vs_T0
## T300_vs_T150 T300_vs_T150
##                                                                   Contrast
## T150_vs_T0       (G_T150_MI + G_T150_MINOCA)/2 - (G_T0_MI + G_T0_MINOCA)/2
## T300_vs_T0       (G_T300_MI + G_T300_MINOCA)/2 - (G_T0_MI + G_T0_MINOCA)/2
## T300_vs_T150 (G_T300_MI + G_T300_MINOCA)/2 - (G_T150_MI + G_T150_MINOCA)/2

ls <- level_specific_contrasts(primary_levels, secondary_levels)
data.frame(ContrastName = names(ls), Contrast = unlist(ls))

##                              ContrastName                  Contrast
## MINOCA_vs_MI_at_T0     MINOCA_vs_MI_at_T0     G_MINOCA_T0 - G_MI_T0
## MINOCA_vs_MI_at_T150 MINOCA_vs_MI_at_T150 G_MINOCA_T150 - G_MI_T150
## MINOCA_vs_MI_at_T300 MINOCA_vs_MI_at_T300 G_MINOCA_T300 - G_MI_T300

ic <- interaction_contrasts(primary_levels, secondary_levels)
data.frame(ContrastName = names(ic), Contrast = unlist(ic))

##                                                                      ContrastName
## interaction_MINOCA_vs_MI_at_T150_vs_T0     interaction_MINOCA_vs_MI_at_T150_vs_T0
## interaction_MINOCA_vs_MI_at_T300_vs_T0     interaction_MINOCA_vs_MI_at_T300_vs_T0
## interaction_MINOCA_vs_MI_at_T300_vs_T150 interaction_MINOCA_vs_MI_at_T300_vs_T150
##                                                                                           Contrast
## interaction_MINOCA_vs_MI_at_T150_vs_T0       (G_MINOCA_T150 - G_MI_T150) - (G_MINOCA_T0 - G_MI_T0)
## interaction_MINOCA_vs_MI_at_T300_vs_T0       (G_MINOCA_T300 - G_MI_T300) - (G_MINOCA_T0 - G_MI_T0)
## interaction_MINOCA_vs_MI_at_T300_vs_T150 (G_MINOCA_T300 - G_MI_T300) - (G_MINOCA_T150 - G_MI_T150)

group_levels <- c("CondA", "CondB", "CondC")
sf <- generate_contrasts_for_factor(group_levels)
data.frame(ContrastName = names(sf), Contrast = unlist(sf))

##                  ContrastName      Contrast
## CondB_vs_CondA CondB_vs_CondA CondB - CondA
## CondC_vs_CondA CondC_vs_CondA CondC - CondA
## CondC_vs_CondB CondC_vs_CondB CondC - CondB

Generating all contrasts at once

generate_contrasts combines main effects, level-specific, and interaction contrasts into a single data frame:

all_contrasts <- generate_contrasts(primary_levels, secondary_levels)
knitr::kable(all_contrasts, row.names = FALSE)

To exclude interaction contrasts:

no_int <- generate_contrasts(primary_levels, secondary_levels, interactions = FALSE)
knitr::kable(no_int, row.names = FALSE)

Working with annotation tables

In a typical prolfquapp workflow, you start with a sample annotation table that has columns for the two factors. annotation_add_contrasts creates a united Group column, generates all contrasts, and binds them alongside the annotation:

# x5463yzwer453bbb is a bundled example annotation table
# with factor_A (MI / MINOCA) and factor_B (T0 / T150 / T300)
data("x5463yzwer453bbb", package = "prolfqua")
head(x5463yzwer453bbb[, c("Name", "Group", "factor_A", "factor_B")])

## # A tibble: 6 × 4
##   Name         Group       factor_A factor_B
##   <chr>        <chr>       <chr>    <chr>   
## 1 MI_150_6     MI_T150     MI       T150    
## 2 MINOCA_0_3   MINOCA_T0   MINOCA   T0      
## 3 MINOCA_300_5 MINOCA_T300 MINOCA   T300    
## 4 MI_150_5     MI_T150     MI       T150    
## 5 MI_150_1     MI_T150     MI       T150    
## 6 MI_0_3       MI_T0       MI       T0

result <- annotation_add_contrasts(
  x5463yzwer453bbb,
  primary_col = "factor_A",
  secondary_col = "factor_B",
  prefix = "primary"
)

# The annotation with united Group and contrast columns
knitr::kable(head(result$annot[, c("Name", "Group", "ContrastName", "Contrast")], 10),
             row.names = FALSE)

# Suggested output file name
result$name

## [1] "DEA_primary_dataset.csv"

Swapping primary and secondary factors gives contrasts from the other perspective:

result2 <- annotation_add_contrasts(
  x5463yzwer453bbb,
  primary_col = "factor_B",
  secondary_col = "factor_A",
  prefix = "secondary"
)
knitr::kable(head(result2$annot[, c("Name", "Group", "ContrastName", "Contrast")], 10),
             row.names = FALSE)

Session Info

sessionInfo()

## R version 4.6.2 (2026-10-29)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 26.04.1 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: Etc/UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] prolfqua_0.99.8  dplyr_1.2.1      BiocStyle_2.41.0
## 
## loaded via a namespace (and not attached):
##   [1] Rdpack_2.6.6           gridExtra_2.3.1        rlang_1.3.0           
##   [4] magrittr_2.0.5         clue_0.3-68            GetoptLong_1.1.1      
##   [7] otel_0.3.0             matrixStats_1.5.0      compiler_4.6.2        
##  [10] mgcv_1.9-5             png_0.1-9              vctrs_0.7.3           
##  [13] pkgconfig_2.0.3        shape_1.4.6.1          crayon_1.5.3          
##  [16] fastmap_1.2.0          backports_1.5.1        labeling_0.4.3        
##  [19] utf8_1.2.6             promises_1.5.0         rmarkdown_2.32        
##  [22] nloptr_2.2.1           UpSetR_1.4.1           purrr_1.2.2           
##  [25] xfun_0.62              glmnet_5.2             jomo_2.7-6            
##  [28] logistf_1.26.1         cachem_1.1.0           jsonlite_2.0.0        
##  [31] progress_1.2.3         later_1.4.8            pan_2.0               
##  [34] prettyunits_1.2.0      broom_1.0.13           parallel_4.6.2        
##  [37] cluster_2.1.8.3        R6_2.6.1               bslib_0.12.0          
##  [40] stringi_1.8.9          RColorBrewer_1.1-3     limma_3.99.4          
##  [43] boot_1.3-32            rpart_4.1.27           jquerylib_0.1.4       
##  [46] Rcpp_1.1.2             iterators_1.0.14       knitr_1.52            
##  [49] IRanges_2.47.5         httpuv_1.6.17          Matrix_1.7-6          
##  [52] splines_4.6.2          nnet_7.3-21            tidyselect_1.2.1      
##  [55] yaml_2.3.12            doParallel_1.0.17      codetools_0.2-20      
##  [58] lattice_0.23-1         tibble_3.3.1           plyr_1.8.9            
##  [61] shiny_1.14.0           withr_3.0.3            S7_0.2.2              
##  [64] evaluate_1.0.5         survival_3.8-12        circlize_0.4.18       
##  [67] pillar_1.11.1          BiocManager_1.30.27    mice_3.19.0           
##  [70] KernSmooth_2.23-27     foreach_1.5.2          stats4_4.6.2          
##  [73] reformulas_0.4.4       plotly_4.12.1          generics_0.1.4        
##  [76] hms_1.1.4              S4Vectors_0.51.10      ggplot2_4.0.3         
##  [79] scales_1.4.0           minqa_1.2.8            xtable_1.8-8          
##  [82] glue_1.8.1             maketools_1.3.2        tools_4.6.2           
##  [85] sys_3.4.3              data.table_1.18.6.1    lme4_2.1-0            
##  [88] forcats_1.0.1          buildtools_1.0.0       grid_4.6.2            
##  [91] tidyr_1.3.2            rbibutils_2.4.1        crosstalk_1.2.2       
##  [94] colorspace_2.1-4       nlme_3.1-172           formula.tools_1.7.1   
##  [97] cli_3.6.6              viridisLite_0.4.3      ComplexHeatmap_2.29.0 
## [100] gtable_0.3.6           sass_0.4.10            digest_0.6.39         
## [103] operator.tools_1.6.3.1 BiocGenerics_0.59.13   ggrepel_0.9.8         
## [106] rjson_0.2.23           htmlwidgets_1.6.4      farver_2.1.2          
## [109] htmltools_0.5.9        lifecycle_1.0.5        httr_1.4.9            
## [112] mime_0.13              GlobalOptions_0.1.4    mitml_0.4-5           
## [115] statmod_1.5.2          MASS_7.3-66