Genomic prediction skill

Genomic Prediction Blueprints

This skill provides execution blueprints and templates for implementing established genomic prediction models using official software packages. Always use these validated implementations rather than writing custom approximation scripts.

1. Core Operating Principles

• No Workarounds: Never attempt to build custom approximations, pseudo-code fallbacks, or shortcuts to bypass execution errors.
• No Silent Fallbacks: If required input variables/metadata are missing, explicitly flag the missing data, abort, and report. Do not use pseudo-valid inputs.
• Robust Self-Auditing: Critically analyze pipelines to ensure alignment with scientific rigor. Use official methods; flag custom pseudo-implementations.

2. Environment and Data Prerequisites

• R Packages: qgg, rrBLUP, BGLR, randomForest or ranger.
• Stand-alone Executables: FAANG/BayesRCO, LDAK.
• Data Formats: Phenotypes in standard vectors/dataframes. Genotypes as numeric matrices (e.g., 0, 1, 2) or standard formats (PLINK bed/bim/fam).
• Data Transfer Architecture: Always transfer genomic dataset pathways using binary files (e.g., binary streams via R's readBin/Python's np.tofile, .rds objects, HDF5, or PLINK formats) and index-level metadata. NEVER serialize large biological data matrices into text formats like JSON or XML for inter-process communication.

3. High-Clarity Structured Code Commenting

