associate$regression

associate$regression() fits one association model per outcome x predictor x interaction x stratum cell resolved from a PolyGeniusStudy, picking a classical or survival family per outcome. It returns a PolyGeniusAssociation carrying long-format coefficient rows, plot-ready artifacts and per-fit diagnostics.

With output = "summary" (default), a PolyGeniusAssociation: $results — One row per coefficient term, following the schema named in each row's schema column (schema-lm, schema-glm, schema-cox, schema-crr or schema-km): identity (.fit, fit.id, family, outcome, predictor, interaction, covariates, term, term.type, stratum, formula), inference (estimate, se, lower, upper, statistic, pval, adj.pval, adj.family.id), and n, effect.scale, test. Survival schemas add n.events, entry and time.origin; glm adds n.cases and n.controls. A km row is an omnibus log-rank test and carries no coefficient.

$artifacts — prediction.grid for lm/glm; observed.curves, predicted.curves, risk.table and group.summary for cox/crr; observed.curves, risk.table and group.summary for km. Compacted to a .fit key -- use artifacts() to rejoin the identity columns. Empty when artifacts = "none".

$diagnostics — fit.messages, one row per warning, error or not-fitted cell, kept wide with its full fit context.

$fits — One row per fit: identity plus covariates, formula, n, n.cases, n.controls, n.events, entry, time.origin. Failed fits are included.

$metadata — outcome.type (or "mixed" when families disagree).

$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 fits that ran, with columns fit.id, family, outcome and predictor. It does not carry the fitted model objects.

Outcome descriptors

outcomes accepts a bare column, an outcome() wrapper, a surv() descriptor, or a c() of these. Survival descriptors are read from the unevaluated call, so only time, event, competing (or competing.event), entry and origin are honoured here; surv()'s event.code, competing.code, type and label are ignored on this path.

# Bare column -- family inferred from the column's type
associate$regression(data, outcomes = dementia)

# Several plain outcomes in one call
associate$regression(data, outcomes = c(bmi, dementia))

# Survival outcome (Cox), then with a competing risk (Fine-Gray)
associate$regression(data, outcomes = surv(time = age, event = dementia))
associate$regression(data,
  outcomes = surv(time = age, event = dementia, competing = death))

# Several survival outcomes sharing one time variable
associate$regression(data,
  outcomes = c(
    dementia = surv(time = age, event = dementia),
    mci      = surv(time = age, event = mci)
  ))

# Left-truncated (delayed-entry) Cox
associate$regression(data,
  outcomes = surv(time = age_exit, event = dementia, entry = age_entry,
                  origin = "age since birth"))

Family selection

model = "auto" resolves per outcome: a surv() descriptor with a competing event gives "crr" and without one gives "cox"; a factor or logical column gives "glm", as does a numeric column whose non-missing values are all in {0, 1} and a character column with at most two distinct values; anything else gives "lm". "km" is never inferred and must be requested explicitly. A multi-level factor outcome resolves to "glm" and then fails in the fit.

Left truncation

surv(entry = ) declares a delayed-entry time: "cox" and "crr" then fit Surv(entry, time, event), restricting each event's risk set to subjects with entry <= time. surv(origin = ) is a free-text label for what time = 0 means; it is never checked against the data, but it is recorded on every result row and in $fits as time.origin (alongside the resolved entry column name) so associate$meta can warn when pooled studies disagree.

Complete cases

Each fit drops rows missing any variable it uses -- outcome, time, event, competing, entry, predictor, interaction or covariate -- and reports that count as n. Dropping is per fit, so strata and families can retain different sample sizes. A subject lost to follow-up must be coded as censored (last contact in time, event = 0), not as NA: censored rows define the at-risk sets and, for "crr", the censoring distribution behind the Fine-Gray weights, whereas an NA time silently removes the subject. For "crr", complete cases are selected before survival::finegray() builds the weighted risk set, so those weights are estimated on exactly the analysis sample.

Multiplicity

p.adjust.method is applied within each outcome x family x stratum group, not across the whole table, so screening many predictors for one outcome is the controlled family. km rows carry no adj.pval. The declared families are recorded in $indices$multiplicity and keyed from adj.family.id.

Failed fits

A cell that errors is dropped, recorded in $diagnostics$fit.messages with a reason.code, and summarized in one warning; the surviving cells are still returned. The call aborts only when every cell failed, or -- before any fit runs -- when a covariate or interaction term has a single observed level across the whole frame.

associate, associate$compare, associate$meta, PolyGeniusAssociation, outcome(), surv()

Other associate-analyses: associate-compare, associate-mediation, associate-meta, associate-mr, associate-single-variant