Load Control Annotations from CSV or GDS

Loads annotation features from pre-annotated control variants. Supports single file or directory with per-chromosome files.

load_control_annotations(
  source,
  features = .default_PI_features(),
  chromosomes = 1:22,
  format = "auto",
  max_controls = NULL
)

Arguments

source

Path to either:

• A single CSV or GDS file

• A directory containing chr*.csv or chr*.gds files

features

Character vector of annotation column names to extract. Default: 11 FAVOR features.

chromosomes

Integer vector of chromosomes to include when loading from a directory. Default: 1:22 (all autosomes).

format

File format: "auto" (detect from extension), "csv", or "gds".

max_controls

Maximum number of control variants to return. If source contains more variants, proportional sampling is performed during file loading to limit memory usage. Default: NULL (all). Note: Random seed should be set before calling this function for reproducible sampling.

Value

Numeric matrix with dimensions (N_variants x M_features). Row names are set to VarInfo values. May contain NA values.

Details

When source is a directory, the function scans for files matching chr{N}_*.csv or chr{N}_*.gds patterns and loads only those corresponding to the requested chromosomes.

Memory Management

When max_controls is set and loading from a directory, proportional sampling is performed during loading (not after). Each chromosome file contributes variants proportional to its size, so memory usage is bounded by max_controls regardless of total dataset size.

Examples

if (FALSE) { # \dontrun{
# Load from directory with chr1-22 CSVs (sample 100K)
ctrl_annot <- load_control_annotations(
  "/path/to/favor_csv/",
  max_controls = 100000
)

# Load specific chromosomes
ctrl_annot <- load_control_annotations(
  "/path/to/favor_csv/",
  chromosomes = c(21, 22)
)
} # }