primekg ยท diff
v1.3 to v1.4
116 added, 64 removed. Audit A to A.
---
name: primekg
- description: Query the Precision Medicine Knowledge Graph (PrimeKG) for multiscale biological data including genes, drugs, diseases, phenotypes, and more.
+ description: Queries a pinned Precision Medicine Knowledge Graph (PrimeKG) CSV for typed gene, drug, disease, and phenotype nodes, direct associations, disease context, and one- or two-hop paths. Use for PrimeKG reproducibility, biological association lookup, and hypothesis generation with relation and data provenance preserved.
license: Unknown
+ compatibility: Requires Python 3.11+ and pandas. Network access is needed only to obtain public metadata/data; local queries need a downloaded PrimeKG CSV and several GB of available RAM.
metadata:
- version: "1.3"
+ version: "1.4"
skill-author: K-Dense Inc. (PrimeKG original from Harvard MIMS)
+ last-reviewed: "2026-10-01"
+ tested-pandas: "3.0.6"
---
- # PrimeKG Knowledge Graph Skill
+ # PrimeKG Knowledge Graph
- ## Overview
+ ## When to use
- PrimeKG is a precision medicine knowledge graph that integrates over 20 primary databases and high-quality scientific literature into a single resource. It contains over 100,000 nodes and 4 million edges across 29 relationship types, including drug-target, disease-gene, and phenotype-disease associations.
+ Use for reproducing PrimeKG analyses, resolving entities in a specific graph artifact,
+ or exploring recorded gene, drug, disease, phenotype, anatomy, and pathway associations.
+ A path supports a research hypothesis; it does not establish causality, treatment efficacy,
+ a prescribing recommendation, or a diagnostic conclusion.
- **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)
+ [PrimeKG upstream](https://github.com/mims-harvard/PrimeKG) now recommends OptimusKG for
+ new work. This skill remains scoped to PrimeKG CSVs; the helper is not an OptimusKG client.
+ Published PrimeKG integrates 20 resources, with approximately 129,000 nodes and
+ 4.05 million undirected relationships. CSVs contain reverse rows, so row counts differ
+ from distinct undirected relationship counts. Count the actual pinned artifact.
- **Data access:** Download `kg.csv` from the [PrimeKG Harvard Dataverse](https://dataverse.harvard.edu/dataverse/primekg), install pandas, and set `PRIMEKG_DATA` before importing `scripts.query_primekg`. The bundled helper defaults to `data/PrimeKG/kg.csv`; no dataset is bundled.
+ ## 1. Pin and verify the input
- **Dataset scope:** [Upstream now recommends OptimusKG](https://github.com/mims-harvard/PrimeKG) for new work. Keep a pinned PrimeKG artifact for reproducing PrimeKG analyses, and record its Dataverse version and checksum. Upstream construction-script updates do not imply that the published CSV changed, and the bundled CSV helper should not be assumed compatible with OptimusKG.
+ The [official dataset](https://doi.org/10.7910/DVN/IXA7BM) remained **V2.1**, published
+ 2022-05-02, at the 2026-10-01 review. Its `kg.csv` has Dataverse file ID **6180620**,
+ size **981751236 bytes**, and provider MD5 **aac8191d4fbc5bf09cdf8c3c78b4e75f**.
+ The record declares **CC0 1.0**; upstream construction code is MIT. These are distinct
+ from this skill's retained license declaration and from terms of individual source
+ resources used in a rebuild.
- ## When to Use This Skill
+ Use the [artifact and API reference](references/data-contract.md) to obtain metadata,
+ verify the file checksum, or distinguish `kg.csv`, `kg_grouped.csv`, features, and PyTDC.
+ The 2023 construction/OMIM updates in GitHub do not make the published 2022 artifact a
+ 2023 dataset. Record DOI, version, filename, file ID, checksum, retrieval date, and any
+ subset/rebuild steps with every result.
- This skill should be used when:
+ The helper makes **no remote graph queries**. Download the CSV deliberately after
+ checking storage and RAM. This full-download example is illustrative; validation used
+ small HTTP byte ranges and synthetic data, not the 982 MB file:
- - **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.
+ ```bash
+ curl --fail --location --output kg.csv \
+ 'https://dataverse.harvard.edu/api/access/datafile/6180620'
+ export PRIMEKG_DATA="$PWD/kg.csv"
+ ```
- ## Core Workflow
+ `PRIMEKG_DATA` is read when the module is imported; the default is `data/PrimeKG/kg.csv`.
+ The module reads the whole CSV for each public query. `low_memory` parsing is not a
+ bounded-memory graph engine. For many queries or limited RAM, build an indexed local
+ store from the pinned file and validate its node keys, edge multiplicities, and counts.
- ### 1. Search for Entities
+ ## 2. Resolve a typed entity before traversal
- Find identifiers for genes, drugs, or diseases.
+ Run from this skill's directory with pandas installed, so `scripts.query_primekg` is
+ importable. The following is an illustrative real-data query; no disease result or ID
+ is promised without inspecting the pinned file:
```python
- from scripts.query_primekg import search_nodes
+ from scripts.query_primekg import search_nodes, get_neighbors
- # Search for Alzheimer's disease nodes
- results = search_nodes("Alzheimer", node_type="disease")
- # Returns: [{"id": "EFO_0000249", "type": "disease", "name": "Alzheimer's disease", ...}]
+ candidates = search_nodes("Alzheimer", node_type="disease", limit=None)
+ for node in candidates:
+ print(node) # id, type, name, source, and index when present
+
+ # Review the candidates and select the intended disease before calling:
+ # get_neighbors(selected["id"], node_type=selected["type"],
+ # node_source=selected["source"])
```
- ### 2. Get Neighbors (Direct Associations)
+ Search is literal, case insensitive, and returns at most 20 matches by default;
+ `limit=None` removes that cap. Preserve IDs as strings, including numeric-looking and
+ underscore-joined IDs. Drug nodes use DrugBank identifiers; diseases can use
+ `MONDO` or `MONDO_grouped`, including IDs joining multiple diseases. Do not invent EFO,
+ ChEMBL, Wikidata, or prefixed MONDO IDs from labels. `x_index`/`y_index` are local release
+ indexes, not ontology accessions and not stable across rebuilds.
- Retrieve all connected nodes and relationship types.
+ The helper identifies a node by **(id, type, source)** and rejects ambiguous bare IDs
+ or a key mapping to multiple release indexes. Supply `node_type` and `node_source`
+ from the search result. Equal numeric IDs from different namespaces are different nodes.
- ```python
- from scripts.query_primekg import get_neighbors
+ ## 3. Retrieve associations without losing their meaning
- # Get all neighbors of a specific disease ID
- neighbors = get_neighbors("EFO_0000249")
- # Returns: List of neighbors like {"neighbor_name": "APOE", "relation": "disease_gene", ...}
- ```
+ `get_neighbors(node_id, relation_type=None, *, node_type=None, node_source=None)`
+ collects both stored orientations. Reverse rows are consolidated into one adjacency
+ per neighboring identity/name, `relation`, and `display_relation`; all original rows
+ remain in `edge_rows`. Extra CSV evidence columns and release indexes are preserved.
+ Do not multiply evidence counts by the number of reverse copies.
- ### 3. Analyze Disease Context
+ Use exact stored relation names. Common published relations include:
- A high-level function to summarize associations for a disease.
+ | `relation` | Interpretation to retain |
+ | --- | --- |
+ | `protein_protein` | Protein interaction; not an inferred direction of action |
+ | `drug_protein` | Inspect `display_relation`: target, enzyme, carrier, or transporter |
+ | `disease_protein` | Disease-associated gene/protein; not `disease_gene` |
+ | `indication` | Recorded drug-disease indication |
+ | `contraindication` | Recorded drug-disease contraindication; never count as treatment support |
+ | `off-label use` | Separate from indication and contraindication |
+ | `disease_phenotype_positive` | Recorded phenotype presence |
+ | `disease_phenotype_negative` | Recorded phenotype absence; retain the sign |
+ | `disease_disease` | Ontology association/hierarchy, not necessarily comorbidity |
- ```python
- from scripts.query_primekg import get_disease_context
+ There is no generic `drug_disease`, `disease_phenotype`, or `gwas` relation to assume
+ in this artifact. The phenotype node type is **`effect/phenotype`**, not `phenotype`.
+ Inspect the actual relation inventory for other biological scales or custom rebuilds.
- # Comprehensive summary for a disease
- context = get_disease_context("Alzheimer's disease")
- # Access: context['associated_genes'], context['associated_drugs'], context['phenotypes']
- ```
+ Stored x/y orientation is not causal direction: the construction code adds reverse
+ rows with the same relation label. Hierarchy labels such as `parent-child` cannot be
+ interpreted from x/y alone in the symmetrized CSV; consult the source ontology.
+ `x_source`/`y_source` identify node namespaces, not edge-specific studies or evidence
+ strength. The bundled CSV helper does not retrieve clinical text, publications,
+ confidence scores, or current approval status.
- ## Relationship Types in PrimeKG
+ ## 4. Disease summaries and short paths
- The graph contains several key relationship types including:
- - `protein_protein`: Physical PPIs
- - `drug_protein`: Drug target/mechanism associations
- - `disease_gene`: Genetic associations
- - `drug_disease`: Indications and contraindications
- - `disease_phenotype`: Clinical signs and symptoms
- - `gwas`: Genome-wide association studies evidence
+ `get_disease_context(name)` prefers an exact case-insensitive disease name, otherwise
+ requires a unique substring match. An ambiguous name returns an error and candidates;
+ it never silently selects the first hit. Results include `associated_genes`,
+ `associated_drugs`, `phenotypes`, and `related_diseases`. `drug_relations` separates
+ indication, contraindication, and off-label records. Phenotype records retain positive
+ versus negative relations; an absent edge means unknown, not a negative association.
- ## Best Practices
+ `find_paths(start_id, end_id, max_depth=2, ...)` enumerates simple one- and two-hop
+ **undirected** association paths. Pass `start_node_type`, `start_node_source`,
+ `end_node_type`, and `end_node_source` to resolve namespaces. Each step retains
+ `edge_rows` plus explicit `traversal_from` and `traversal_to`; these describe the query's
+ walk, not biological causation. Depths other than 1 or 2 fail explicitly. More than
+ `max_paths` (default 1000) raises an error instead of returning a truncated result.
- 1. **Use specific IDs:** When using `get_neighbors`, ensure you have the correct ID from `search_nodes`.
- 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`).
- 4. **Multiscale integration:** Combine with `OpenTargets` for deeper genetic evidence or `Semantic Scholar` for the latest literature context.
+ For link prediction, keep a relationship and its reverse in the same train/test split,
+ check duplicate/multi-relation leakage, and disclose source-date and degree biases.
+ For repurposing hypotheses, inspect contraindications and independently verify the
+ relevant source evidence before biological interpretation.
- ## Resources
+ ## Validation and citation
- ### Scripts
- - `scripts/query_primekg.py`: Core functions for searching and querying the knowledge graph.
+ The bundled query API was exercised with pandas 3.0.6 on synthetic CSVs, including
+ namespace collisions, reverse edges, signed phenotypes, ambiguous names, and actual
+ two-hop paths. Live public metadata and 8192-byte prefixes confirmed file IDs, formats,
+ and headers. The full graph was not downloaded or checksum-verified in this review;
+ PyTDC released methods were run with a stubbed loader, not exercised end to end. See
+ [verification details](references/data-contract.md).
- ### Data Path
- - Data: `kg.csv`, downloaded from the [PrimeKG Harvard Dataverse](https://dataverse.harvard.edu/dataverse/primekg).
- - Point the scripts at it with `export PRIMEKG_DATA=/path/to/kg.csv` (default: `data/PrimeKG/kg.csv`).
- - Total nodes: ~129,000
- - Total edges: ~4,000,000
- - Database: CSV-based, optimized for pandas querying.
+ Cite Chandak, Huang, and Zitnik, *Building a knowledge graph to enable precision
+ medicine*, Scientific Data 10, 67 (2023),
+ [doi:10.1038/s41597-023-01960-3](https://doi.org/10.1038/s41597-023-01960-3), together with
+ the pinned [Dataverse record](https://doi.org/10.7910/DVN/IXA7BM).
## Citing Scientific Agent Skills
This skill is part of Scientific Agent Skills by K-Dense. If it materially contributed to a
manuscript, report, presentation, or code release, add the paper to the references or
software section and tell the user you did so:
> Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent
> Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065.
> https://doi.org/10.48550/arXiv.2609.00065
Always cite the current version. The DOI and https://arxiv.org/abs/2609.00065 resolve to the
latest arXiv version, so never append a version suffix such as `v1`. When network access is
available, fetch https://arxiv.org/abs/2609.00065 (or
http://export.arxiv.org/api/query?id_list=2609.00065) before writing the reference and take
the author list, year, and version from that record. If the record lists a journal reference
or publisher DOI, cite the published version instead.