hinna0818/ukbanalytica_v2/ukbsci-proteomics

ukbsci-proteomics — UKB Olink / UKB-PPP downstream analyses

0. RAP guardrails

Strict local-agent boundary: this skill is for script generation, workflow planning, package guidance, and interpretation of aggregate outputs. The agent must not read, inspect, summarize, or process real UK Biobank RAP participant-level data, including de-identified row-level tables, raw RAP fields, exact dates, per-row predictions, row-level SHAP matrices, screenshots, tracebacks, or logs containing row-level values. Generate scripts for the user to run inside RAP; only aggregate results or rendered figures may be shared back with the agent. See ../references/agent-privacy-boundary.md.

• Participant-level Olink intensities, protein matrices, and any tables that

retain participant identifiers or row-level values stay in RAP.

• A list of significant protein IDs / gene symbols (no participant

rows) is non-identifying and may be exported when needed (e.g. for cross-cohort replication, or for running STRING enrichment outside RAP if the user prefers).

• STRING / KEGG queries hit external servers — confirm RAP node has

outbound internet and that the user is comfortable sending their gene-symbol hits.

1. When to load

• User has a list of significant proteins (e.g. from a Cox screen across

~3,000 Olink targets) and wants PPI / pathway downstream.

• User wants GO BP / MF / CC ORA or KEGG ORA.
• User wants to cluster the PPI network and characterize modules.
• User wants a "robustness" check: would the network collapse if specific

proteins were knocked out?

2. When NOT to load

• Running the upstream protein-association screen (Cox / logistic for

~3,000 targets) → ukbsci-regression.

• Producing the volcano plot of effect estimates →

ukbsci-plot::plot_regression_volcano().

3. Prerequisites

library(UKBAnalytica)
library(clusterProfiler)        # ORA + bitr
library(org.Hs.eg.db)           # human gene-symbol mapping
library(igraph)
library(TCMDATA)                # PPI helpers
library(data.table)

The protein input is typically the significant subset of a UKBAnalytica Cox / logistic batch run — i.e. a data.frame with at least one column of Olink protein identifiers and (optionally) effect sizes / adjusted p-values.

4. Pipeline (4 phases)

Phase 1 — Map protein IDs to gene symbols

hits <- fread("/mnt/project/<area>/04-results/protein_screen_sig.csv")
# columns: protein (Olink ID), HR, lower95, upper95, pvalue, padj
 
mapped <- protein_to_gene_symbol(
  hits,
  protein_col       = "protein",
  from_type         = "SYMBOL",            # Olink IDs are typically gene symbols
  drop_unmapped     = TRUE,
  organism_db       = "org.Hs.eg.db"
)
# Returns: data.frame(protein, gene_symbol, mapping_source)
genes <- unique(mapped$gene_symbol)

Phase 2 — Enrichment (ORA)

GO over-representation:

go_res <- run_protein_ora(
  proteins      = genes,
  from_type     = "SYMBOL",
  universe      = NULL,                    # NULL = whole-genome background
  ont           = "BP",                    # "BP", "MF", "CC", or "ALL"
  pvalueCutoff  = 0.05,
  qvalueCutoff  = 0.2,
  minGSSize     = 10, maxGSSize = 500,
  readable      = TRUE
)
go_res$ora_result                            # enrichResult
 
p_go <- plot_go_ora_bar(go_res)              # ggplot bar

KEGG over-representation:

kegg_res <- run_protein_kegg_ora(
  proteins   = genes,
  organism   = "hsa",
  pvalueCutoff = 0.05,
  use_internal_data = FALSE                  # FALSE = live KEGG fetch
)
p_kegg <- plot_enrichment_lollipop(kegg_res) # ggplot lollipop

Phase 3 — PPI network analysis

ppi <- get_protein_ppi(
  proteins        = genes,
  taxID           = 9606,                    # Homo sapiens
  required_score  = 700,                     # STRING confidence × 1000
  network_type    = "functional",            # or "physical"
  output          = "igraph"
)
# ppi$ppi is an igraph object
 
