GRAB.NullModel: Top-level API for generating a null model object used by GRAB.Marker and GRAB.Region

Description

GRAB performs two-step genetic association testing. This function implements the first step: fitting a null model and preparing the dataset required for downstream marker-level (GRAB.Marker) and region-level (GRAB.Region) analyses.

Usage

GRAB.NullModel(
  formula,
  data,
  subjIDcol = NULL,
  subjData = NULL,
  method,
  traitType,
  GenoFile = NULL,
  GenoFileIndex = NULL,
  SparseGRMFile = NULL,
  control = NULL,
  ...
)

Value

An S3 object with class "{method}_NULL_Model". All returned objects contain the following elements:

N: Sample size (integer).
subjData: Character vector of subject IDs included in analysis.
Call: Original function call.
sessionInfo: R session and package information.
time: Analysis completion timestamp (character).
control: List of control parameters used in fitting.

This object serves as input for GRAB.Marker or GRAB.Region.

See method-specific documentation for additional elements included in the returned object.

Arguments

formula

(formula) Formula with response variable(s) on the left and covariates on the right. Do not include an intercept (added automatically). For SPAmix with traitType "Residual", multiple response variables (separated by "+") are supported.

data

(data.frame) Data frame containing response variables and covariates in the formula. Parameter "subset" is deprecated. All subjects with phenotype data will be used. Missing values should be coded as NA. Other values (e.g., -9, -999) are treated as numeric.

subjIDcol

(character or NULL) Column name in data containing subject IDs.

subjData

(character vector or NULL) Subject IDs aligned with rows of data. Exactly one of subjIDcol or subjData must be provided.

method

(character) Supported methods:

"POLMM": Ordinal traits. See ?GRAB.POLMM.
"SPACox": Time-to-event or Residual. See ?GRAB.SPACox.
"SPAmix": Time-to-event or Residual. See ?GRAB.SPAmix.
"WtCoxG": Time-to-event traits. See ?GRAB.WtCoxG.

traitType

(character) Supported: "ordinal", "time-to-event", and "Residual".

GenoFile

(character or NULL) Path to genotype file. Supported formats determined by extension:

PLINK: "prefix.bed"
BGEN: "prefix.bgen" (version 1.2 with 8-bit compression)

GenoFileIndex

(character vector or NULL) Associated files for the genotype file (auto-detected if NULL):

PLINK: c("prefix.bim", "prefix.fam")
BGEN: c("prefix.bgen.bgi", "prefix.sample") or c("prefix.bgen.bgi")

SparseGRMFile

(character or NULL) Path to a sparse GRM file. The file must be whitespace-delimited with three columns in the order:

Column 1: Subject ID 1
Column 2: Subject ID 2
Column 3: Genetic correlation between the two subjects

See system.file("extdata", "SparseGRM.txt", package = "GRAB") for an example. See ?getSparseGRM for details on generating a sparse GRM.

control

(list or NULL) List of additional, less commonly used parameters. See the corresponding method documentation for available options and defaults.

...

Additional method-specific parameters.