Glossary and FAQ

Glossary

Where a term has a general meaning and a narrower PolyGenius meaning, both are given.

Artifact — a plot-ready derived table attached to a result, such as a confusion matrix or a set of survival curves. Artifacts exist so that plotting never has to compute a statistic. They arrive as a bundle per analysis, which is why a stratification result cannot draw a ROC curve.

Backbone — the PolyGeniusBackbone behind a model library: one variant dictionary plus the model registry, shared by every model in that library. It is what makes a library cost one dictionary rather than one per model. A PolyGeniusStudy owns its own, narrowed at construction from the PGS library it was handed, so two cohorts built from one PGS library carry two backbones of equal content rather than one object between them.

Cell (meta-analysis) — one comparable quantity across cohorts: the same predictor, outcome, model family and stratum. Pooling happens cell by cell.

Definition vs realization — the split that organizes PolyGeniusStudy. Definitional content (a model's variants and weights, its GWAS and algorithm provenance, a variant's identity) is true independent of any one cohort and lives on the shared backbone. Realization content (a score matrix, kinship, a fitted association) depends on which samples produced it and lives on the study. The test: would it be unchanged if you swapped in a different cohort's genotypes against the same model library? If yes, definitional; if no, realization.

Effect scale — the scale a stored estimate is on, from a closed vocabulary: identity, log-odds, log-hazard, log-subdistribution-hazard, change in R², median time. Stored estimates are always on the model's coefficient scale; plots exponentiate for display.

Effective sample size — the sample size that determines an effect estimate's variance. Equal to the total for a quantitative trait; for a case/control trait it is 4 × ncase × ncontrol / (ncase + ncontrol). Not interchangeable with the total, and supplying one where the other is wanted rescales every weight without erroring.

Family (multiple testing) — the set of tests a p-value adjustment is computed over. In PolyGenius a family is what was tested for one outcome within one stratum, per call. Adjustment never spans calls.

Fate (of a variant) — the recorded outcome of trying to score a variant: scored, or excluded with a reason. Every requested variant ends with exactly one.

Fit key — the integer that links a row-heavy artifact back to the fit that produced it, so identifying columns are not repeated on every artifact row.

Genome build — the reference assembly coordinates are on. PolyGenius supports GRCh37/hg19 and GRCh38/hg38 and refuses anything else at the boundary.

Identity (of a resource) — the hash of a resource's type and parameters, which decides whether a stored result can be reused. Excludes runtime hints; excludes the contents of files you pointed at; excludes the version of PolyGenius.

In-sample — computed on the same samples being judged. Every metric in evaluate is in-sample; there is no cross-validation anywhere in it.

Layer (score) — one named samples × models matrix in a study's scores slot (study$scores$<layer>). X is a convention, not a fixed name; a layer produced by compute$scores()/compute$standardize() carries its own diagnostics (coverage, or center/scale) attached to that layer itself, never copied elsewhere.

PGS / PRS — polygenic score and polygenic risk score name the same thing. This documentation says PGS.

PGSLibrary — the container holding the models an analysis works with: an ordered, named collection sharing one variant dictionary per genome build through a PolyGeniusBackbone. A PolyGeniusStudy is built from one and narrows it into a library of its own, reached as study$library.

