Extract Phenotype and Covariates from GDS File

Source: R/marginal_scan.R

Reads sample annotation fields from a GDS file and prepares them for null model fitting. Handles PLINK phenotype encoding and covariate conversions.

extract_pheno_covar_gds(
  gds_file,
  pheno_name = "phenotype",
  covar_names = NULL,
  pheno_coding = "plink",
  verbose = 1
)

Arguments

gds_file

Character path to GDS file.

pheno_name

Character name of the sample.annotation field containing the phenotype. Default: "phenotype".

covar_names

Character vector of sample.annotation field names to use as covariates. Default: NULL (no covariates beyond intercept).

pheno_coding

Character encoding scheme for phenotype values. "plink" (1=control, 2=case, -9=missing) or "01" (already 0/1). Default: "plink".

verbose

Integer verbosity level (0=silent, 1=progress, 2=detailed).

Value

A list with components:

sample_id

Character vector of sample IDs (missing-phenotype samples excluded)

Y

Numeric response vector (0/1 for binary)

X

Numeric covariate matrix (columns named by covar_names), or NULL if no covariates

trait

Character: "binary" or "continuous" (auto-detected)

n_total

Integer: total samples in GDS

n_excluded

Integer: samples excluded due to missing phenotype

Details

Opens the GDS file read-only using SeqArray and reads sample annotation nodes. Phenotype encoding is applied before missing-value filtering, so PLINK sentinel values (-9) are converted to NA and those samples are excluded. Character covariates are converted: sex (M/F) becomes 1/0; other character covariates become integer factor codes minus 1.

Trait type is auto-detected after encoding: if all non-missing values are in {0, 1} the trait is "binary", otherwise "continuous".

Complexity: O(n) in sample count. The GDS file is opened and closed within this call.

Examples

if (FALSE) { # \dontrun{
pheno <- extract_pheno_covar_gds(
  "chr22.gds",
  pheno_name   = "phenotype",
  covar_names  = c("sex", "age"),
  pheno_coding = "plink",
  verbose      = 1
)
head(pheno$Y)
dim(pheno$X)
} # }