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
Install
npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/cheminformatics/alterlab-primekg
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 |
| Parsing a SMILES string, computing descriptors (MW, LogP, TPSA) or fingerprints for one molecule | alterlab-rdkit |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-opentargets) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
Core Workflow
Run install-free from the skill directory (so scripts/ is importable), pinning the
interpreter since uv's default here is 3.9: uv run --python ">=3.11" --with pandas python your_analysis.py — 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.
Files (alterlab-academic-skills)
-
evals
-
fixtures
-
kg.csv 2.6 KB · in bundle
-
-
evals.json 4.2 KB
Loading…
-
-
scripts
-
query_primekg.py 6.2 KB
Loading…
-
-
SKILL.md 8.7 KB
--- name: alterlab-primekg description: 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. license: MIT allowed-tools: Read Write Edit Bash(python:*) Bash(uv:*) compatibility: "Runs under `uv run python` with pandas installed and the PrimeKG `kg.csv` available locally (set `PRIMEKG_DATA_PATH`); no API key or account required." metadata: skill-author: AlterLab version: "1.1.1" last_updated: "2026-09-23" --- # 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` | | Parsing a SMILES string, computing descriptors (MW, LogP, TPSA) or fingerprints for one molecule | `alterlab-rdkit` | **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-opentargets`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work. ## Core Workflow Run install-free from the skill directory (so `scripts/` is importable), pinning the interpreter since uv's default here is 3.9: `uv run --python ">=3.11" --with pandas python your_analysis.py` — 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"`. ```python 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. ```python 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. ```python 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. ```python 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.