GWAS Sources

You are about to build your own score. That means declaring where the summary statistics come from, which is what this page covers, and then choosing a construction method, which is chapter 09.

Declaring, not fetching

A source constructor describes what you want; nothing is retrieved until you run a generation call. That is what makes it cheap to declare more than you end up using.

Sources combine: pass several and the generation call pairs each with each algorithm. What that costs is chapter 10.

Local files

generate$sources$local() takes named summary-statistics tables, or functions that return them so nothing is read until needed.

Each table needs chromosome, position, effect and other allele, effect size and p-value. Add a standard error if you intend to use anything but clumping-and-thresholding.

Metadata needs an identifier and a genome build per entry, and every extra column you provide travels with the model — which is how sample sizes get supplied.

OpenGWAS

Declare study identifiers and PolyGenius handles authentication at run time.

There are two retrieval modes and the difference is large: above a p-value threshold of 0.1 it downloads the whole study's summary statistics, below it fetches only top hits. Since the LD-based methods default to using everything, that is usually a whole-study download.

Top-hits mode returns unclumped variants — do not assume the server clumped them for you.

The GWAS Catalog

Declare accessions; no token needed. The harmonised file location is derived from the accession itself, so the study API is only used for optional extras and its failure does not stop you.

Where the harmonised metadata provides a build or a trait name, those are used. Where a study reports only an odds ratio, the effect size is derived from it.

Sample size: total versus effective

The LD-based methods need the effective sample size, because it sets how much weight each variant's effect estimate carries. For a quantitative trait that is the total; for a case/control trait it is 4 × ncase × ncontrol / (ncase + ncontrol). Supplying a total where an effective size is wanted rescales every weight, and nothing about the result looks wrong.

Both remote sources work this out for you. Only local() needs you to act: if your trait is case/control, supply ncase and ncontrol in the metadata rather than a single sample size. The resolution order and its fallbacks are in ?generate$sources$local.

One thing to know if you are relying on being warned: the fallback caveat is written to the component log, not raised as an R warning. If you have set verbosity low, you will not see it — the setup block in Your First Analysis is a brief couple of lines, not a walkthrough of the verbosity setting, so check your own configuration if you are relying on this warning.

What every source normalises

Build labels are recognised in their common spellings, chromosome and position are coerced to consistent types, and rows without a usable coordinate are dropped and counted rather than silently discarded.

Contigs that are recognisable but not standard — scaffolds and decoys — are kept, and simply never match a reference panel.

Four things that fail late rather than early

A standard error is not required by any source but is required by three of the four algorithms. A local GWAS without one declares fine, fetches fine, and fails inside the algorithm.

A local GWAS's contents are not part of its identity. Edit the file, keep the same identifier, re-run — and you get the model built from the old data, with no warning. Version the identifier instead.

A wrong declared build is undetectable. It does not error; it produces a model that overlaps your cohort almost nowhere.

There is no p-value argument on a source. The threshold used for fetching is the loosest one across every algorithm in the call, so pairing a strict clumping threshold with any LD-based method escalates the fetch for everything.

That last one is worth splitting your runs over if you only wanted top hits.