alterlab-primekg

Files (3)

• SKILL.md
• evals.json · evals/
• query_primekg.py · scripts/

SKILL.md (first lines)

# 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 /

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills