Contents

PolyGeniusResult

Shared result-container base

PolyGeniusResult is the base every PolyGeniusAssociation and PolyGeniusEvaluation is built on. It is not constructed directly: use PolyGeniusAssociation() or PolyGeniusEvaluation(), which supply their own class tag and slot conventions (association's fits argument becomes indices$fits; evaluation passes an empty indices).

This topic also documents the methods implemented once here and shared by both subclasses: as.data.frame(), as.data.table(), [, split() and the dplyr verbs. Every one of them returns a new object and leaves its input untouched.

Usage

PolyGeniusResult(
  results = NULL,
  indices = list(),
  artifacts = list(),
  diagnostics = list(),
  metadata = list(),
  class = character()
)

S3 method for class 'PolyGeniusResult'

as.data.frame(x, row.names = NULL, optional = FALSE, ...)

S3 method for class 'PolyGeniusResult'

as.data.table(x, ...)

S3 method for class 'PolyGeniusResult'

x[i, j, drop = FALSE]

S3 method for class 'PolyGeniusResult'

split(x, f, drop = FALSE, ...)

S3 method for class 'PolyGeniusResult'

filter(.data, ...)

S3 method for class 'PolyGeniusResult'

slice(.data, ...)

S3 method for class 'PolyGeniusResult'

arrange(.data, ...)

S3 method for class 'PolyGeniusResult'

mutate(.data, ...)

S3 method for class 'PolyGeniusResult'

select(.data, ...)

S3 method for class 'PolyGeniusResult'

rename(.data, ...)

S3 method for class 'PolyGeniusResult'

transmute(.data, ...)

S3 method for class 'PolyGeniusResult'

distinct(.data, ..., .keep_all = FALSE)

S3 method for class 'PolyGeniusResult'

group_by(
  .data,
  ...,
  .add = FALSE,
  .drop = dplyr::group_by_drop_default(.pg.dplyr.data(.data))
)

S3 method for class 'PolyGeniusResult'

ungroup(.data, ...)

S3 method for class 'PolyGeniusResult'

summarise(.data, ...)

S3 method for class 'PolyGeniusResult'

pull(.data, ...)

Arguments

Argument	Description
`results`	A data.frame or data.table of result rows, or NULL (default) for a zero-row table. Coerced to a data.table.
`indices`	Named list of index tables (e.g. fits), default list(). Each data.frame entry is coerced to a data.table; other entries pass through.
`artifacts`	Named list of plot-ready tables, default list(). A bare data.frame is wrapped as list(messages = ...). An unnamed or partly named list aborts.
`diagnostics`	Named list of diagnostic tables, default list(). Same handling as artifacts.
`metadata`	Named list, default list(). Stored as given: whatever the caller and the internals of an analysis put there travels with the object untouched.
`class`	Character vector of subclass names, most specific first (e.g. "PolyGeniusAssociation"), default character(). At least one name is required; an empty class aborts.
`x`	A PolyGeniusAssociation or PolyGeniusEvaluation.
`.data`	A PolyGeniusAssociation or PolyGeniusEvaluation.
`row.names`	Unused; present for as.data.frame() signature compatibility.
`optional`	Unused; present for as.data.frame() signature compatibility.
`...`	For a dplyr verb, that verb's own arguments, passed straight to the matching dplyr function. For as.data.frame(), passed on to as.data.frame(). Unused by as.data.table() and split().
`i`	Row and column index for [, applied to $results, as for a data.frame. Either may be missing; both missing returns a copy of x.
`j`	Row and column index for [, applied to $results, as for a data.frame. Either may be missing; both missing returns a copy of x.
`drop`	Logical scalar, default FALSE. For [, present for signature compatibility only -- $results is a data.table, which ignores it, so [ returns a result object rather than a bare column. For split(), drops unused factor levels.
`f`	For split(), one or more column names of $results, or a vector as long as nrow($results). A name not present in $results aborts, as does a vector of the wrong length.
`.keep_all`	Logical scalar, default FALSE. Passed to dplyr::distinct(). With .keep_all = FALSE and at least one column named in ..., distinct() returns the plain distinct table rather than a result object, since the remaining columns cannot identify their own rows.
`.add`	Logical scalar, default FALSE. Passed to dplyr::group_by(); TRUE adds to the existing grouping rather than replacing it.
`.drop`	Logical scalar, default dplyr::group_by_drop_default(.pg.dplyr.data(.data)). Passed to dplyr::group_by() and recorded on $metadata$dplyr.drop.

Value

PolyGeniusResult() returns a list of class c(class, "PolyGeniusResult", "list") with slots $results (a data.table), $indices, $artifacts, $diagnostics and $metadata (named lists), and $provenance (a PolyGeniusProvenance, or NULL when the object was built without one).

The shared methods return a PolyGeniusAssociation or PolyGeniusEvaluation of the same subclass as x/.data -- a new object, with the input unmodified -- except: as.data.frame() a plain data.frame of $results; as.data.table() a copy of $results; split() a named list of such objects, one per level; summarise() and pull() a plain dplyr table and a bare vector; and distinct() a plain distinct table under the .keep_all rule above.

Details

What a shared method does to the slots beyond $results:

Row-changing ([, split(), filter(), slice(), arrange(), distinct()) prune $artifacts and $diagnostics to the rows whose composite tuple of shared identifier columns still occurs in $results, and prune $indices$multiplicity to the adjustment families still represented. Association also prunes $fits. A non-tabular artifact (a similarity matrix, say) passes through untouched, and adj.pval is never recomputed -- a surviving row's adjusted p-value still refers to its family's original size.
Column-changing (select(), rename(), transmute()) prune nothing and re-add any core identifier column the verb dropped, so a selected-down object still identifies its own rows.
mutate(), group_by(), ungroup() prune nothing. Grouping is stored on $metadata$dplyr.groups/$dplyr.drop and reapplied by the next verb rather than kept on $results; a grouping column that a later verb removes is dropped from the record.
summarise() and pull() leave the container behind entirely and return dplyr's own output.

print(), summary(), plot(), merge()/c(), and association's artifacts() carry per-class content and stay on PolyGeniusAssociation and PolyGeniusEvaluation. federate() is implemented once here, like the dplyr verbs.

$metadata and $provenance

Two slots, two jobs.

$metadata is open space, stored exactly as it is given. Analysis-level scalars live there (analysis, outcome.type), and so does whatever an analysis's own internals pass through it -- fit.id and family travel that way from a per-fit producer to the aggregator that builds $fits, and dplyr.groups/dplyr.drop are read back by the next verb. Nothing validates or interprets its keys.

$provenance is one PolyGeniusProvenance() recording how the object was made: the operation, the call, the arguments supplied, what the operation resolved, and a stamped created/ version. Read it with provenance(x) and set it with provenance(x) <- value, which is the only writer -- it coerces, so the slot holds a record or NULL and provenance(x) is type-stable. PGSLibrary and PolyGeniusStudy carry the same field under the same name, so one verb reads all three.

A row- or column-changing verb carries the record: it narrows a result, it does not produce one. merge() is the one exception -- a merged object was not produced by a single call, and it may bind rows computed at different settings, so one record would describe rows it does not cover. provenance() on a merged object returns NULL.

Where a result lives

A PolyGeniusResult is a plain list -- never an R6 object, never carrying a live environment -- so it round-trips through saveRDS()/readRDS() and through savePolyGenius()/loadPolyGenius() with no reconstruction machinery beyond its own constructor. associate$*() returns a PolyGeniusAssociation and evaluate$*() a PolyGeniusEvaluation; file one into the study it came from, at study$associations[[name]] or study$evaluations[[name]].

See Also

PolyGeniusAssociation, PolyGeniusEvaluation

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

Aliases: PolyGeniusResult, as.data.frame.PolyGeniusResult, as.data.table.PolyGeniusResult, [.PolyGeniusResult, split.PolyGeniusResult, filter.PolyGeniusResult, slice.PolyGeniusResult, arrange.PolyGeniusResult, mutate.PolyGeniusResult, select.PolyGeniusResult, rename.PolyGeniusResult, transmute.PolyGeniusResult, distinct.PolyGeniusResult, group_by.PolyGeniusResult, ungroup.PolyGeniusResult, summarise.PolyGeniusResult, pull.PolyGeniusResult