Skip to contents

Run Common Factor GWAS

Source: R/commonfactorGWAS.R
commonfactorGWAS.Rd

Runs multivariate GWAS with an auto-generated 1-factor model per SNP.

Usage

commonfactorGWAS(
  covstruc = NULL,
  SNPs = NULL,
  estimation = "DWLS",
  cores = NULL,
  toler = FALSE,
  SNPSE = FALSE,
  parallel = TRUE,
  GC = "standard",
  MPI = FALSE,
  TWAS = FALSE,
  smooth_check = FALSE,
  identification = "fixed_variance"
)

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"

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)

TWAS

TWAS gene-level analysis mode (default FALSE)

smooth_check

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

identification

Factor identification strategy: "fixed_variance" (default, fixes F1 variance to 1) or "marker_indicator" (fixes first loading to 1, matching R GenomicSEM's convention). Use "marker_indicator" for exact numerical parity with R GenomicSEM.

Value

Data frame of per-SNP (or per-Gene if TWAS=TRUE) results

Note

gsemr's commonfactorGWAS uses fixed-variance identification and is numerically equivalent to userGWAS on the same 1-factor model. It does NOT match R GenomicSEM::commonfactorGWAS, which uses marker-indicator identification. A first-use warning is emitted per session; suppress it with options(gsemr.commonfactorGWAS.quiet = TRUE). See ARCHITECTURE.md section 3.3 for the full rationale.

Examples

if (FALSE) { # \dontrun{
# Suppress the one-shot compatibility warning if desired:
options(gsemr.commonfactorGWAS.quiet = TRUE)

# `covstruc` from `ldsc()`, merged SNP file from `sumstats()`:
result <- commonfactorGWAS(
  covstruc = covstruc,
  SNPs = "merged_sumstats.tsv",
  estimation = "DWLS",
  GC = "standard"
)
head(result)   # per-SNP est, se, z, p
} # }