ras_weights_from_sumstats: Align External GWAS Summary Statistics to a Local Genotype...

In RAS: Regional Association Score for Genome-Wide Association Studies

Align External GWAS Summary Statistics to a Local Genotype Map

Description

Turns an external GWAS's effect estimates into a weight vector aligned to a local genotype matrix, one weight per genotype column, in order. This is the matcher underneath ras_harmonize_sumstats; call that instead unless you have already settled the naming and build questions yourself.

Usage

ras_weights_from_sumstats(
  sumstats,
  map,
  cols = list(),
  drop_ambiguous = TRUE,
  on_or = TRUE,
  match_by = c("id", "pos"),
  match_min_prop = 0.2,
  build_check = TRUE,
  target_af = NULL,
  af_tol = 0.2,
  block_size = 500L,
  pos_fallback = NULL
)

Arguments

sumstats	Path to a whitespace/tab-delimited file, or a data frame. Column names are auto-detected across PLINK 1/2 and GWAS-SSF conventions; GWAS Catalog hm_* columns take precedence, being the authoritative harmonised values. A PLINK TEST column is filtered to ADD.
map	Data frame with columns SNP, A1, A2 (and CHR, BP when position matching or the build gate is wanted) describing the LOCAL genotype matrix, one row per column of the genotype data, in order. A1 must be the allele the local dosage COUNTS.
cols	Optional named list overriding auto-detected columns, e.g. list(snp = "MarkerName", a1 = "Allele1", beta = "Effect").
drop_ambiguous	Logical. Drop strand-ambiguous A/T and C/G variants (default TRUE).
on_or	Logical. If the file carries OR instead of BETA, take log(OR) (default TRUE).
match_by	"id", "pos", or c("id","pos") (the default) to try IDs first and retry the leftovers on chr:pos. Position matching REQUIRES the build gate to pass, or to be switched off deliberately. The two keys are not interchangeable and neither is redundant. An rsID survives a change of genome build but is NOT unique – multi-allelic sites share one, and a real WGS file has about 1.25\ chr:pos:alleles is far sharper but is meaningless across builds, and indel anchoring conventions make it fragile. Not every variant carries an rsID at all, which is the case position matching exists for. They also stand in a specific order of dependence: the build gate can only compare positions on variants BOTH sides name, so the ID-matched subset is what licenses the position matching that then covers the variants without rsIDs. Using "pos" alone leaves nothing able to show it matched the right variants.
match_min_prop	Numeric. Stop if fewer than this proportion of the smaller dataset ends up with a usable weight (default 0.2, the guard bigsnpr::snp_match() uses). A low match rate is the standard symptom of a wrong build or an ID-convention mismatch.
build_check	Logical. Verify that ID-matched variants agree on position (default TRUE). Set FALSE only when the builds have been confirmed by other means; doing so while match_by includes "pos" is the one configuration that can silently produce spatially truncated weights.
target_af	Optional numeric vector, length nrow(map), giving the frequency of map$A1 in the TARGET cohort. When supplied and the summary statistics carry an effect-allele frequency column, the two are compared after orientation and reported. Purely diagnostic: no variant is ever dropped on a frequency disagreement, because a real frequency difference between cohorts is expected and is not an error.
af_tol	Numeric. Absolute frequency difference above which a variant is counted as discordant in that report (default 0.20).
block_size	Integer. Window, in variants along the local map, for the match-rate profile returned in blocks.
pos_fallback	Deprecated, kept so old calls still run. TRUE maps to match_by = c("id","pos"), FALSE to match_by = "id".

Details

The alignment rule is deliberately conservative:

• w_j = +\beta_j when the summary statistics' effect allele is the allele the local dosage counts (map$A1);

• w_j = -\beta_j when it is the other allele (map$A2);

• w_j = 0 when the variant is absent, the alleles cannot be reconciled, or (with drop_ambiguous = TRUE) the variant is strand-ambiguous.

Strand-ambiguous (A/T, C/G) variants are removed rather than rescued. Rescuing them requires a frequency rule, which is a modelling decision this layer does not make.

Value

A list with

weights	Numeric vector of length nrow(map): the aligned weights, zero wherever no usable weight exists.
qc	The reproducible harmonisation QC table (see ras_harmonize_sumstats).
report	Per-status variant counts.
detail	One row per map variant: status, matching route, sign, weight.
matched_by	Counts matched by ID, by ID+alleles, and by position.
build	The build gate's verdict.
blocks	Match rate along the chromosome, in block_size windows.
af	The allele-frequency comparison, when target_af was given.

See Also

ras_harmonize_sumstats for the driver that chooses the naming/build route first; ras_scan_external to scan with the resulting weights.

RAS documentation built on Nov. 3, 2026, 1:07 a.m.