Prepare Control Variant List for PI Estimation Training

Source: R/get_PI_control_data_loader.R

Prepares control (neutral/non-causal) variant lists for PI estimation training. Supports multiple input formats with GDS as the unified intermediate format for genotype data. Control variants are used to estimate the null distribution of variant-importance scores in the GLOW framework.

prepare_PI_control_data(
  source,
  format = "auto",
  strategy = "provided",
  n_controls = NULL,
  gds_output = NULL,
  random_seed = NULL,
  verbose = 1
)

Arguments

source

Character or data.frame. Input source:

  • PLINK prefix (without .bed/.bim/.fam extension)

  • Path to GDS file (.gds)

  • Path to CSV file (.csv)

  • data.frame with variant information

format

Character. Input format: "auto" (default), "plink", "gds", "csv", "dataframe". When "auto", format is detected from file extension or object type.

strategy

Character. Control selection strategy (Phase 1: only "provided"):

  • "provided" (default): Use all variants from source as controls

Future strategies: "synonymous", "intergenic", "common" (requires annotation)

n_controls

Integer or NULL. If specified, randomly sample to this number of variants. If NULL (default), use all variants from source.

gds_output

Character or NULL. When format="plink", path to save the intermediate GDS file. If NULL (default), creates a temporary file that is deleted after variant extraction. Set this to save GDS for reuse in pipeline workflows.

random_seed

Integer or NULL. Seed for reproducible random sampling when n_controls is specified. Use this for reproducible training sets.

verbose

Integer. Verbosity level: 0=silent, 1=messages (default), 2=detailed.

Value

An S3 object of class glow_pi_control_data containing:

  • data: data.frame with columns:

    • VarInfo: FAVOR format "CHR-POS-REF-ALT"

    • rsID: Variant identifier (from GDS annotation/id, or NA)

    • CHR: Chromosome (character or numeric)

    • POS: Position (integer)

    • REF: Reference allele

    • ALT: Alternate allele

  • metadata: List with:

    • n_input: Number of variants in source

    • n_output: Number of variants after sampling

    • format: Detected or specified format

    • gds_path: Path to GDS file (if created/used)

    • gds_persistent: Whether GDS was saved permanently

    • strategy: Control selection strategy used

    • random_seed: Seed used (if sampling performed)

    • date_prepared: Date of preparation

Details

Processing Pipeline (format="plink"):

  1. Convert PLINK to GDS using plink_to_gds

  2. Extract variant information from GDS (CHR, POS, REF, ALT, rsID)

  3. Generate VarInfo column in FAVOR format (CHR-POS-REF-ALT)

  4. Random sample if n_controls specified

  5. Delete temp GDS if gds_output is NULL

Processing Pipeline (format="gds"):

  1. Open GDS file (read-only)

  2. Extract variant information from GDS

  3. Generate VarInfo column

  4. Random sample if n_controls specified

Processing Pipeline (format="csv" or "dataframe"):

  1. Load data from CSV or accept data.frame

  2. Validate required columns (CHR, POS, REF, ALT)

  3. Generate VarInfo column

  4. Random sample if n_controls specified

GDS as Canonical Format:

GDS (Genomic Data Structure) serves as the unified intermediate format in GLOWpipeline. This design ensures:

  • Consistent variant representation across input formats

  • Efficient extraction of variant information

  • Integration with downstream pipeline steps (aGDS, FAVOR)

  • Optional persistence for pipeline reuse

Control Variant Selection:

Phase 1 implementation uses "provided" strategy: all variants from the source are treated as controls. Users are responsible for providing appropriate control variants (e.g., common synonymous variants, intergenic variants).

Future strategies (requires FAVOR annotation):

  • "synonymous": Filter to synonymous variants

  • "intergenic": Filter to intergenic variants

  • "common": Filter to common variants (MAF > threshold)

Random Sampling:

When n_controls is specified:

  • Random sampling without replacement

  • Set random_seed for reproducibility

  • Sampling applied after format conversion

  • If n_controls > available variants, uses all variants with warning

Computational Complexity:

  • PLINK format: O(n x m) for conversion + O(n) for extraction

  • GDS format: O(n) for extraction

  • CSV format: O(n) for reading

  • Random sampling: O(n)

where n = number of variants, m = number of samples.

See also

plink_to_gds for PLINK to GDS conversion get_PI for PI estimation using prepared control data prepare_PI_case_data for case variant preparation

Examples

if (FALSE) { # \dontrun{
# Example 1: From PLINK files (GDS saved permanently for reuse)
controls <- prepare_PI_control_data(
  source = "data/reference_panel",
  format = "plink",
  gds_output = "data/reference_panel.gds",
  verbose = 1
)

# Example 2: From PLINK files (temp GDS, deleted after use)
controls <- prepare_PI_control_data(
  source = "data/reference_panel",
  format = "plink",
  gds_output = NULL,  # Default: temp file
  verbose = 1
)

# Example 3: From existing GDS
controls <- prepare_PI_control_data(
  source = "data/reference_panel.gds",
  format = "gds"
)

# Example 4: With random sampling (reproducible)
controls <- prepare_PI_control_data(
  source = "data/reference_panel.gds",
  n_controls = 1000,
  random_seed = 42,
  verbose = 1
)

# Example 5: From CSV file with variant list
controls <- prepare_PI_control_data(
  source = "data/control_variants.csv",
  format = "csv"
)

# Example 6: From data.frame
control_df <- data.frame(
  CHR = c(1, 1, 2),
  POS = c(12345, 67890, 11111),
  REF = c("A", "G", "C"),
  ALT = c("G", "T", "T")
)
controls <- prepare_PI_control_data(
  source = control_df,
  format = "dataframe"
)

# Access results
print(controls)
summary(controls)
head(controls$data)
str(controls$metadata)
} # }