Contents

PolyGeniusGenomeSignal

Positioned genome-signal container

PolyGeniusGenomeSignal is the result object for a value defined over genome position: single-variant statistics, cross-model reductions (reuse, coverage, directional concordance, cumulative weight), per-trait attribution, and reference-frame contrasts. It is a lightweight S3 list with $results, $artifacts, $diagnostics, and $metadata.

plot() dispatches through the track registry on $metadata$statistic, since the class carries no default.plot.

Usage

PolyGeniusGenomeSignal(
  results,
  resolution = c("variant", "ld.block"),
  bin.reduce = c("sum", "mean", "max", "first"),
  statistic = NA_character_,
  frame = "absolute",
  build = NA_character_,
  artifacts = list(),
  diagnostics = list(),
  metadata = list()
)

print.PolyGeniusGenomeSignal(x, ...)

S3 method for class 'PolyGeniusGenomeSignal'

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

S3 method for class 'PolyGeniusGenomeSignal'

x[i, ...]

S3 method for class 'PolyGeniusGenomeSignal'

plot(x, ...)

Arguments

Argument	Description
`results`	A data.frame or data.table of positioned rows, coerced to data.table.
`resolution`	One of "variant" (default), "ld.block". Selects the required position column: position for the former, block for the latter.
`bin.reduce`	One of "sum" (default), "mean", "max", "first". How a display view-bin may legally collapse values; a ratio signal must use "sum".
`statistic`	Character scalar, default NA_character_. Short label for the statistic (e.g. "neglog10p", "concordance", "attribution").
`frame`	Character scalar, default "absolute". The coarse comparison frame: "absolute" for a statistic standing on its own, "relative" for a contrast against a reference. The contrast method itself is carried by statistic. Recorded as given, not checked against those two values.
`build`	Character scalar, default NA_character_. Genome build the positions are on (e.g. "GRCh38").
`artifacts`	Named list, default list(). Standard artifact slot; a non-list is replaced by list().
`diagnostics`	Named list, default list(). Standard diagnostic slot; a non-list is replaced by list().
`metadata`	Named list, default list(). Extra metadata, merged over the constructor's own resolution/bin.reduce/statistic/frame/build entries, so a key of the same name overrides one of them.
`x`	A PolyGeniusGenomeSignal.
`...`	Passed to as.data.frame() for that method and, for plot(), to the resolved visualize$genome$* track builder; unused by print() and [.
`row.names`	Accepted for the as.data.frame() generic's signature and ignored.
`optional`	Accepted for the as.data.frame() generic's signature and ignored.
`i`	Row selector applied to $results, as for [ on a data.table.

Value

A list with class c("PolyGeniusGenomeSignal", "list") carrying $results (a data.table), $artifacts, $diagnostics, and $metadata holding resolution, bin.reduce, statistic, frame, build plus anything metadata added.

print() returns x invisibly. It writes the statistic, frame, resolution, bin.reduce, build and row count, plus the first six chromosomes and the group count when $results has rows.

as.data.frame() returns $results as a plain data.frame, dropping $artifacts, $diagnostics and $metadata.

[ returns a PolyGeniusGenomeSignal with $results subset to those rows and $artifacts, $diagnostics and $metadata carried over unchanged. The constructor's checks are not re-run, so a subset that removes every row is allowed.

For plot(), a PolyGeniusGenomeTrack, for visualize$genome$stack(); it does not compose with +. Aborts when no registry entry declares x's statistic.

Details

$results is a long-format data.table, one row per positioned unit at the signal's finest native resolution:

chr (character), and either position (integer bp, resolution = "variant") or block (LD-block id, resolution = "ld.block");
at resolution = "variant", nea/ea (the non-effect/effect allele the signal's value(s) are oriented against) -- required, the same way chr/position are, so a signal can state which allele its sign refers to and be joined against another canonicalized-allele source (genome.signal.canonical.ea()/genome.signal.canonical.vkey() below);
a value column, or a numerator/denominator pair (value.num / value.den) for ratio statistics such as directional concordance, so that re-binning at render stays correct (sum the parts, divide after);
an optional group column (e.g. trait/model for lane views).

Provenance -- statistic, frame, build, resolution and bin.reduce -- lives on $metadata, not as columns of $results.

Values are stored at finest resolution and are not pre-binned for display. The renderer performs display binning keyed on the region and pixel width, collapsing rows with the reduction declared in $metadata$bin.reduce. Choosing the correct reduction is a compute-time decision frozen on the signal; the renderer only applies it.

Federation: a signal is derived from summary-level inputs only and must carry no individual-level (per-sample) data; the constructor rejects any column whose name looks like a sample identifier, listed under Boundary errors below.

Boundary errors

Construction aborts when results is not a data frame, when chr or the resolution's own position column is missing, when neither a value column nor a complete value.num/value.den pair is present, when a ratio signal asks for anything but bin.reduce = "sum", when position is not numeric at variant resolution, when nea/ea are missing at variant resolution, when a column named sample, samples, iid, fid, obs, obs_names or sample.names is present in any case, or when metadata is not a list.

Examples

# A per-variant signal (produced in practice by compute$genome$*):
sig <- PolyGeniusGenomeSignal(
  data.frame(chr = c("1", "1", "2"), position = c(1e6, 2e6, 5e7),
             nea = c("A", "C", "G"), ea = c("G", "T", "A"),
             value = c(3.2, 1.1, 8.4)),
  statistic = "neglog10p", bin.reduce = "max", build = "GRCh38")

# A ratio statistic (e.g. directional concordance) stores num/den, summed at
# render and divided after -- so it must be sum-reducible:
con <- PolyGeniusGenomeSignal(
  data.frame(chr = "1", position = 1e6, nea = "A", ea = "G",
             value.num = 3, value.den = 4),
  statistic = "concordance", bin.reduce = "sum")

signal <- PolyGeniusGenomeSignal(
  data.frame(chr = "1", position = 1e6, nea = "A", ea = "G",
             value.num = 3, value.den = 4),
  statistic = "concordance", bin.reduce = "sum"
)
track <- plot(signal)

PolyGeniusGenomeSignal

Usage

Arguments

Value

Details

Boundary errors

Examples

See Also