Claude Skill

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

LLM Mart · 0 points · 5 views 0 listing impressions 0 install-command copies
Download AlterLab-IEU-AlterLab-Academic-Skills-skills_cheminformatics_alterlab-primekg-3ab6d03.zip · 8 KB

Install

skills CLI npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/cheminformatics/alterlab-primekg
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
Git 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) 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".

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.

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.

No comments yet.

Reviews (0)

No reviews yet.