Create a GwasSumStats Collection Object

Construct a GwasSumStats S4 DFrame-subclass collection from per-study tuple vectors and a list of GRanges entries (one per study), plus a single LD reference and a single genome build that apply to the whole collection.

Each GRanges entry must carry per-variant statistics in its mcols (at minimum SNP, A1, A2, Z, N; optionally MAF, INFO, BETA, SE, P).

Usage

GwasSumStats(
  studyName,
  entry,
  genome,
  ldReference = NULL,
  varY = NA_real_,
  nCase = NULL,
  nControl = NULL,
  nSample = NULL,
  qcInfo = list(),
  ldBlocks = NULL,
  blockId = NULL,
  extraCols = list()
)

Arguments

studyName

Character vector of study identifiers (must be unique).

entry

A SimpleList or list of GRanges, one per study.

genome

Single character string giving the genome build (e.g., "hg19", "hg38"). Uniform across the collection because all entries share the same LD reference.

ldReference

The LD reference: a genotype panel (see readGenotypes), a GenotypeMixture or an LdMatrix.

varY

Optional numeric vector of per-study phenotype variances (NA_real_ entries allowed). Used by the sufficient-statistic interface; z-score RSS analyses should leave entries as NA.

nCase, nControl

Optional per-study case / control counts. The columns are attached only when supplied (default NULL), so quantitative-trait collections keep the original schema. When given, pass length 1 or length(study) (use NA for the non-case/control studies in a mixed collection). For case/control GWAS, downstream consumers (e.g. colocboostPipeline) use the effective sample size 4 / (1/nCase + 1/nControl) in place of the per-variant N.

nSample

Optional per-study total sample size (numeric; default NULL). Attached only when supplied (length 1 or length(study)). Used as the study-level fallback for the per-variant N when a study has no per-variant N column and no case/control counts. Named nSample to avoid clashing with nSamples() (the LD-panel sample size).

qcInfo

A list recording which QC steps ran. Empty list() on construction; populated by summaryStatsQc() with a per-step audit record. Fine-mapping / TWAS pipelines reject inputs where length(qcInfo(x)) == 0.

ldBlocks

Optional LD-block specification: a GRanges, a data.frame with chrom/start/end (plus an optional blockId), or a path to such a table. When supplied, each study's variants are split into one element per block rather than one per chromosome, and blockId takes the block's key (its names, else a blockId metadata column, else its coordinates). cTWAS needs this granularity: its EM estimates parameters across blocks, so a per-chromosome split is too coarse. Variants overlapping no block are dropped with a warning, because a variant outside every block has no block-local LD to be fine-mapped against.

blockId

Optional character vector of block keys, one per entry, for entries that are already split by block. Use it to carry existing keys through a rebuild; without it a rebuild would re-derive them as seqnames and collapse distinct blocks onto one key. Mutually exclusive with ldBlocks.

extraCols

Optional named list of additional per-study columns to attach to the collection's mcols. Named rather than variadic because the base class's own constructor, GRangesList(...), uses ... for its elements: a bare ... here would read as adding an entry rather than a metadata column.

Value

A GwasSumStats object.

Examples

panel <- readGenotypes(
  system.file("extdata", "toy_ref.bed", package = "pecotmr"))
gr <- GenomicRanges::GRanges("chr1", IRanges::IRanges(100 * 1:3, width = 1))
S4Vectors::mcols(gr) <- S4Vectors::DataFrame(SNP = paste0("rs", 1:3),
  A1 = "A", A2 = "G", Z = rnorm(3), N = 100L)
GwasSumStats(studyName = "t1", entry = list(gr), genome = "hg38",
  ldReference = panel)
#> GwasSumStats: 1 studies, genome build hg38
#>   LD reference: plink1 @ /tmp/RtmpmBLZhq/temp_libpathaae388f3498/pecotmr/extdata/toy_ref