• Structured Section Banners: ALWAYS organize code scripts into distinct, numbered sections (e.g., # SECTION 1: ...) separated by visual block headers (# ==============================================================================).
• At-a-Glance Readability: Every functional code chunk must begin with a clear explanatory header.
• Scope-Specific & Conceptual Clarity: Limit comments to describing what the script actually executes. For algorithm parameters, ALWAYS include a concise explanation of what the parameters mean biologically/mathematically and how they operate dynamically.

4. Performance & Big Data Best Practices

• Scalability: Design all wrappers and parsers for target dataset scales (e.g., $M > 250,000$).
• Strict Accession-to-Phenotype Alignment: Always implement explicit runtime assertions comparing the exact length and sorting order of sample/accession IDs between the phenotype target vector, the genotype matrix rows, and covariance/GRM matrices. Never rely on implicit matching.
• Avoid Suboptimal Loops: NEVER write explicit $O(M)$ for loops in R or Python for whole-genome data. Use fast vectorized functions.
• No Active Polling: For computationally heavy tasks, NEVER set short timers or run frequent active check-ins. Rely on reactive wake-ups.

5. Matrix Serialization & Diagnostic Debugging

• Matrix Serialization Hazards: Rigorously check actual dimensions of a returned matrix before transforming or serializing it. Naively transposing before raw binary serialization can silently scramble genotype-to-sample alignments.
• Mandatory Heritability Diagnostics: If a pipeline yields severely degraded accuracy (e.g., $r < 0.10$ for a highly heritable trait), immediately write an independent diagnostic script to compute the narrow-sense genomic heritability ($h^2$) using a standard solver (e.g., rrBLUP::mixed.solve).
• Permutation Benchmarks: If $h^2$ is abnormally low or permutation testing doesn't drop $h^2$ to ~0%, it indicates a structural alignment bug. Fix the data pipeline; do not tune hyperparameters.
• Enforce Output Persistence: NEVER print intermediate/diagnostic results purely to stdout. Always serialize and save diagnostic metrics and data to structured persistent files (CSV, JSON, RDS).

6. BLUP Methods

6.1. GBLUP (Genomic BLUP)

Package: rrBLUP (R)

library(rrBLUP)
# 'y' is phenotype vector, 'M' is marker matrix (n x p)
# If using a pre-computed genomic relationship matrix (K):
# ans <- kin.blup(data = df, geno = "id", pheno = "trait", K = K_matrix)
# If using markers directly:
ans <- mixed.solve(y, Z = M, K = NULL) 

6.2. GFBLUP (Genomic Feature BLUP)

Package: qgg (R)

library(qgg)
# Create genomic feature groups (e.g., list of marker indices or names)
# Compute feature-specific relationship matrices
# G1 <- getG(W1, scale = TRUE); G2 <- getG(W2, scale = TRUE)
# fit <- greml(y = y, X = X, G = list(G1 = G1, G2 = G2))
# Or using gblup():
fit <- gblup(y = y, X = X, G = list(G1, G2))

6.3. MultiBLUP

Software: LDAK (Executable) MultiBLUP allows specifying multiple variance components for different genomic regions.

# Calculate kinship matrices for different regions
./ldak --calc-kins-direct region1 --bfile mydata --extract region1_snps.txt
./ldak --calc-kins-direct region2 --bfile mydata --extract region2_snps.txt
# Fit MultiBLUP
./ldak --reml output --pheno pheno.txt --mgrm kinship_list.txt

7. Bayesian Methods

The BGLR package is the standard for most Bayesian whole-genome regression models in R.

7.1. BayesB

library(BGLR)
# ETA specifies the linear predictor. For BayesB:
ETA <- list(list(X=M, model='BayesB'))
fit <- BGLR(y=y, ETA=ETA, nIter=12000, burnIn=2000, saveAt='bayesB_')

7.2. BayesA

library(BGLR)
ETA <- list(list(X=M, model='BayesA'))
fit <- BGLR(y=y, ETA=ETA, nIter=12000, burnIn=2000, saveAt='bayesA_')

7.3. BayesC / BayesCpi

library(BGLR)
ETA <- list(list(X=M, model='BayesC'))
fit <- BGLR(y=y, ETA=ETA, nIter=12000, burnIn=2000, saveAt='bayesC_')

7.4. Bayesian Lasso (BL)

library(BGLR)
ETA <- list(list(X=M, model='BL'))
fit <- BGLR(y=y, ETA=ETA, nIter=12000, burnIn=2000, saveAt='BL_')

7.5. BayesRC

Software: FAANG/BayesRCO BayesRC extends BayesR to incorporate prior biological information (classes of variants).

# Ensure BayesRC executable is compiled
./bayesR -bfile mydata -out output_prefix -numit 10000 -burnin 2000 -prior prior_file.txt

(Requires specialized input files including a prior file assigning SNPs to annotation classes).

8. Machine Learning Methods

8.1. Random Forest

Package: ranger (R - recommended over randomForest for high-dimensional genomic data due to speed and memory efficiency)

library(ranger)
# Data should be a dataframe with the phenotype as the response and SNPs as predictors
# df <- data.frame(trait = y, M)
fit <- ranger(trait ~ ., data = df, num.trees = 500, mtry = floor(sqrt(ncol(M))), importance = 'impurity')
# Make predictions on test set
predictions <- predict(fit, data = test_df)$predictions

9. Benchmarking & Validation Best Practices

Based on established pipelines, adhere to the following when benchmarking genomic prediction models:

1. Population-Structure Aware Cross-Validation: Random CV folds often overestimate accuracy due to family relatedness. Use k-means or kinship-based clustering to assign related individuals to the same fold.
2. Size-Matched Random Controls: When evaluating a subset of biologically informed SNPs (e.g., 30 GWAS-significant SNPs), always compare the predictive accuracy against $N$ repetitions (e.g., 10 reps) of randomly selected SNPs of the exact same size to eliminate random sampling bias.
3. External Benchmarking (e.g., EasyGeSe): Always compare the model's Pearson $r$ or predictive ability against published benchmark values for the same species and trait.

10. Visualization and Validation (EasyGeSe Style)

When evaluating model performance, it is helpful to visualize the predicted vs. true values and plot the metrics against benchmark thresholds. Here is a Python function using matplotlib and seaborn to plot the validation results:

import matplotlib.pyplot as plt
import seaborn as sns
import numpy as np
from scipy.stats import pearsonr

def plot_easygese_validation(y_true, y_pred, trait_name="Trait", benchmark_r=0.55):
    """
    Plots predicted vs true phenotype values and annotates with Pearson r.
    Compares against a published benchmark threshold.
    """
    r_val, _ = pearsonr(y_true, y_pred)
    status = "PASSED" if r_val >= (benchmark_r - 0.05) else "BELOW BENCHMARK"
    
    plt.figure(figsize=(8, 6))
    sns.regplot(x=y_true, y=y_pred, scatter_kws={'alpha':0.5}, line_kws={'color':'red'})
    
    plt.title(f"Genomic Prediction Validation: {trait_name}")
    plt.xlabel("True Phenotype")
    plt.ylabel("Predicted Phenotype")
    
    # 1:1 Reference Line
    min_val = min(np.min(y_true), np.min(y_pred))
    max_val = max(np.max(y_true), np.max(y_pred))
    plt.plot([min_val, max_val], [min_val, max_val], color="black", linestyle="--", alpha=0.5, label="1:1 Line")
    
    textstr = f"Pearson r: {r_val:.3f}\nBenchmark: {benchmark_r:.3f}\nStatus: {status}"
    props = dict(boxstyle='round', facecolor='wheat', alpha=0.5)
    plt.gca().text(0.05, 0.95, textstr, transform=plt.gca().transAxes,
                   fontsize=12, verticalalignment='top', bbox=props)
                   
    plt.legend()
    plt.tight_layout()
    plt.show()