Prepare Case Variant List for PI Estimation Training

Source: R/get_PI_case_data_loader.R

Standardizes and validates trait-associated variant lists for use in PI (variant-importance score) estimation training. This function loads curated lists of known disease/trait-associated variants from literature or GWAS Catalog, applies quality control filters, and generates FAVOR-compatible VarInfo identifiers for annotation retrieval.

prepare_PI_case_data(
  data,
  format = "auto",
  column_mapping = NULL,
  filter_include = NULL,
  filter_exclude = NULL,
  qc_filters = list(remove_duplicates = TRUE, duplicate_priority = "N", filter_autosomes
    = TRUE, filter_indels = FALSE, remove_na = TRUE, remove_na_cols = c("rsID", "CHR",
    "POS")),
  exclude_authors = NULL,
  exclude_chromosomes = NULL,
  verbose = 1
)

Arguments

data

Either a file path (CSV/TSV/Excel) or a data.frame containing trait-associated variant information. Supported formats: .csv, .tsv, .txt, .xlsx, .xls

format

Character string specifying input format: "auto" (default), "gwas_catalog", "csv", "excel", or "dataframe". When "auto", auto-detects from file extension

column_mapping

Named list for custom column name mapping. Specify mappings like list(N = "Sample Size", BETA = "Beta_numeric")

filter_include

Named list for inclusion filters. Only rows matching specified values are kept. Example: list(TRAIT = "ALS", CHR = 1:5). Takes precedence over filter_exclude

filter_exclude

Named list for exclusion filters. Rows matching specified values are removed. Example: list(TRAIT = c("trait1", "trait2")). Ignored for columns in filter_include

qc_filters

List of quality control parameters:

  • remove_duplicates: Remove duplicate rsIDs (default: TRUE)

  • duplicate_priority: Column for duplicate resolution (default: "N")

  • filter_autosomes: Keep only chromosomes 1-22 (default: TRUE)

  • filter_indels: Remove insertion/deletion variants (default: FALSE)

  • remove_na: Remove rows with NA in required columns (default: TRUE)

  • remove_na_cols: Columns requiring non-NA values (default: c("rsID", "CHR", "POS"))

exclude_authors

Character vector of author names to exclude (case-insensitive partial matching). Example: c("Nicolas A", "Smith J"). Useful for removing overlapping studies or specific publications

exclude_chromosomes

Character or numeric vector of chromosomes to exclude. Example: c("X", "Y", "MT") or c(23, 24, 25). Applied before autosome filtering

verbose

Integer controlling verbosity: 0=silent, 1=messages (default), 2=detailed messages

Value

An S3 object of class glow_pi_case_data containing:

  • data: data.frame with standardized columns including:

    • rsID: SNP identifier

    • CHR: Chromosome (numeric 1-22 if filter_autosomes=TRUE)

    • POS: Position

    • REF: Reference allele (may be NA if not available)

    • ALT: Alternate allele (may be NA if not available)

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

    • MAF, P, N, BETA: If available

    • TRAIT, STUDY, PMID, FIRST_AUTHOR: Metadata columns if present

  • metadata: List with processing information:

    • n_input: Number of variants in input data

    • n_output: Number of variants after all filtering

    • n_removed: Number of variants removed

    • format: Detected or specified data format

    • filters_applied: Record of all filters used

    • column_mappings: Which columns were renamed

    • date_prepared: Date of preparation

Details

Processing Pipeline:

The function performs the following operations in sequence:

  • Load Data: Read from file (Excel/CSV/TSV) or accept data.frame

  • Standardize Columns: Map to standard names (rsID, CHR, POS, etc.)

  • Fill Missing Positions: Search alternative columns if POS has NAs

  • Filter by Chromosome: Remove specified chromosomes (if exclude_chromosomes provided)

  • Convert CHR & Filter Autosomes: Numeric CHR, keep 1-22 (if filter_autosomes=TRUE)

  • Apply General Filters: Include/exclude filters on any column

  • Remove Duplicates: By rsID, keep highest priority (if remove_duplicates=TRUE)

  • Filter by Author: Remove specified authors (if exclude_authors provided)

  • Remove NA: In required columns (if remove_na=TRUE)

  • Generate VarInfo: Create CHR-POS-REF-ALT format for FAVOR

  • Sort by Position: Order variants by CHR then POS

  • Reorder Columns: VarInfo first, then standard order

