PolyGeniusEvaluation

PolyGeniusEvaluation is the standard result object returned by the evaluate family of functions. It is a PolyGeniusResult with an $indices that is empty unless $results carries a BH-adjusted column -- evaluation has no per-fit index, but shares the multiplicity index with association. Fields: $results, $indices, $artifacts, $diagnostics, and $metadata.

plot() draws the default plot for the object's analysis type, resolving $results$analysis through the visualize plot registry's default.for field. An object mixing several analyses that includes performance or incremental goes to visualize$evaluate$profile(), which is built for exactly that shape; a single-analysis object always goes to that analysis's own plot. It aborts on any other mix of analysis types, or when no plot is registered for a single one; use the specific visualize$evaluate$*() function in either case.

merge() combines any number of PolyGeniusEvaluation objects into one, binding result rows and table-like artifacts.

A list with class c("PolyGeniusEvaluation", "PolyGeniusResult", "list"), carrying $results, $indices, $artifacts, $diagnostics, $metadata and $provenance. There is no $fits slot; that index is association-only.

print() returns x invisibly; called for its console output, which lists the analyses, outcomes, model and metric-row counts, one line per artifact and diagnostic entry, and a closing line summarising the provenance record.

summary() returns a data.table with one row per analysis/outcome pair and columns analysis, outcome, n.models, n.metrics; an empty typed table when $results has no rows.

as_tibble() returns $results as a plain tibble, dropping $indices, $artifacts, $diagnostics and $metadata.

plot() returns whatever the registered plot function builds: a ggplot for every analysis, evaluate$profile()'s combined view included -- except performance on an object mixing binary and continuous outcomes, which returns a patchwork of the two panels stacked; use &, not +, to apply a theme or scale to both panels there.

merge() returns one PolyGeniusEvaluation. adj.family.id is offset per input so adjustment families never collide, multiplicity is 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 PolyGeniusEvaluation.

c() returns the same merged PolyGeniusEvaluation 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 metric value for a model/outcome pair. The columns every row carries are analysis, outcome, outcome.type, model, model.ref, stratum, tier, tier.ref, metric, estimate, lower, upper, pval, adj.pval, adj.family.id, n, and n.events. adj.family.id keys into $indices$multiplicity and is NA on any row adj.pval was never computed for. Unlike an association, an evaluation has no PolyGeniusSchema: the contract is this column vector, returned by the internal .polygenius.evaluation.schema().

$indices is the PolyGeniusResult normalization-index slot. Evaluation has no per-fit index (association-only, fits, keyed by .fit), but does carry multiplicity (keyed by adj.family.id) whenever a producer recorded one through .pg.multiplicity.record() -- one row per BH-adjustment family, declaring p.adjust.method, the grouping columns, and family size n.

$artifacts is a named list of plot-ready derived tables: confusion (per-threshold counts, binary outcomes) and score.outcome.bins (a binned score-by-outcome grid, continuous outcomes).

$diagnostics is a named list of diagnostic tables.

$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 PolyGeniusEvaluation. Row-filtering verbs also prune $artifacts, $diagnostics and $indices$multiplicity to surviving identifiers. summarise() and pull() operate on $results but return a plain dplyr table or bare vector rather than a PolyGeniusEvaluation. These verbs are implemented once, shared with PolyGeniusAssociation -- see PolyGeniusResult.

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

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