PGSLibraryView — the view a model in a PGSLibrary is represented by once absorbed into a backbone: a pointer (backbone id plus position), not a materialized variant table. It refuses [, $<column> beyond a fixed registry set, and every dplyr verb, because letting any of those run would either materialize the whole variant table unbounded or silently clone/corrupt the shared backbone. as.PGS() is the one explicit crossing back to an owned, portable model.

Projection (of principal components) — computing components on a reference panel and placing your samples on those axes, rather than computing components within your own sample. A projected coordinate is a per-allele average.

Resource — anything the execution engine can produce and store: retrieved summary statistics, a prepared panel, an LD matrix, a model.

Rule — the unit that knows how to produce one type of resource. Rules declare their inputs and costs and never call each other.

Sample axis — the row axis of a PolyGeniusStudy's own tables: samples, sample.pairs, and the rows of a score layer. Sits alongside the model axis; the variant axis is not a study-owned axis at all, but an overlay onto the backbone's shared dictionary — see Variant dictionary.

Schema — an association's declared result contract: required and optional columns, artifacts, applicable plots, and the columns that identify a poolable cell. Evaluations have no schema.

Score layer — see Layer.

Store — the on-disk record of every resource that has been materialised, plus the index that is authoritative about what exists.

Stratum — one level of a split.by variable, fitted as an independent model. Part of the multiplicity grouping, which is why adding a split.by changes every adjusted p-value in a call.

Variant dictionary — the shared, dict.slot-indexed table of distinct variant identities on a PolyGeniusBackbone, one row per (chromosome, position, alleles). Every model absorbed into the backbone points into it rather than repeating a variant it shares with another model. It is reached through study$library$backbone, never as a slot on the study itself, and a model-side subset narrows it to exactly what the retained models reference.

Variant space — a named variant set used to restrict a reference panel before LD computation.

Virtual output — a resource whose count is not known until its rule runs, such as a parameter grid. Checked as a set: if any member is missing, the whole expansion re-runs.

Frequently asked

Why does a linear model's result have event-count columns?

Because the coefficient families share one table shape, which is what lets one forest plot, one pooling engine and one filtering vocabulary serve all of them. Columns that do not apply are empty. Expected, not a defect.

I standardised my scores and my effect sizes did not change. Why?

scores.layer defaults to X. Standardising into a different layer and not naming it means the analysis used the raw scores. This is the most common single mistake in a first analysis.

My adjusted p-values changed when I added split.by. Is that a bug?

No. The stratum is part of the multiplicity grouping, so adding one changes the families. Adjusted p-values from two calls with different groupings are not comparable.

Can I meta-analyse my evaluation results?

No. Pooling takes association objects only. Comparing predictive performance across cohorts is something you do by hand.

Why can't I pool a model comparison?

Because an incremental test produces a test statistic rather than an effect with a standard error, and inverse-variance weighting has nothing to weight. The same reason Kaplan–Meier cannot be pooled. Both declare this structurally rather than failing at pooling time.

Why did my Kaplan–Meier call error on a score column?

It requires a categorical predictor. Bin the score into quantiles first; there is no binning helper on that path.

Does PolyGenius test proportional hazards?

No. There is no Schoenfeld residual check anywhere in the package. Proportional hazards must hold within each cohort for a Cox coefficient — and any later pooled estimate — to mean anything. Take the fitted models and test them yourself.

I upgraded PolyGenius and got the same results. Is caching broken?

No, it is working as designed: a stored result is identified by what you asked for, not by which version answered. If a release note says a construction algorithm changed, generate into a fresh store so the new code runs.

I edited my GWAS file and got the old model back.

A locally-supplied table is identified by the name you gave it, not by its contents. Version the name, or use a fresh store.

My run finished instantly and the dashboard is empty.

That is a fully cached run. Cached tasks emit no events, so there is nothing to display, while the progress indicator counts them as complete. Raise verbosity to confirm.

I asked for twelve models and got seven, with no error.

Generation does not error on individual failures. The returned set carries a table of what failed and why, with each model's parameters on the same row. Read that first.

Why is my score not comparable to a colleague's on the same cohort?

Scores are sums over the variants that were scored, so their scale depends on how many that was. Two runs that scored different variant sets — different filters, different coverage — are on different scales. Standardise within cohort before comparing.

Why do my projected principal components include a cluster at zero?

Samples with no scoreable variant land at zero rather than missing. Check coverage before interpreting a cluster at the origin as average ancestry.

+ theme() did nothing to my forest plot.

It is a multi-panel composition, so + reaches only the last panel. Use & instead. Heatmaps take neither.

Grey cells in the leaderboard — is that worst, or missing?

Neither, necessarily. Grey means unranked or missing, indistinguishably. Metrics that exist for reporting rather than ranking render grey by design.

Can I use PolyGenius without letting my data leave the site?

Yes, and that is the intended multi-cohort pattern: computation runs locally against your files, and only summary-level result objects are shared. What a shared object carries depends on the artifacts you requested, so choose that deliberately rather than assuming the default is minimal.

Reporting checklist

Things worth recording alongside a result set, because they change the numbers and are not recoverable afterwards.

Inputs. Which GWAS, by accession or file with a version. Which reference panel and which build. Which variant space, if you restricted one.

Cohort handling. How many samples entered and how many survived each filter. Whether relatedness was assessed, at what degree, and how many samples pruning dropped. Whether principal components were computed in-sample or projected, how many, and on what variant set.

Scoring. How many of each model's variants your cohort actually had. Any minor-allele-frequency threshold, and that it was applied using your cohort's own frequencies. Whether scores were standardised, and within what set.

Analysis. The model family per outcome. The covariates, including how many principal components. The multiplicity grouping and the number of tests in each family. The raw as well as the adjusted p-value when the family is large.

Model selection, if you selected. Which components fed the ranking, which preset, and how many candidates were compared — because the index is relative to that set and is not comparable across runs. And that the metrics were in-sample, unless you held a cohort out.

Pooling, if you pooled. Fixed or random effects, how many cohorts, the heterogeneity statistic, and how many cohorts actually contributed to each estimate — which can be fewer than you passed in.

Software. The PolyGenius version, the PLINK2 version, and the versions of any method packages. Identity does not record these, so your notes are the only place they exist.