PolyGeniusAssociation

PolyGeniusAssociation is the standard result object returned by association workflows. It is a PolyGeniusResult carrying $results, $fits, $indices, $artifacts, $diagnostics and $metadata; the constructor is exported so a custom producer can emit the same object every associate$*() function does.

plot() draws the default plot for the object's schema, resolving the schema's declared default.plot token through the visualize plot registry. It aborts when $results mixes more than one schema, or when no plot is registered for that schema; use the specific visualize$associations$*() function in either case.

merge() combines any number of PolyGeniusAssociation objects into one, binding result rows and table-like artifacts. An optional .id column can be added to trace each row back to its source object.

A list with class c("PolyGeniusAssociation", "PolyGeniusResult", "list"), carrying $results, $fits, $indices, $artifacts, $diagnostics, $metadata and $provenance.

print() returns x invisibly; called for its console output, which lists the schemas, families, result-row and fit counts, a not-fitted count when any fit failed, one line per artifact and diagnostic entry, and a closing line summarising the provenance record.

summary() returns a summary.PolyGeniusAssociation list with $counts (a data.table of per schema/family result-row and fit counts) and $failures (a data.table with one deduplicated row per not-fitted/error cause, with a fit count n). Both are empty typed tables when $results has no rows.

plot() returns whatever the registered plot function builds: a ggplot, a patchwork composite, or a PolyGeniusGenomeTrack, depending on the schema's default.plot.

merge() returns one PolyGeniusAssociation. .fit and adj.family.id are offset per input so keys stay unique, multiplicity families are re-keyed rather than recomputed, and $metadata records merged, n.objects and sources. Aborts when no object is supplied or any input is not a PolyGeniusAssociation.

c() returns the same merged PolyGeniusAssociation merge() does. A .id passed to c() reaches merge(), so c(a = x, b = y, .id = "source") adds the source column.

$results is a long-format data.table where each row is one statistical claim (coefficient, test, ...), stored fully materialized so it reads directly. Every row carries columns .fit, fit.id, schema, family, outcome, predictor, term, estimate, se, lower, upper, pval, adj.pval, adj.family.id and n. adj.family.id is NA on a row adj.pval was never computed for (e.g. km, which carries no coefficient-scale test); where it is populated it keys into $indices$multiplicity.

$fits (equivalently $indices$fits) is the per-fit lookup table: one row per .fit carrying the fit-level-invariant metadata (fit.id, family, outcome, predictor, stratum, formula, counts, ...). Row-heavy $artifacts and $diagnostics tables store only the integer .fit key plus their own value columns; the identifying columns are factored out here so they are stored once per fit rather than once per row. Use artifacts() to retrieve an artifact with the $fits metadata joined back on. $fits is NULL (and $indices empty) for analysis types whose tables are already narrow (e.g. meta, mediation, compare).

$indices is the PolyGeniusResult normalization-index slot: a named list of tables, each joined to $results by an integer key. Association carries two today: fits (keyed by .fit, association-only) and multiplicity (keyed by adj.family.id, shared with evaluation -- one row per BH-adjustment family, declaring p.adjust.method, the grouping columns, and family size n, so adj.pval stays traceable to what produced it across merge() and subsetting).

$artifacts is a named list of plot-ready derived tables such as prediction grids, survival curves, risk tables, and cumulative-incidence curves. $diagnostics is a named list of diagnostic tables recording fit warnings, errors, exclusions, and convergence notes. $metadata is open space, stored as given; $provenance is the record of how the object was made, read with provenance(x). See $metadata and $provenance in PolyGeniusResult.

filter(), slice(), arrange(), mutate(), select(), rename(), transmute(), distinct(), group_by(), and ungroup() operate on $results and return a PolyGeniusAssociation. Row-filtering verbs also prune $artifacts, $diagnostics, $fits and $indices$multiplicity to surviving identifiers. summarise() and pull() operate on $results but return a plain dplyr table or bare vector rather than a PolyGeniusAssociation. These verbs are implemented once, shared with PolyGeniusEvaluation -- see PolyGeniusResult.

PolyGeniusResult for the shared subsetting/dplyr-verb implementation, PolyGeniusEvaluation for the sibling subclass.

Other result-objects: PolyGeniusEvaluation(), PolyGeniusResult(), artifacts(), diagnostics(), federate(), provenance()