alterlab-primekg
Queries the Precision Medicine Knowledge Graph (PrimeKG) for multiscale biomedical relationships across genes, drugs, diseases, phenotypes, pathways, and biological processes. Use when exploring drug-disease or gene-disease links, building disease-centric knowledge subgraphs, or sourcing relations for drug repurposing and precision-medicine analyses; also points to OptimusKG, the maintainers' successor graph, for new work. Part of the AlterLab Academic Skills suite.
How do I install this agent skill?
npx skills add https://github.com/alterlab-ieu/alterlab-academic-skills --skill alterlab-primekgIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides tools to query the PrimeKG biomedical knowledge graph locally using pandas. It allows searching for genes, drugs, and diseases and exploring their relationships. The implementation is transparent and adheres to standard data processing practices without any detected malicious behaviors.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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)orG = 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 PPIsdrug_protein: drug target/mechanism associationsdisease_protein: disease-gene/protein associations (there is nodisease_gene)indication,contraindication,off-label use: the three drug-disease relations (there is no singledrug_disease)disease_phenotype_positive/disease_phenotype_negative: phenotype present/absentbioprocess_protein,pathway_protein,molfunc_protein,cellcomp_protein: GO / pathway annotationsanatomy_protein_present/anatomy_protein_absent,exposure_*: anatomy/exposure links
Best Practices
- Use specific IDs: When using
get_neighbors, ensure you have the correct ID fromsearch_nodes(disease IDs are MONDO ids). - Context first: Use
get_disease_contextfor a broad overview before diving into specific genes or drugs. - Filter relationships: Use the
relation_typefilter inget_neighborsto focus on specific evidence (e.g., onlydrug_protein, orindicationfor treatment links). Use exact relation strings from the list above. - 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(setPRIMEKG_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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/alterlab-ieu/alterlab-academic-skills/alterlab-primekg">View alterlab-primekg on skillZs</a>