GRAB.POLMM: Instruction of POLMM method

Description

POLMM inplements single-variant association tests for ordinal categorical phenotypes, which accounts for sample relatedness. It can control type I error rates at a stringent significance level regardless of the phenotypic distribution, and is more powerful than alternative methods. This instruction covers null model fitting and marker-level analysis using POLMM. For region-based analysis with POLMM-GENE, see GRAB.POLMM.Region.

Usage

GRAB.POLMM()

Arguments

Details

Genotype file: GenoFile is mandatory for GRAB.NullModel() when using POLMM. It is required for estimating the variance ratio parameter, which is essential for calibrating the test statistics in subsequent association tests.

Genetic Relationship Matrix (GRM) Options: POLMM supports both sparse and dense GRM for modeling genetic relatedness:

If SparseGRMFile is provided to GRAB.NullModel(), the sparse GRM will be used in model fitting.
If SparseGRMFile is not provided, GRAB.NullModel() will calculate a dense GRM from GenoFile.

Additional Control Parameters for GRAB.NullModel():

memoryChunk (numeric, default: 2): Memory chunk size for computation.
seed (integer, default: -1): Random seed (-1 means no seed is set).
tracenrun (integer, default: 30): Number of runs for trace calculation.
maxiter (integer, default: 100): Maximum number of iterations for model fitting.
tolBeta (numeric, default: 0.001): Convergence tolerance for beta estimates.
tolTau (numeric, default: 0.002): Convergence tolerance for tau estimates.
tau (numeric, default: 0.2): Initial variance component value.
maxiterPCG (integer, default: 100): Maximum iterations for preconditioned conjugate gradient.
tolPCG (numeric, default: 1e-6): Tolerance for preconditioned conjugate gradient.
showInfo (logical, default: FALSE): Whether to print PCG iteration information for debugging.
maxiterEps (integer, default: 100): Maximum iterations for epsilon estimation.
tolEps (numeric, default: 1e-10): Tolerance for epsilon estimation.
minMafVarRatio (numeric, default: 0.1): Minimum MAF for variance ratio estimation.
maxMissingVarRatio (numeric, default: 0.1): Maximum missing rate for variance ratio estimation.
nSNPsVarRatio (integer, default: 20): Number of SNPs used for variance ratio estimation.
CVcutoff (numeric, default: 0.0025): Coefficient of variation cutoff.
grainSize (integer, default: 1): Grain size for parallel processing.
minMafGRM (numeric, default: 0.01): Minimum MAF for GRM construction.
maxMissingGRM (numeric, default: 0.1): Maximum missing rate for GRM construction.

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

M: Number of ordinal categories (integer).
iter: Number of iterations to convergence (numeric).
eta: Linear predictor (matrix).
yVec: Phenotype matrix (matrix).
Cova: Design matrix of covariates (matrix).
muMat: Fitted probabilities for each category (matrix).
YMat: Indicator matrix for ordinal categories (matrix).
beta: Estimated covariate coefficients (matrix).
bVec: Random effect estimates (matrix).
tau: Variance component estimate (numeric).
eps: Cutpoints for ordinal categories (matrix).

Additional Control Parameters for GRAB.Marker():

ifOutGroup (logical, default: FALSE): Whether to output group-specific statistics (alternative allele frequency, counts, and sample size for each ordinal category). When TRUE, adds columns AltFreqInGroup., AltCountsInGroup., and nSamplesInGroup.* to the output file.

Marker-level results (OutputFile) columns:

Marker: Marker identifier (rsID or CHR:POS:REF:ALT).
Info: Marker information in format CHR:POS:REF:ALT.
AltFreq: Alternative allele frequency in the overall sample.
AltCounts: Total count of alternative alleles.
MissingRate: Proportion of missing genotypes.
Pvalue: P-value from the score test.
beta: Effect size estimate (log-odds scale).
seBeta: Standard error of beta.
zScore: Z-score from the score test.
AltFreqInGroup.1, AltFreqInGroup.2, ...: (Only if ifOutGroup = TRUE) Alternative allele frequency in each ordinal category.
AltCountsInGroup.1, AltCountsInGroup.2, ...: (Only if ifOutGroup = TRUE) Alternative allele counts in each ordinal category.
nSamplesInGroup.1, nSamplesInGroup.2, ...: (Only if ifOutGroup = TRUE) Sample size in each ordinal category.

References

Bi et al. (2021). Efficient mixed model approach for large-scale genome-wide association studies of ordinal categorical phenotypes. tools:::Rd_expr_doi("10.1016/j.ajhg.2021.03.019")

Examples

Run this code

GenoFile <- system.file("extdata", "simuPLINK.bed", package = "GRAB")
SparseGRMFile <- system.file("extdata", "SparseGRM.txt", package = "GRAB")
OutputFile <- file.path(tempdir(), "resultPOLMMmarker.txt")

PhenoFile <- system.file("extdata", "simuPHENO.txt", package = "GRAB")
PhenoData <- data.table::fread(PhenoFile, header = TRUE)
PhenoData$OrdinalPheno <- factor(PhenoData$OrdinalPheno, levels = c(0, 1, 2))
# Step 1
obj.POLMM <- GRAB.NullModel(
 OrdinalPheno ~ AGE + GENDER,
 data = PhenoData,
 subjIDcol = "IID",
 method = "POLMM",
 traitType = "ordinal",
 GenoFile = GenoFile,
 SparseGRMFile = SparseGRMFile
)

# Step 2
GRAB.Marker(obj.POLMM, GenoFile, OutputFile,
  control = list(ifOutGroup = TRUE))

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

Run the code above in your browser using DataLab