Skip to contents

Run User-Specified GWAS

Source: R/userGWAS.R
userGWAS.Rd

Runs multivariate GWAS with a user-specified SEM model per SNP.

Usage

userGWAS(
  covstruc = NULL,
  SNPs = NULL,
  estimation = "DWLS",
  model = "",
  printwarn = TRUE,
  sub = FALSE,
  cores = NULL,
  toler = FALSE,
  SNPSE = FALSE,
  parallel = TRUE,
  GC = "standard",
  MPI = FALSE,
  smooth_check = FALSE,
  TWAS = FALSE,
  std.lv = FALSE,
  fix_measurement = TRUE,
  Q_SNP = FALSE
)

Arguments

covstruc

LDSC result (named list with S, V, I, N, m components)

SNPs

Path to merged summary statistics file

estimation

Estimation method: "DWLS" (default) or "ML"

model

lavaan-style model syntax

printwarn

Print warnings (default TRUE; FALSE suppresses Rust warnings)

sub

Subset of results to return (default FALSE = all)

cores

Integer cap on the rayon worker pool size used for the per-SNP fit loop. When NULL (the default) rayon honours RAYON_NUM_THREADS if set, else it uses the number of logical cores reported by the OS. On many-core machines (32+) or when the underlying BLAS is multithreaded, set this explicitly to avoid oversubscribing CPUs with nested BLAS threads.

toler

Tolerance (accepted; convergence controlled by L-BFGS internally)

SNPSE

SNP SE override (default FALSE = auto)

parallel

Use a parallel rayon worker pool for the per-SNP fit loop (default TRUE). Set to FALSE to force single-threaded execution.

GC

Genomic control: "standard" (default), "conservative", or "none"

MPI

Use MPI (ignored in gsemr – not applicable to Rust backend)

smooth_check

Check for non-positive-definite matrices (default FALSE)

TWAS

TWAS gene-level analysis mode (default FALSE)

std.lv

Standardize latent variables (default FALSE)

fix_measurement

Fix measurement model (default TRUE)

Q_SNP

Compute Q_SNP heterogeneity statistic (default FALSE)

Value

A two-element list in normalized relational form:

snps

One row per SNP with columns SNP, CHR, BP, MAF, A1, A2, chisq, df, converged (plus Q_chisq, Q_df, Q_pval when Q_SNP = TRUE).

params

Flat parameter table with columns SNP, lhs, op, rhs, est, se, z, p; join to snps on SNP.

When TWAS = TRUE the first slot is named genes with columns Gene, Panel, HSQ, chisq, df, converged; the params table uses Gene in place of SNP.

Note

This replaces the earlier one-row-per-SNP-with-list-column shape; the old layout made R reconstruction O(N) `data.frame()` calls and hung at multi-million-SNP scale. Example filters: `result$params[result$params$SNP == "rsXXXX", ]` for one SNP, or `result$params[result$params$op == "~" & result$params$rhs == "SNP", ]` for every SNP's regression effect.

Examples

if (FALSE) { # \dontrun{
# `covstruc` from `ldsc()`, `merged_sumstats.tsv` from `sumstats()`.
result <- userGWAS(
  covstruc = covstruc,
  SNPs = "merged_sumstats.tsv",
  model = "F1 =~ NA*V1 + V2 + V3\nF1 ~ SNP\nF1 ~~ 1*F1"
)
# Per-SNP metadata:
head(result$snps)
# SNP regression effects (F1 ~ SNP) across all SNPs:
head(result$params[result$params$op == "~" & result$params$rhs == "SNP", ])
} # }