ras_harmonize_sumstats: Harmonise External GWAS Summary Statistics into RAS Weights

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

Harmonise External GWAS Summary Statistics into RAS Weights

Description

The entry point for summary-informed RAS. Takes a raw external summary-statistics file and a local genotype map, chooses the naming/build route from the data rather than from an assumption, and returns a verified weight vector together with a reproducible QC table.

Usage

ras_harmonize_sumstats(
  sumstats,
  map,
  dict = NULL,
  chain = NULL,
  chain_back = NULL,
  cup = NULL,
  converter = .liftover_converter_ucsc,
  check_reverse = TRUE,
  assume_same_build = FALSE,
  cols = list(),
  ...
)

Arguments

sumstats	Path to the external summary statistics, or a data frame.
map	Data frame with columns SNP, CHR, BP, A1, A2: the local genotype map, one row per genotype column, in order. A1 must be the allele the local dosage counts.
dict	Optional variant dictionary ON THE MAP'S BUILD, from ras_read_variant_dictionary. Enables the dictionary route, which fixes a naming disagreement without touching any coordinate.
chain, chain_back	Optional liftOver chain files, enabling the coordinate-conversion route. chain_back is required unless check_reverse = FALSE.
cup	Optional data frame (CHR, START, END) of conversion-unstable intervals on the source build, passed to the liftOver route.
converter	Conversion function for the liftOver route; the default shells out to the UCSC liftOver binary.
check_reverse	Logical. Round-trip every liftOver conversion and drop what cannot return to its own position (default TRUE).
assume_same_build	Logical. Assert, on the caller's authority, that both sides use the same genome build. Only then will positions be used without the build gate having verified them. Appropriate when the summary statistics are a GWAS Catalog harmonised (GRCh38) file and the map is GRCh38.
cols	Optional column-name overrides, passed through.
...	Passed to ras_weights_from_sumstats, e.g. drop_ambiguous, match_min_prop, target_af, block_size.

Details

The driver never guesses about the genome build. It inspects both sides' ID conventions and then either matches directly, translates the summary statistics through a dictionary, lifts their coordinates over, or refuses – listing exactly what would unblock it. Every path ends at ras_weights_from_sumstats with build_check = TRUE unless the caller has explicitly asserted the builds agree or a liftOver round trip has already established them.

Value

A list with

weights	Numeric vector of length nrow(map), ready to pass to ras_scan_external.
qc	A data frame with one row per harmonisation stage (item, n, denom, pct): external variants read, dropped for a missing beta, dropped as duplicates, matched by rsID, matched by position, absent from the target, allele-aligned, allele-flipped, palindromic removed, and final usable weights. Written to be quoted directly in a manuscript.
route	The route actually taken.
trail	Human-readable audit trail of every decision.
weights_result	The full ras_weights_from_sumstats result, including detail, build and blocks.
sumstats_aligned	The summary statistics after any translation or conversion.

See Also

ras_scan_external to scan with these weights; ras_sumstats_report to inspect an alignment without committing to it.

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