Contents

associate$compare

Formal model comparisons for a PolyGeniusStudy

associate$compare() answers one of three comparison questions about predictors and outcomes resolved from a PolyGeniusStudy: does adding a predictor improve fit, is its effect homogeneous across groups, and how do group-specific effects differ pairwise. It returns a PolyGeniusAssociation whose $results follow the "comparison" schema.

Usage

associate.compare(
  data,
  outcomes,
  predictors = NULL,
  groups.by = NULL,
  covariates = NULL,
  type = c("incremental", "heterogeneity", "contrast"),
  model = c("auto", "lm", "glm", "cox", "crr"),
  reference.level = NULL,
  conf.level = 0.95,
  p.adjust.method = "BH",
  output = c("summary", "models"),
  ...
)

Arguments

Argument	Description
`data`	A PolyGeniusStudy.
`outcomes`	Unquoted outcome expression, resolved from data. Accepts a bare column, an [outcome()](/reference/outcome/) wrapper, a [surv()](/reference/surv/) descriptor, or a c() of these.
`predictors`	Unquoted predictor expression, or NULL (default). Required by all three types: for "incremental" the terms added to the base model, otherwise the exposure whose effect is examined by group. Only the first resolved column is used.
`groups.by`	Unquoted grouping expression, or NULL (default). Required for "heterogeneity" and "contrast", which abort without it; unused by "incremental". Non-factor columns are coerced with factor(), so levels take their natural order.
`covariates`	Unquoted adjustment expression, or NULL (default). Entered in both the base and full model.
`type`	One of "incremental" (default), "heterogeneity", "contrast".
`model`	One of "auto" (default), "lm", "glm", "cox", "crr". "auto" infers the family per outcome; any other value forces it.
`reference.level`	Non-empty character scalar, or NULL (default). Validated and carried into the fit specification, but no comparison family reads it -- it currently has no effect on the fitted contrasts.
`conf.level`	Numeric scalar in (0, 1), default 0.95. Confidence level for the "contrast" intervals.
`p.adjust.method`	Character scalar, default "BH". Method passed to stats::p.adjust().
`output`	One of "summary" (default), "models". "models" returns a fit index rather than a result object -- see Value.
`...`	Collected into the fit specification alongside reference.level. No comparison family reads them; they are not forwarded to the fitting function.

Value

With output = "summary" (default), a PolyGeniusAssociation: $results — Rows following the schema-comparison schema -- identity (fit.id, family, outcome, predictor, covariates, stratum, comparison.type, groups.by, contrast, term, term.type), inference (estimate, se, lower, upper, statistic, pval, adj.pval, adj.family.id, df1, df2), plus base.model, full.model, effect.scale, test, n and n.events.

$artifacts — Empty. The "comparison" schema declares observed.curves and predicted.curves as optional, but no comparison family builds them.

$diagnostics — fit.messages, one row per warning or error raised by a comparison cell. A cell that errors contributes a diagnostic row and no result row; the remaining cells still return.

$fits — NULL -- comparison rows are already narrow, so artifacts() returns tables unchanged.

$provenance — the captured call; see $metadata and $provenance in PolyGeniusResult.

$indices$multiplicity — One row per declared adjustment family, keyed from each result row's adj.family.id. With output = "models", a plain data.frame indexing the cells that ran, with columns fit.id, family and outcome. It does not carry the fitted model objects.

Details

Comparison types

"incremental" — Refits the model with and without predictors and tests the difference. For "lm" this is a nested F-test and estimate is the increase in R-squared (effect.scale = "delta.r2"); for "glm", "cox" and "crr" it is a likelihood-ratio test and estimate is NA -- no reclassification or discrimination metric is computed.

"heterogeneity" — Tests predictors * groups.by against the additive model. One row, term.type = "interaction", estimate NA; the F (lm) or chi-square (others) statistic carries the result.

"contrast" — Fits the interaction model and emits one row per pair of groups.by levels, with the difference in the predictors effect, its delta-method standard error, a conf.level interval and a Wald p-value.

Family selection

model = "auto" resolves per outcome: a surv() descriptor with a competing event gives "crr" and without one gives "cox"; a factor, logical or binary-numeric outcome gives "glm"; anything else gives "lm". "km" is not a comparison family. outcomes accepts a bare column, an outcome() wrapper, a surv() descriptor, or a c() of these; mixing surv() and plain outcomes in one call aborts.

Every family fits on complete cases of the columns it uses, so n is per comparison cell. "crr" additionally aborts when a row is flagged as both the event and the competing event.

Multiplicity

p.adjust.method is applied within each outcome x family group. The declared families are recorded in $indices$multiplicity and keyed from adj.family.id.

Examples

# Does PRS_AD add to a covariate-only model?
associate$compare(data,
  outcomes   = dementia,
  predictors = PRS_AD,
  covariates = c(age, sex, PC1, PC2),
  type       = "incremental")

# Is the PRS_AD hazard ratio the same in both sexes?
associate$compare(data,
  outcomes   = surv(time = age_obs, event = dementia),
  predictors = PRS_AD,
  groups.by  = sex,
  covariates = c(PC1, PC2),
  type       = "heterogeneity")

# Pairwise cohort differences in the PRS_AD effect
associate$compare(data,
  outcomes   = dementia,
  predictors = PRS_AD,
  groups.by  = cohort,
  type       = "contrast")