Fit CpG-wise mixed-effects models for longitudinal methylation analyses

Fit one linear mixed-effects model per CpG for each phenotype requested in the object returned by prepareMethylationLMEData(). Each native fit is reduced to compact numerical results and discarded before the next batch is returned.

fitMethylationLMEModels(
  preparedData,
  nCores = 1L,
  libPath = NULL,
  lmeLibs = "lme4,lmerTest",
  correlationStructure = "none",
  correlationVar = NULL,
  omnibusTest = FALSE,
  omnibusDdf = "Satterthwaite",
  summaryDir = NULL,
  resumeFromSummary = TRUE,
  verbose = FALSE,
  logs = FALSE,
  log_dir = NULL,
  log_file = "log_methylationLME.txt"
)

Arguments

preparedData

Object returned by prepareMethylationLMEData().

nCores

Integer. Maximum number of worker processes to use. Automatic fitting uses the lme4 or nlme crossover and caps workers by available CpGs, CPUs, and detected memory.

libPath

Character vector or NULL. Optional library paths forwarded to worker processes.

lmeLibs

Character vector or comma-separated string of package names to check on worker processes. The default is 'lme4,lmerTest'.

correlationStructure

Character. Residual correlation structure used when lmeLibs selects 'nlme'. One of 'none', 'AR1', or 'CAR1'.

correlationVar

Character or NULL. Variable used to order repeated observations within personVar for AR1 or CAR1 residual correlation structures. Must be supplied explicitly for AR1 or CAR1.

omnibusTest

Logical. If TRUE, calculate one joint fixed-effect test per CpG for the phenotype-by-interaction term, or the phenotype main effect when no interaction is requested.

omnibusDdf

Character. Denominator degrees-of-freedom method used by lmerTest::contestMD(): 'Satterthwaite' or 'Kenward-Roger'.

summaryDir

Character or NULL. Directory used for one complete compact summary per phenotype. NULL disables disk persistence.

resumeFromSummary

Logical. If TRUE, reuse a complete summary in summaryDir when it was generated from the same input file and model configuration.

verbose

Logical. If TRUE, emit progress messages with message().

logs

Logical. If TRUE, write the same messages to a log file.

log_dir

Character or NULL. Directory used for the log file when logs = TRUE.

log_file

Character. File name used when logs = TRUE.

Value

A list with class 'dnaEPICO_methylationLME_models' containing compact coefficient matrices, unfiltered target summaries, formulas, model conditions, omnibus results, hard errors, and phenotype summary artifacts.

Examples

ex <- dnaEPICO:::exampleMethylationLMEStateDnaEpico()
model_results <- fitMethylationLMEModels(
  preparedData = ex$preparedData,
  nCores = 1,
  verbose = FALSE,
  logs = FALSE
)
names(model_results$fits)
#> [1] "score"