GRAB (version 0.2.4)

GRAB.SPAmix: Instruction of SPAmix method

Description

SPAmix performs retrospective single-variant association tests using genotypes and residuals from null models of any complex trait in large-scale biobanks. It extends SPACox to support complex population structures, such as admixed ancestry and multiple populations, but does not account for sample relatedness.

Usage

GRAB.SPAmix()

Details

Additional Control Parameters for GRAB.NullModel():

• PC_columns (character, required): Comma-separated column names of principal components (e.g., "PC1,PC2").

• OutlierRatio (numeric, default: 1.5): IQR multiplier for outlier detection. Outliers are defined as values outside [Q1 - rIQR, Q3 + rIQR].

Method-specific elements in the SPAmix_NULL_Model object returned by GRAB.NullModel()::

• resid: Residuals from mixed model (matrix or "Residual" class).

• yVec: Phenotype vector (numeric or "Residual" class).

• PCs: Principal components for dimension reduction (matrix).

• nPheno: Number of phenotypes analyzed (integer).

• outLierList: List identifying outlier subjects for SPA adjustment.

Additional Control Parameters for GRAB.Marker():

• dosage_option (character, default: "rounding_first"): Dosage handling option. Must be either "rounding_first" or "rounding_last".

Output file columns:

Pheno

Phenotype identifier (for multi-trait analysis).

Marker

Marker identifier (rsID or CHR:POS:REF:ALT).

Info

Marker information in format CHR:POS:REF:ALT.

AltFreq

Alternative allele frequency in the sample.

AltCounts

Total count of alternative alleles.

MissingRate

Proportion of missing genotypes.

Pvalue

P-value from the score test.

zScore

Z-score from the score test.

References

Ma et al. (2025). SPAmix: a scalable, accurate, and universal analysis framework for large‑scale genetic association studies in admixed populations. tools:::Rd_expr_doi("10.1186/s13059-025-03827-9")

Examples

PhenoFile <- system.file("extdata", "simuPHENO.txt", package = "GRAB")
GenoFile <- system.file("extdata", "simuPLINK.bed", package = "GRAB")
OutputFile <- file.path(tempdir(), "resultSPAmix.txt")
PhenoData <- data.table::fread(PhenoFile, header = TRUE)

# Step 1 option 1
obj.SPAmix <- GRAB.NullModel(
  survival::Surv(SurvTime, SurvEvent) ~ AGE + GENDER + PC1 + PC2,
  data = PhenoData,
  subjIDcol = "IID",
  method = "SPAmix",
  traitType = "time-to-event",
  control = list(PC_columns = "PC1,PC2")
)

# Step 1 option 2
residuals <- survival::coxph(
  survival::Surv(SurvTime, SurvEvent) ~ AGE + GENDER + PC1 + PC2,
  data = PhenoData
)$residuals

obj.SPAmix <- GRAB.NullModel(
  residuals ~ AGE + GENDER + PC1 + PC2,
  data = PhenoData,
  subjIDcol = "IID",
  method = "SPAmix",
  traitType = "Residual",
  control = list(PC_columns = "PC1,PC2")
)

# Step 1 option 2: analyze multiple traits at once
res_cox <- survival::coxph(
  survival::Surv(SurvTime, SurvEvent) ~ AGE + GENDER + PC1 + PC2,
  data = PhenoData
)$residuals

res_lm <- lm(QuantPheno ~ AGE + GENDER + PC1 + PC2, data = PhenoData)$residuals

obj.SPAmix <- GRAB.NullModel(
  res_cox + res_lm ~ AGE + GENDER + PC1 + PC2,
  data = PhenoData,
  subjIDcol = "IID",
  method = "SPAmix",
  traitType = "Residual",
  control = list(PC_columns = "PC1,PC2")
)

# Step 2
GRAB.Marker(obj.SPAmix, GenoFile, OutputFile)

head(data.table::fread(OutputFile))