VarInfo Generation:

The VarInfo column is generated in FAVOR-compatible format for annotation:

  • Standard: "1-12345-A-G" (CHR-POS-REF-ALT)

  • Missing alleles: "1-12345-NA-NA" (with warning)

  • Multi-allelic: Takes first ALT allele

Many literature-curated lists lack REF/ALT information. The function accommodates this by using "NA" placeholders, which allows FAVOR to attempt annotation by position.

Duplicate Handling:

When remove_duplicates = TRUE:

  • Duplicates identified by rsID

  • Variant with highest value in duplicate_priority column kept

  • Default: Keep variant with largest sample size (N)

  • Alternative: Set duplicate_priority = "P" to keep lowest p-value

Author Filtering:

The exclude_authors parameter provides flexible author-based filtering:

  • Case-insensitive partial matching

  • Handles name variations: "Nicolas A", "Nicolas A.", "Nicolas"

  • Common use: Remove overlapping studies or low-quality publications

  • Applied before other filters for efficiency

Chromosome Filtering:

Two-stage chromosome filtering:

  1. exclude_chromosomes: Remove specific chromosomes (e.g., "X")

  2. filter_autosomes: If TRUE, keep only CHR 1-22 (default)

This allows flexible control: exclude X but keep Y, or exclude all non-autosomes.

Comparison with prepare_B_training_data():

Key differences:

  • PI case data: Curated trait-associated variants (literature, GWAS Catalog)

  • B training data: GWAS summary statistics (all variants, genome-wide)

  • PI requires: VarInfo generation for FAVOR annotation

  • PI allows: Missing REF/ALT (common in literature)

  • PI adds: Author filtering, more flexible column handling

Computational Complexity:

O(n x f) where n = number of variants, f = number of filters. Dominant operations: duplicate detection O(n log n), filtering O(n x f).

See also

get_PI for PI estimation using prepared case/control data prepare_B_training_data for B estimation data preparation

Examples

if (FALSE) { # \dontrun{
# Example 1: ALS known variants (replicate legacy workflow)
als_data <- prepare_PI_case_data(
  data = "ALS-known-SNPs-raw.xlsx",
  format = "excel",
  column_mapping = list(
    N = "Sample Size",
    BETA = "Beta_numeric"
  ),
  exclude_authors = "Nicolas A",
  exclude_chromosomes = "X",
  qc_filters = list(
    remove_duplicates = TRUE,
    duplicate_priority = "N",
    filter_autosomes = FALSE,  # Already filtered by exclude_chromosomes
    remove_na = FALSE           # Keep variants with missing info
  ),
  verbose = 2
)
# Expected: 297 variants (352 input -> 297 after filtering)

# Example 2: GWAS Catalog download
catalog_data <- prepare_PI_case_data(
  data = "gwas_catalog_v1.0-associations.tsv",
  format = "gwas_catalog",
  filter_include = list(
    `DISEASE/TRAIT` = "Type 2 diabetes"
  ),
  qc_filters = list(
    remove_duplicates = TRUE,
    duplicate_priority = "N",
    remove_na = TRUE,
    remove_na_cols = c("rsID", "CHR", "POS")
  ),
  verbose = 1
)

# Example 3: Custom filtering (multiple criteria)
custom_data <- prepare_PI_case_data(
  data = my_variants_df,
  filter_include = list(
    TRAIT = c("ALS", "FTD"),  # Include only these traits
    CHR = 1:5                  # Only first 5 chromosomes
  ),
  filter_exclude = list(
    PMID = c("12345678", "87654321")  # Exclude specific studies
  ),
  exclude_authors = c("Smith J", "Jones K"),
  verbose = 2
)

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