@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/bio-causal-genomics-colocalization-analysis/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: bio-causal-genomics-colocalization-analysis
+description: Test whether two traits share a causal variant at a genomic locus using Bayesian colocalization with coloc. Computes posterior probabilities for shared vs distinct causal variants between GWAS and eQTL signals. Use when determining if a GWAS signal and an eQTL share the same causal variant.
+tool_type: r
+primary_tool: coloc
+---
+
+## Version Compatibility
+
+Reference examples tested with: ggplot2 3.5+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- R: `packageVersion('<pkg>')` then `?function_name` to verify parameters
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# Colocalization Analysis
+
+**"Test whether my GWAS signal and eQTL share the same causal variant"** → Compute Bayesian posterior probabilities for five colocalization hypotheses (no association, trait-1-only, trait-2-only, distinct causal variants, shared causal variant) to distinguish true causal overlap from LD-driven coincidence.
+- R: `coloc::coloc.abf()` for approximate Bayes factor colocalization
+
+## Overview
+
+Colocalization tests whether two association signals at the same locus are driven by the
+same causal variant. This distinguishes shared causality from coincidental overlap due to LD.
+
+Five hypotheses tested by coloc:
+- H0: No association with either trait
+- H1: Association with trait 1 only
+- H2: Association with trait 2 only
+- H3: Both associated, different causal variants
+- H4: Both associated, shared causal variant
+
+## coloc.abf Analysis
+
+**Goal:** Test whether two traits share a causal variant at a GWAS locus using Bayesian colocalization.
+
+**Approach:** Format summary statistics for each trait as named lists, run coloc.abf to compute posterior probabilities for five hypotheses (H0-H4), and interpret PP.H4 as evidence for a shared causal variant.
+
+```r
+library(coloc)
+
+# --- Input format: named list with GWAS summary stats ---
+# Required fields: beta, varbeta, snp, position, type, N
+# type = 'quant' (continuous) or 'cc' (case-control)
+
+gwas_data <- list(
+  beta = gwas_df$BETA,
+  varbeta = gwas_df$SE^2,
+  snp = gwas_df$SNP,
+  position = gwas_df$POS,
+  type = 'cc',           # Case-control study
+  s = 0.3,               # Proportion of cases (required for cc)
+  N = 50000              # Total sample size
+)
+
+eqtl_data <- list(
+  beta = eqtl_df$BETA,
+  varbeta = eqtl_df$SE^2,
+  snp = eqtl_df$SNP,
+  position = eqtl_df$POS,
+  type = 'quant',        # Quantitative trait (expression)
+  N = 500,               # eQTL sample size
+  sdY = 1                # SD of trait (1 if already normalized)
+)
+
+# --- Run colocalization ---
+result <- coloc.abf(dataset1 = gwas_data, dataset2 = eqtl_data)
+
+# Posterior probabilities
+# PP.H4 > 0.8: Strong evidence for colocalization (shared variant)
+# PP.H3 > 0.8: Distinct causal variants at the locus
+# PP.H4 between 0.5-0.8: Suggestive but inconclusive
+print(result$summary)
+```
+
+## Prior Sensitivity
+
+```r
+# Default priors: p1 = 1e-4, p2 = 1e-4, p12 = 1e-5
+# p1: Prior probability a SNP is associated with trait 1
+# p2: Prior probability a SNP is associated with trait 2
+# p12: Prior probability a SNP is associated with both traits
+#
+# Ratio p12/p1 represents prior belief in colocalization
+# Default: p12/p1 = 0.1 (10% of trait 1 SNPs also affect trait 2)
+
+result_sensitive <- coloc.abf(
+  dataset1 = gwas_data,
+  dataset2 = eqtl_data,
+  p1 = 1e-4,
+  p2 = 1e-4,
+  p12 = 5e-6    # More conservative prior for shared association
+)
+
+# Sensitivity analysis across prior values
+sensitivity(result, 'H4 > 0.8')
+```
+
+## Using P-values (No Beta/SE)
+
+```r
+# When only p-values are available, use MAF to approximate
+gwas_pval <- list(
+  pvalues = gwas_df$P,
+  MAF = gwas_df$MAF,
+  snp = gwas_df$SNP,
+  position = gwas_df$POS,
+  type = 'cc',
+  s = 0.3,
+  N = 50000
+)
+
+result <- coloc.abf(dataset1 = gwas_pval, dataset2 = eqtl_data)
+```
+
+## SuSiE-Coloc (Multiple Causal Variants)
+
+**Goal:** Test colocalization at loci with multiple independent causal signals.
+
+**Approach:** Run SuSiE fine-mapping on each dataset to identify credible sets, then test colocalization between all pairs of credible sets using coloc.susie.
+
+```r
+library(coloc)
+library(susieR)
+
+# coloc.abf assumes a single causal variant per locus
+# SuSiE-coloc handles multiple causal variants
+
+# LD matrix required (correlation matrix from reference panel)
+ld_matrix <- as.matrix(read.table('ld_matrix.txt'))
+
+# Run SuSiE on each dataset
+susie_gwas <- runsusie(
+  list(beta = gwas_df$BETA, varbeta = gwas_df$SE^2,
+       snp = gwas_df$SNP, position = gwas_df$POS,
+       type = 'cc', s = 0.3, N = 50000, LD = ld_matrix),
+  L = 10       # Max number of causal variants to search for
+)
+
+susie_eqtl <- runsusie(
+  list(beta = eqtl_df$BETA, varbeta = eqtl_df$SE^2,
+       snp = eqtl_df$SNP, position = eqtl_df$POS,
+       type = 'quant', N = 500, sdY = 1, LD = ld_matrix),
+  L = 10
+)
+
+# Coloc using SuSiE credible sets
+result_susie <- coloc.susie(susie_gwas, susie_eqtl)
+print(result_susie$summary)
+# Each row tests colocalization between a pair of credible sets
+# hit1, hit2: Credible set indices from dataset 1 and 2
+```
+
+## HyPrColoc (Multi-Trait)
+
+**Goal:** Test colocalization across three or more traits simultaneously to identify shared causal variant clusters.
+
+**Approach:** Provide beta and SE matrices (SNPs x traits) to hyprcoloc, which clusters traits sharing a causal variant using a branch-and-bound algorithm.
+
+```r
+# install.packages('remotes')
+# remotes::install_github('jrs95/hyprcoloc')
+library(hyprcoloc)
+
+# Test colocalization across multiple traits simultaneously
+# Input: matrices of betas and SEs (rows = SNPs, columns = traits)
+betas <- cbind(gwas_df$BETA, eqtl1_df$BETA, eqtl2_df$BETA)
+ses <- cbind(gwas_df$SE, eqtl1_df$SE, eqtl2_df$SE)
+colnames(betas) <- colnames(ses) <- c('GWAS', 'eQTL_gene1', 'eQTL_gene2')
+rownames(betas) <- rownames(ses) <- gwas_df$SNP
+
+result_hypr <- hyprcoloc(
+  effect.est = betas,
+  effect.se = ses,
+  trait.names = colnames(betas),
+  snp.id = rownames(betas)
+)
+
+# Output: clusters of traits sharing a causal variant
+print(result_hypr$results)
+```
+
+## Input Preparation
+
+```r
+# --- Extract a locus (1 Mb window around lead SNP) ---
+extract_locus <- function(sumstats, lead_snp_pos, chr, window = 500000) {
+  locus <- sumstats[sumstats$CHR == chr &
+                    sumstats$POS >= (lead_snp_pos - window) &
+                    sumstats$POS <= (lead_snp_pos + window), ]
+  locus[order(locus$POS), ]
+}
+
+# --- Generate LD matrix from plink ---
+# plink --bfile ref_panel --chr 6 --from-bp 30000000 --to-bp 31000000 \
+#   --r square --out ld_matrix
+# Read into R:
+ld <- as.matrix(read.table('ld_matrix.ld'))
+```
+
+## Visualization
+
+```r
+library(ggplot2)
+
+plot_coloc_locus <- function(gwas_df, eqtl_df, result) {
+  pp4 <- round(result$summary['PP.H4.abf'], 3)
+
+  p1 <- ggplot(gwas_df, aes(x = POS / 1e6, y = -log10(P))) +
+    geom_point(alpha = 0.6) +
+    labs(x = 'Position (Mb)', y = '-log10(P)', title = paste('GWAS | PP.H4 =', pp4)) +
+    theme_minimal()
+
+  p2 <- ggplot(eqtl_df, aes(x = POS / 1e6, y = -log10(P))) +
+    geom_point(alpha = 0.6, color = 'steelblue') +
+    labs(x = 'Position (Mb)', y = '-log10(P)', title = 'eQTL') +
+    theme_minimal()
+
+  library(patchwork)
+  p1 / p2
+}
+```
+
+## LocusCompare Plot
+
+```r
+# LocusCompare: scatter of -log10(P) for GWAS vs eQTL at shared SNPs
+plot_locuscompare <- function(gwas_df, eqtl_df) {
+  merged <- merge(
+    gwas_df[, c('SNP', 'P')],
+    eqtl_df[, c('SNP', 'P')],
+    by = 'SNP', suffixes = c('.gwas', '.eqtl')
+  )
+
+  ggplot(merged, aes(x = -log10(P.gwas), y = -log10(P.eqtl))) +
+    geom_point(alpha = 0.5) +
+    geom_smooth(method = 'lm', se = FALSE, linetype = 'dashed', color = 'grey50') +
+    labs(x = '-log10(P) GWAS', y = '-log10(P) eQTL', title = 'LocusCompare') +
+    theme_minimal()
+}
+```
+
+## Decision Framework
+
+```
+PP.H4 > 0.8:  Strong colocalization -- traits share a causal variant
+PP.H3 > 0.8:  Distinct causal variants -- LD-driven overlap, not shared causality
+PP.H4 0.5-0.8: Suggestive -- increase sample size, try SuSiE-coloc
+PP.H0/H1/H2 dominant: Insufficient signal at this locus
+```
+
+Common pitfalls:
+- Small eQTL sample sizes reduce power (N < 200 is problematic)
+- LD can inflate PP.H3 when two nearby causal variants exist -- use SuSiE-coloc
+- Always check that both traits have significant signals at the locus before running coloc
+
+## Related Skills
+
+- mendelian-randomization - Test causal effects using genetic instruments
+- fine-mapping - Identify causal variants and credible sets
+- population-genetics/linkage-disequilibrium - LD reference panels for SuSiE-coloc
+- differential-expression/deseq2-basics - Generate eQTL data for colocalization

