Genome Tracks
Composing variant, model and library-wide signal on one shared genome axis
Who this page is for
You need a model library and, for most of it, at least one single-variant scan. If you have one score and one outcome, you do not need this page.
What it gives you is a way to ask where in the genome a score-level finding comes from, by putting several signals on one shared axis.
Start with the overview
One call takes your models and a scan and produces a stacked figure: where your library places its variants, the variant-level signal, where models converge, and how consistent they are.
It runs the underlying genome-signal computations for you, which is worth knowing — you are not expected to prepare them first.
The signals available
| Track | Needs |
|---|---|
| variant-level significance | a single-variant scan |
| per-model signal | a per-model regression |
| variant reuse, coverage, effect sizes | a PGS library |
| convergence, concordance, cumulative weight, attribution | a computed genome signal |
A track is not a plot
Each builder returns a specification rather than a figure: plain, saveable, and re-renderable at any region later without recomputing anything.
Print it and it draws on its own axis. Convert it and you get a ggplot you can add to. Only the composing functions return a finished multi-panel figure.
Composing
Stack tracks top to bottom; only the bottom one carries the chromosome axis.
All tracks in a stack must be on the same genome build — mixing them is refused rather than silently misaligned.
The axis is the union of every track's positions, so a track covering fewer variants is placed on the shared axis rather than stretched across it. That is the most likely misreading of a stack.
Zooming
Restricting to a region re-renders from the same tracks; it never recomputes. Looking at three loci is three calls over one set of tracks.
Two things change when you zoom, and both look like data if you do not know:
Bin width adapts to the window. A zoomed track is not a crop of the whole-genome one — the bars are computed over narrower bins, so their heights differ. Values are not comparable between the two views.
Clipping happens before summarising. A moving-window summary near the edge of your region cannot see variants just outside it, so it is under-counted there.
For the lane heatmaps — attribution and PRS-level association — scale = "genome" on the stack turns both off: the lanes keep their genome-wide bin width and colour limits, and the zoom only crops. A zoomed lane then reads on the same scale as the whole-genome figure. Bar and point tracks are unaffected.
Marking loci
visualize$genome$loci() is a thin track of labelled rectangles, one per interval — hotspots, candidate regions. Pass the same intervals to the stack as bands = and they are shaded through every panel, behind the data, without moving either axis.
A locus that straddles a zoom edge is kept and drawn clipped. At genome scale a 1 Mb locus is narrower than a pixel, so loci and bands are drawn at a minimum width of 0.3% of the visible span. That widening is display only: do not read a band's width as the locus size on a whole-genome figure.
The two reduces
The statistical reduction — how variant-level values become a positioned signal — is shared with the compute side, so a track shows the same signal the table does.
The display reduction is separate: disjoint bins, or an overlapping moving window. That choice is about legibility, not about the signal.
A moving window is a moving sum, so it inflates the height of area tracks relative to disjoint bins. Immaterial for anything normalised; material if you are reading absolute values.
Keeping a genome-wide figure readable
Point tracks can be rasterised, binned tracks take a bin width and a reduce mode, and labelled tracks take a cap on how many labels to draw.
Only some tracks pay a cost for a wide moving window; the summed ones do not expand at all. If a render is going to be very large you get a warning naming the argument to change.
Two things not to over-read
The standardisation option on the effects track is a display normalisation across models, not a reported statistic. Do not quote it as an effect size.
The overview drops a track it cannot build and warns rather than failing, so a missing panel is information about your inputs rather than a glitch.