optimuskg

name	optimuskg
description	Guide for using OptimusKG, the biomedical knowledge graph, through the `optimuskg` Python client. Use this when loading, querying, filtering, or analyzing OptimusKG data — genes, drugs, diseases, phenotypes, anatomy, pathways, and their relationships — as Polars DataFrames or a NetworkX graph, or when downloading the published graph from Harvard Dataverse.

OptimusKG

OptimusKG is a modern multimodal biomedical knowledge graph (190,531 nodes across 10 entity types, 21,813,816 edges across 27 relation types) integrating 65 resources grounded in 18 ontologies via the BioCypher framework and Biolink Model. It is published on Harvard Dataverse as Apache Parquet files and consumed through the optimuskg PyPI client.

This skill covers using the published graph via the client. It is not for developing the data pipeline in the mims-harvard/optimuskg repo — that work uses the repo's own /node-catalog-sync skill.

When to use

Use the optimuskg client when you need to:

• Download OptimusKG node/edge tables for analysis.
• Load the graph as Polars DataFrames or a NetworkX MultiDiGraph.
• Filter by entity type (Gene, Drug, Disease, …) or relation type.
• Build biomedical analyses, Graph-RAG, or ML over the graph.

Always prefer this client over hand-rolling Dataverse downloads — it resolves file IDs automatically and caches locally.

Installation

uv add optimuskg     # in a uv project (preferred — see the `uv` skill)
pip install optimuskg

The client depends on polars (DataFrames) and networkx (graph view).

Quick start

import optimuskg

# Download a specific file; returns its local cached path
local_path = optimuskg.get_file("nodes/gene.parquet")

# Read a single Parquet file as a Polars DataFrame
drugs = optimuskg.load_parquet("nodes/drug.parquet")

# Load nodes + edges as Polars DataFrames (lcc=True -> largest connected component only)
nodes, edges = optimuskg.load_graph(lcc=True)

# Load as a NetworkX MultiDiGraph with properties merged onto node/edge attrs
G = optimuskg.load_networkx(lcc=True)

Choosing the right loader

Need	Function	Returns
Just the file on disk	get_file(path, *, force=False)	pathlib.Path
One table as a DataFrame	load_parquet(path, *, force=False, **read_parquet_kwargs)	pl.DataFrame
Whole graph as DataFrames	load_graph(*, lcc=False, force=False)	(nodes, edges) tuple of pl.DataFrame
Whole graph as NetworkX	load_networkx(*, lcc=False, force=False, parse_properties=True)	nx.MultiDiGraph

Notes:

• load_parquet forwards extra kwargs to pl.read_parquet — e.g. push down column selection: optimuskg.load_parquet("nodes/drug.parquet", columns=["id"]).
• force=True re-downloads even if the file is already cached.
• load_networkx always builds a MultiDiGraph regardless of edge directionality; call G.to_undirected() if you need an undirected view.
• Memory: loading the full graph into NetworkX needs several GB (190k nodes, 21M edges) and emits a warning. Pass lcc=True for a smaller, connected variant unless you specifically need every node.

File paths

Paths mirror the catalog layout under data/gold/kg/parquet/ in the source repo:

optimuskg.get_file("nodes.parquet")                              # full nodes table
optimuskg.get_file("edges.parquet")                              # full edges table
optimuskg.get_file("largest_connected_component_nodes.parquet")  # LCC nodes
optimuskg.get_file("largest_connected_component_edges.parquet")  # LCC edges
optimuskg.get_file("nodes/gene.parquet")                         # only Gene (GEN) nodes
optimuskg.get_file("edges/disease_gene.parquet")                 # only DIS-GEN edges

nodes/<type>.parquet files use the lowercase entity name (gene, drug, …); edges/<a>_<b>.parquet files use the lowercase node pair (disease_gene, drug_gene, …).

Graph schema (at a glance)

Node table columns: id, label (the type code, e.g. GEN), properties. Edge table columns: from, to, label (e.g. DIS-GEN), relation (e.g. ASSOCIATED_WITH), undirected, properties.

In the unified nodes.parquet / edges.parquet tables, properties is a JSON string. In the stratified per-type files (nodes/<type>.parquet, edges/<label>.parquet) it is expanded into native typed columns as a Polars Struct.

The 10 node type codes:

Label	Type		Label	Type
GEN	Gene		ANA	Anatomy
DIS	Disease		MFN	Molecular Function
BPO	Biological Process		CCO	Cellular Component
PHE	Phenotype		PWY	Pathway
DRG	Drug		EXP	Exposure

For the full edge-label/relation taxonomy (all 27 edge types and their relation strings) and per-type property fields, see reference/graph-schema.md.

Common patterns

Filter Polars DataFrames by type/relation:

import polars as pl

nodes, edges = optimuskg.load_graph(lcc=True)
genes = nodes.filter(pl.col("label") == "GEN")
dis_gen = edges.filter(pl.col("relation") == "ASSOCIATED_WITH")

Filter a NetworkX graph (properties are merged onto attrs):

G = optimuskg.load_networkx(lcc=True)

# Nodes by type code
genes = [n for n, a in G.nodes(data=True) if a["label"] == "GEN"]

# Edges by relation
expression = [
    (u, v) for u, v, a in G.edges(data=True)
    if a["relation"] == "EXPRESSION_PRESENT"
]

Pass parse_properties=False to load_networkx to keep properties as a raw JSON string instead of merging parsed keys into the attribute dicts.

Configuration

The client targets doi:10.7910/DVN/IYNGEV on https://dataverse.harvard.edu by default, and caches downloads in platformdirs.user_cache_dir("optimuskg") (~/.cache/optimuskg on Linux, ~/Library/Caches/optimuskg on macOS). Cache keys include the dataset version, so a new release invalidates it automatically.

Override from code or via environment variables:

optimuskg.set_cache_dir("/data/optimuskg-cache")
optimuskg.set_doi("doi:10.7910/DVN/EXAMPLE")     # target a different release
optimuskg.set_server("https://dataverse.example.org")  # non-Harvard installation

# Read current settings
optimuskg.get_cache_dir(); optimuskg.get_doi(); optimuskg.get_server()

export OPTIMUSKG_CACHE_DIR=/data/optimuskg-cache
export OPTIMUSKG_DOI=doi:10.7910/DVN/EXAMPLE
export OPTIMUSKG_SERVER=https://dataverse.example.org

Citing and license

• Cite OptimusKG when you use it in research — see https://optimuskg.ai/docs/citation and the dataset DOI 10.7910/DVN/IYNGEV.
• License: the OptimusKG codebase is MIT. The integrated source datasets keep their own licenses and terms of use, which may restrict redistribution or commercial use of a given graph subset — review each source's terms. See https://optimuskg.ai/docs/license.

Documentation

For full details (function signatures, per-type schemas, edge relations), read the official docs — they expose machine-readable text files:

• https://optimuskg.ai/llms.txt — index of all doc pages
• https://optimuskg.ai/llms-full.txt — full documentation in one file
• https://optimuskg.ai/docs/optimuskg-client/reference — API reference
• https://github.com/mims-harvard/optimuskg — source repository