# 3a. Confidence-based subset
ppi_top <- subset_protein_ppi(ppi$ppi, score_cutoff = 0.7, rm_isolates = TRUE)
 
# 3b. Compute network metrics
ppi_m <- compute_protein_ppi_metrics(ppi_top, weight_attr = "score",
                                      normalize = FALSE, seed = 42)
 
# 3c. Rank nodes by integrated centrality
ranked <- rank_protein_ppi_nodes(
  ppi_m,
  metrics = c("degree","betweenness","closeness",
              "eccentricity","radiality","Stress",
              "MCC","MNC","DMNC","BN","EPC"),
  use_weight = TRUE
)
ranked$table[1:20, ]

Phase 4 — Community detection + cluster scoring

# Pick ONE algorithm based on network size / preference
ppi_fg <- run_protein_ppi_clustering(
  ppi_m,
  method = "fastgreedy",
  n_clusters = 4,
  largest_component = TRUE
)
 
# Score clusters (size, density, average centrality)
scores <- score_protein_ppi_clusters(
  ppi_fg,
  cluster_attr = "fast_greedy_cluster",
  min_size     = 3
)

Phase 5 — Robustness to target knockout

robust <- run_protein_ppi_robustness(
  ppi          = ppi_m,
  targets      = c("APOB", "LPA"),         # known-causal candidates
  n_perm       = 100L,
  rewire_niter = 10L,
  seed         = 42L
)
robust$robustness          # TCMDATA result with permutation summary

Phase 6 — Export

fwrite(go_res$ora_result@result, "/mnt/project/<area>/04-results/12-go_ora.csv")
fwrite(kegg_res$ora_result@result, "/mnt/project/<area>/04-results/13-kegg_ora.csv")
fwrite(ranked$table,                "/mnt/project/<area>/04-results/14-ppi_node_rank.csv")
fwrite(scores,                       "/mnt/project/<area>/04-results/15-ppi_cluster_scores.csv")
 
ggplot2::ggsave("/mnt/project/<area>/05-figs/Fig11-go_bar.pdf",
                p_go, width = 8, height = 6)
ggplot2::ggsave("/mnt/project/<area>/05-figs/Fig12-kegg_lollipop.pdf",
                p_kegg, width = 8, height = 6)

5. Common pitfalls

1. Olink ID format. Most UKB Olink panel names are HGNC symbols (e.g.

IL6, CRP), but a handful are not (FAM3A, Q8NEW0). When drop_unmapped = TRUE, those are silently removed; check attr(mapped, "n_dropped") if available.

1. `universe = NULL` background. Whole-genome background inflates

enrichment. Use the union of measured Olink panel symbols as universe for honest results.

1. `required_score = 700` is the STRING "high confidence" cutoff.

400 is "medium". Don't go below 400.

1. Network-type choice. "physical" returns only experimentally

determined interactions; "functional" is broader (co-expression, text-mining). For mechanism-focused stories use "physical".

1. Largest connected component. Fastgreedy requires it; the other

algorithms tolerate disconnected components but typically cluster only the giant one. Note this in the manuscript.

1. MCODE parameters. vwp (vertex weight percentage) governs

stringency; lower values yield more / smaller clusters.

1. External-network calls. get_protein_ppi() and

run_protein_kegg_ora(use_internal_data = FALSE) make outbound HTTP calls. If the RAP node is network-restricted, set use_internal_data = TRUE for KEGG or supply your own STRING dump.

1. `TCMDATA` dependency. Many helpers (subset, rank, MCODE,

robustness) thinly wrap TCMDATA. If the package is unavailable on the RAP node, fall back to manual igraph + clusterProfiler workflows.

6. Key functions

7. Related skills

8. References

• `references/functions.md`
• `references/examples.md`