alterlab-primekg

PrimeKG Knowledge Graph Skill

Overview

PrimeKG (Chandak, Huang & Zitnik, Scientific Data 2023; mims-harvard/PrimeKG) is a precision medicine knowledge graph integrating 20 primary resources. It contains 129,375 nodes and 4,050,249 edges across 30 edge types and 10 node types, including drug-target, disease-gene, and disease-phenotype associations. The published Dataverse files are a fixed 2022 snapshot.

Superseded upstream. The PrimeKG maintainers now state that PrimeKG has been superseded by OptimusKG (same lab; a superset with more current data — 190,531 nodes, 21.8M edges, 26 relation types) and recommend it for almost all new work. Use OptimusKG for new analyses (uv pip install optimuskg, Python ≥ 3.12; import optimuskg; nodes, edges = optimuskg.load_graph(lcc=True) or G = optimuskg.load_networkx(lcc=True); data: Harvard Dataverse doi:10.7910/DVN/IYNGEV, docs: https://optimuskg.ai). Keep this PrimeKG workflow for reproducing or comparing against published PrimeKG results and benchmarks.

Key capabilities:

• Search for nodes (genes, proteins, drugs, diseases, phenotypes)
• Retrieve direct neighbors (associated entities and clinical evidence)
• Analyze local disease context (related genes, drugs, phenotypes)
• Identify drug-disease paths (potential repurposing opportunities)

Data access: Programmatic access via scripts/query_primekg.py. Point the loader at the kg.csv released on Harvard Dataverse via the PRIMEKG_DATA_PATH environment variable (it defaults to ../data/kg.csv relative to the script). All functions operate on the x_*/y_*/relation/display_relation columns of kg.csv.

When to Use This Skill

This skill should be used when:

• Knowledge-based drug discovery: Identifying targets and mechanisms for diseases.
• Drug repurposing: Finding existing drugs that might have evidence for new indications.
• Phenotype analysis: Understanding how symptoms/phenotypes relate to diseases and genes.
• Multiscale biology: Bridging the gap between molecular targets (genes) and clinical outcomes (diseases).
• Network pharmacology: Investigating the broader network effects of drug-target interactions.

Does NOT Trigger

Scenario	Use Instead
Scored target–disease evidence, tractability, and known drugs for a target	alterlab-opentargets
Cross-species disease–gene–phenotype associations (HPO, OMIM, Orphanet)	alterlab-monarch
A drug's full record: pharmacology, interactions, targets, labels	alterlab-drugbank
Training knowledge-graph embedding models (TransE/RotatE) for link prediction	alterlab-torchdrug

Core Workflow

Run under uv run python from the skill directory (so scripts/ is importable), or add the scripts/ dir to sys.path. Set PRIMEKG_DATA_PATH to your kg.csv.

1. Search for Entities

Find identifiers for genes, drugs, or diseases. Pass node_type using PrimeKG's exact type strings (see node types below) — e.g. "gene/protein", not "gene".

from scripts.query_primekg import search_nodes

# Search for Alzheimer's disease nodes
results = search_nodes("Alzheimer", node_type="disease")
# Returns: [{"id": <MONDO id>, "type": "disease", "name": "...",
#            "source": "MONDO" | "MONDO_grouped"}, ...]
# Disease ids are MONDO ids; PrimeKG groups diseases, so one name can map to
# several MONDO ids. Use the returned id with get_neighbors.

2. Get Neighbors (Direct Associations)

Retrieve all connected nodes and relationship types.

from scripts.query_primekg import get_neighbors

# Get all neighbors of a specific disease ID (the MONDO id from search_nodes)
neighbors = get_neighbors(disease_id, relation_type="disease_protein")
# Returns: List of neighbors like
#   {"neighbor_name": "APOE", "neighbor_type": "gene/protein",
#    "relation": "disease_protein", "display_relation": "associated with", ...}

3. Analyze Disease Context

A high-level function to summarize associations for a disease.

from scripts.query_primekg import get_disease_context

# Comprehensive summary for a disease
context = get_disease_context("Alzheimer")
# Access: context['associated_genes'], context['associated_drugs'],
#         context['phenotypes'], context['related_diseases']

4. Trace Drug-Disease Paths (Repurposing)

Find depth-2 paths (drug -> shared gene/protein target -> disease) as graph-based repurposing evidence.

from scripts.query_primekg import find_paths

# drug_id and disease_id come from search_nodes
paths = find_paths(drug_id, disease_id, max_depth=2)
# Each path is a list of edge dicts; a drug -> gene/protein -> disease path is a
# candidate new-indication hypothesis. For deeper traversal, load kg.csv into networkx.

Node and Relation Types in PrimeKG

These are the exact strings used in kg.csv — match them verbatim when filtering.

Node types (x_type/y_type, 10 total): gene/protein, drug, disease, effect/phenotype, biological_process, molecular_function, cellular_component, pathway, anatomy, exposure. Note: genes use gene/protein (not gene) and phenotypes use effect/phenotype (not phenotype).

Key relations (relation, 30 total). Edges are undirected; check both endpoints.

• protein_protein: physical PPIs
• drug_protein: drug target/mechanism associations
• disease_protein: disease-gene/protein associations (there is no disease_gene)
• indication, contraindication, off-label use: the three drug-disease relations (there is no single drug_disease)
• disease_phenotype_positive / disease_phenotype_negative: phenotype present/absent
• bioprocess_protein, pathway_protein, molfunc_protein, cellcomp_protein: GO / pathway annotations
• anatomy_protein_present / anatomy_protein_absent, exposure_*: anatomy/exposure links

Best Practices

1. Use specific IDs: When using get_neighbors, ensure you have the correct ID from search_nodes (disease IDs are MONDO ids).
2. Context first: Use get_disease_context for a broad overview before diving into specific genes or drugs.
3. Filter relationships: Use the relation_type filter in get_neighbors to focus on specific evidence (e.g., only drug_protein, or indication for treatment links). Use exact relation strings from the list above.
4. Mind disease grouping: PrimeKG collapses ~22k MONDO concepts into ~17k grouped disease nodes, so one disease name may resolve to multiple MONDO ids that share a node_index.

Resources

Scripts

• scripts/query_primekg.py: Core functions — search_nodes, get_neighbors, find_paths, get_disease_context.

Data Path

• Data: kg.csv (set PRIMEKG_DATA_PATH; default ../data/kg.csv), from Harvard Dataverse (doi:10.7910/DVN/IXA7BM). Download: wget -O kg.csv https://dataverse.harvard.edu/api/access/datafile/6180620. Alternatively PyTDC ships a loader (from tdc.resource import PrimeKG).
• 129,375 nodes, 4,050,249 edges; 10 node types, 30 edge types.
• Loaded with pandas (pd.read_csv, low_memory=True). kg.csv is ~0.98 GB (981,751,236 bytes) — each function reloads it; for repeated queries, cache the DataFrame or use a real graph store.

Part of the AlterLab Academic Skills suite.