package/data/skills/bio-causal-genomics-fine-mapping/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: bio-causal-genomics-fine-mapping
+description: Identify likely causal variants within GWAS loci using SuSiE for sum of single effects regression and FINEMAP for shotgun stochastic search. Computes posterior inclusion probabilities and credible sets to prioritize variants for functional follow-up. Use when narrowing GWAS association signals to candidate causal variants or building credible sets for functional validation.
+tool_type: r
+primary_tool: susieR
+---
+
+## Version Compatibility
+
+Reference examples tested with: ggplot2 3.5+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- R: `packageVersion('<pkg>')` then `?function_name` to verify parameters
+- CLI: `<tool> --version` then `<tool> --help` to confirm flags
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# Fine-Mapping
+
+**"Narrow my GWAS locus to the likely causal variant"** → Compute posterior inclusion probabilities (PIPs) for each variant and construct credible sets containing the causal variant at a specified confidence level, accounting for LD and multiple causal signals.
+- R: `susieR::susie_rss()` for SuSiE fine-mapping from summary statistics
+- CLI: `finemap --sss` for shotgun stochastic search
+
+## Overview
+
+Fine-mapping narrows GWAS association signals to identify likely causal variants. Key outputs:
+
+- **PIP** (Posterior Inclusion Probability) - Probability each variant is causal (0-1)
+- **Credible set** - Minimal set of variants containing the causal variant at a given confidence level (e.g., 95%)
+- **L** - Number of independent causal signals at the locus
+
+## SuSiE (Sum of Single Effects)
+
+**Goal:** Fine-map a GWAS locus to identify likely causal variants and credible sets from individual-level data.
+
+**Approach:** Fit SuSiE's sum-of-single-effects model on the genotype matrix, then extract 95% credible sets (each containing the causal variant) and per-variant posterior inclusion probabilities.
+
+```r
+library(susieR)
+
+# --- From individual-level data ---
+# X: genotype matrix (n x p), standardized
+# Y: phenotype vector (n x 1)
+# L: max number of causal variants (10 is a reasonable default)
+fit <- susie(X, Y, L = 10)
+
+# Extract credible sets
+# 95% credible sets: each set contains the causal variant with >= 95% probability
+# coverage: minimum posterior mass for the credible set (default 0.95)
+# min_abs_corr: minimum purity (correlation among variants in set; > 0.5 is good)
+cs <- fit$sets$cs
+cat('Number of credible sets:', length(cs), '\n')
+
+# Credible set purity (minimum absolute correlation within set)
+# Purity > 0.5: Well-resolved signal
+# Purity < 0.5: Signal may be confounded by LD
+purity <- fit$sets$purity
+print(purity)
+
+# PIPs for all variants
+pip <- fit$pip
+top_variants <- order(-pip)[1:10]
+cat('\nTop 10 variants by PIP:\n')
+for (i in top_variants) {
+  cat(sprintf('  Variant %d: PIP = %.4f\n', i, pip[i]))
+}
+```
+
+## SuSiE with Summary Statistics (susie_rss)
+
+**Goal:** Fine-map a GWAS locus using summary statistics and an LD reference matrix (no individual-level data needed).
+
+**Approach:** Compute Z-scores from beta/SE, provide a matched-ancestry LD correlation matrix, and run susie_rss to identify credible sets and PIPs.
+
+```r
+library(susieR)
+
+# --- Most common usage: GWAS summary statistics + LD matrix ---
+# z: Z-scores (beta / se) for each variant
+# R: LD correlation matrix (from matched ancestry reference)
+# n: Sample size
+# L: Max causal variants
+
+z_scores <- gwas_df$BETA / gwas_df$SE
+ld_matrix <- as.matrix(read.table('ld_matrix.ld'))
+
+# Ensure SNP order matches between z-scores and LD matrix
+stopifnot(nrow(ld_matrix) == length(z_scores))
+
+fit <- susie_rss(z = z_scores, R = ld_matrix, n = 50000, L = 10)
+
+# Credible sets
+cs <- fit$sets$cs
+for (i in seq_along(cs)) {
+  cat(sprintf('Credible set %d: %d variants, purity = %.3f\n',
+              i, length(cs[[i]]), fit$sets$purity[i, 1]))
+  cat('  Variants:', paste(gwas_df$SNP[cs[[i]]], collapse = ', '), '\n')
+}
+
+# PIPs
+gwas_df$PIP <- fit$pip
+top_pip <- gwas_df[order(-gwas_df$PIP), ][1:20, c('SNP', 'PIP', 'P')]
+print(top_pip)
+```
+
+## Choosing L (Number of Causal Variants)
+
+```r
+# L = max number of causal signals SuSiE will search for
+# Too low: Misses real signals
+# Too high: Increases computation but rarely hurts results (SuSiE prunes excess)
+#
+# Guidelines:
+# L = 1: Single causal variant expected
+# L = 5: Most GWAS loci
+# L = 10: Default, works well for most cases
+# L = 20: Very complex loci (e.g., HLA region)
+
+# Compare fits with different L
+fit_l5 <- susie_rss(z = z_scores, R = ld_matrix, n = 50000, L = 5)
+fit_l10 <- susie_rss(z = z_scores, R = ld_matrix, n = 50000, L = 10)
+
+cat('L=5 credible sets:', length(fit_l5$sets$cs), '\n')
+cat('L=10 credible sets:', length(fit_l10$sets$cs), '\n')
+```
+
+## LD Reference Panel
+
+```bash
+# Generate LD matrix from 1000 Genomes with plink
+# Must match ancestry of GWAS sample
+
+# Extract region
+plink --bfile 1000G_EUR \
+  --chr 6 --from-bp 30000000 --to-bp 31000000 \
+  --make-bed --out locus_ref
+
+# Compute correlation matrix
+plink --bfile locus_ref \
+  --r square --out ld_matrix
+
+# Filter to GWAS SNPs only
+plink --bfile locus_ref \
+  --extract gwas_snps.txt \
+  --r square --out ld_matrix_filtered
+```
+
+```r
+# Read LD matrix into R
+ld <- as.matrix(read.table('ld_matrix.ld'))
+
+# Ensure positive semi-definite (numerical issues can violate this)
+# Add small ridge to diagonal if needed
+eigenvalues <- eigen(ld, only.values = TRUE)$values
+if (any(eigenvalues < 0)) {
+  ld <- ld + diag(abs(min(eigenvalues)) + 1e-6, nrow(ld))
+}
+```
+
+## FINEMAP
+
+**Goal:** Fine-map a locus using an alternative shotgun stochastic search algorithm.
+
+**Approach:** Prepare .z (summary stats), .ld (LD matrix), and .master (config) files, then run FINEMAP to compute per-variant PIPs and causal configurations.
+
+```bash
+# FINEMAP: alternative fine-mapping tool using shotgun stochastic search
+# Download from http://www.christianbenner.com/
+
+# Required input files:
+# 1. .z file: SNP, chromosome, position, allele1, allele2, MAF, beta, se
+# 2. .ld file: LD matrix (space-separated, no header)
+# 3. .master file: configuration
+
+# Create master file
+cat > master.txt << 'EOF'
+z;ld;snp;config;cred;log;n_samples
+locus.z;locus.ld;locus.snp;locus.config;locus.cred;locus.log;50000
+EOF
+
+# Run FINEMAP
+finemap --sss --in-files master.txt --n-causal-snps 5
+```
+
+```r
+# Parse FINEMAP output
+finemap_snp <- read.table('locus.snp', header = TRUE)
+finemap_snp <- finemap_snp[order(-finemap_snp$prob), ]
+
+cat('Top variants by PIP (FINEMAP):\n')
+print(head(finemap_snp[, c('rsid', 'prob', 'log10bf')], 10))
+
+# Credible sets from .cred file
+finemap_cred <- read.table('locus.cred', header = TRUE)
+```
+
+## Functional Annotation with PolyFun
+
+```r
+# PolyFun integrates functional annotations to improve fine-mapping
+# Uses LD-score regression to estimate per-SNP heritability
+# Provides functionally-informed priors for SuSiE
+
+# After running PolyFun (Python), read prior variances
+polyfun_priors <- read.table('polyfun_output.txt', header = TRUE)
+
+# Use priors in SuSiE
+fit_informed <- susie_rss(
+  z = z_scores, R = ld_matrix, n = 50000, L = 10,
+  prior_variance = polyfun_priors$prior_var
+)
+```
+
+## Visualization
+
+```r
+library(ggplot2)
+
+plot_pip <- function(gwas_df, credible_sets = NULL) {
+  p <- ggplot(gwas_df, aes(x = POS / 1e6, y = PIP)) +
+    geom_point(alpha = 0.5, size = 1.5) +
+    geom_hline(yintercept = 0.5, linetype = 'dashed', color = 'orange', alpha = 0.5) +
+    geom_hline(yintercept = 0.95, linetype = 'dashed', color = 'red', alpha = 0.5) +
+    labs(x = 'Position (Mb)', y = 'Posterior Inclusion Probability',
+         title = 'Fine-Mapping Results') +
+    theme_minimal()
+
+  if (!is.null(credible_sets)) {
+    cs_snps <- unlist(credible_sets)
+    gwas_df$in_cs <- seq_len(nrow(gwas_df)) %in% cs_snps
+    p <- ggplot(gwas_df, aes(x = POS / 1e6, y = PIP, color = in_cs)) +
+      geom_point(alpha = 0.6, size = 1.5) +
+      scale_color_manual(values = c('grey60', 'red'), labels = c('No', 'Yes'), name = 'In credible set') +
+      geom_hline(yintercept = 0.5, linetype = 'dashed', alpha = 0.3) +
+      labs(x = 'Position (Mb)', y = 'PIP', title = 'Fine-Mapping with Credible Sets') +
+      theme_minimal()
+  }
+
+  p
+}
+
+# Combined GWAS + PIP plot
+plot_gwas_pip <- function(gwas_df) {
+  library(patchwork)
+
+  p_gwas <- ggplot(gwas_df, aes(x = POS / 1e6, y = -log10(P))) +
+    geom_point(alpha = 0.4, size = 1) +
+    geom_hline(yintercept = -log10(5e-8), linetype = 'dashed', color = 'red', alpha = 0.3) +
+    labs(x = NULL, y = '-log10(P)', title = 'GWAS') +
+    theme_minimal() + theme(axis.text.x = element_blank())
+
+  p_pip <- ggplot(gwas_df, aes(x = POS / 1e6, y = PIP)) +
+    geom_point(alpha = 0.4, size = 1, color = 'steelblue') +
+    labs(x = 'Position (Mb)', y = 'PIP', title = 'Fine-Mapping') +
+    theme_minimal()
+
+  p_gwas / p_pip
+}
+```
+
+## Related Skills
+
+- colocalization-analysis - SuSiE-coloc uses fine-mapping credible sets
+- mendelian-randomization - Fine-map instrument loci for causal variants
+- population-genetics/linkage-disequilibrium - LD matrices for fine-mapping
+- variant-calling/variant-annotation - Annotate fine-mapped variants