optimuskg 1.0.0

Python client for loading the OptimusKG biomedical knowledge graph from Harvard Dataverse.

Highlights

• A modern biomedical knowledge graph with molecular, anatomical, clinical, and environmental modalities.
• Integrates 65 heterogeneous resources grounded with 18 ontologies and controlled vocabularies using the BioCypher framework and the Biolink Model.
• Contains 190,531 nodes across 10 entity types, 21,813,816 edges across 26 relation types, and 67,249,863 property instances encoding 110,276,843 values across 150 distinct property keys.
• Independently validated using PaperQA3, a multimodal agent that retrieves and reasons over scientific literature.

Installation

pip install optimuskg

# Or with pipx.
pipx install optimuskg

Usage

The client fetches files from the gold layer with local caching, and supports loading the graph either as Polars DataFrames or as a NetworkX MultiDiGraph:

import optimuskg

# Download (once) and cache a file from the gold layer
path = optimuskg.get_file("nodes/gene.parquet")

# Load a single Parquet file
drugs = optimuskg.load_parquet("nodes/drug.parquet")

# Load nodes and edges (full graph or Largest Connected Component)
nodes, edges = optimuskg.load_graph(lcc=True)

# Load as NetworkX MultiDiGraph (JSON properties parsed)
G = optimuskg.load_networkx(lcc=True)

Configuration

Downloads are cached by default in platformdirs.user_cache_dir("optimuskg") (~/Library/Caches/optimuskg on macOS, ~/.cache/optimuskg on Linux). Override the location with the $OPTIMUSKG_CACHE_DIR environment variable or programmatically:

optimuskg.set_cache_dir("/path/to/cache")

To target a different dataset version (e.g., a pre-release), set the $OPTIMUSKG_DOI environment variable or call:

optimuskg.set_doi("doi:10.xxxx/XXXX")

Citation

If you use OptimusKG in your research, please cite:

@article{vittor2026optimuskg,
  title={OptimusKG: Unifying biomedical knowledge in a modern multimodal graph},
  author={Vittor, Lucas and Noori, Ayush and Arango, I{\~n}aki and Polonuer, Joaqu{\'\i}n and Rodriques, Sam and White, Andrew and Clifton, David A. and Zitnik, Marinka},
  journal={Nature Scientific Data},
  year={2026}
}

License

The optimuskg client is released under the MIT License. OptimusKG integrates multiple primary data resources, each of which is subject to its own license and terms of use. These terms may impose restrictions on redistribution, commercial use, or downstream applications of the resulting knowledge graph or its subsets. Some resources provide data under academic or noncommercial licenses, while others may impose attribution or usage requirements. As a result, use of OptimusKG may be partially restricted depending on the specific data components included in a given instantiation. Users are responsible for reviewing and complying with the license and terms of use of each primary dataset, as specified by the original data providers. OptimusKG does not alter or override these source-specific licensing conditions.

Made with ❤️ at Zitnik Lab, Harvard Medical School