# Citing (/docs/citation)



If you use OptimusKG in your research, please cite the following paper:

<CitationBlock />


# Funding (/docs/funding)



We gratefully acknowledge the support of NSF CAREER 2339524, ARPA-H Biomedical Data Fabric (BDF) Toolbox Program, Harvard Data Science Initiative, Amazon Faculty Research, Google Research Scholar Program, AstraZeneca Research, Roche Alliance with Distinguished Scientists (ROADS) Program, Sanofi iDEA-iTECH Award, GlaxoSmithKline Award, Boehringer Ingelheim Award, Merck Award, Optum AI Research Collaboration Award, Pfizer Research, Gates Foundation (INV-079038), Aligning Science Across Parkinson's Initiative (ASAP), Chan Zuckerberg Initiative, John and Virginia Kaneb Fellowship at Harvard Medical School, Biswas Computational Biology Initiative in partnership with the Milken Institute, Collaborative Center for XDP at Massachusetts General Hospital, Harvard Medical School Dean's Innovation Fund for the Use of Artificial Intelligence, and the Kempner Institute for the Study of Natural and Artificial Intelligence at Harvard University.

A.N. was supported by the Rhodes Scholarship and the Y Combinator Summer Fellows Grant. D.A.C. was funded by an NIHR Research Professorship (NIHR302440), a Royal Academy of Engineering Research Chair, and the InnoHK Hong Kong Centre for Cerebro-Cardiovascular Engineering, and was supported by the National Institute for Health Research Oxford Biomedical Research Centre and the Pandemic Sciences Institute at the University of Oxford.

Any opinions, findings, conclusions, or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the funders.


# Introduction (/docs)



Highlights [#highlights]

* A [modern biomedical knowledge graph](https://optimuskg.ai) with molecular, anatomical, clinical, and environmental modalities.
* Integrates 65 heterogeneous resources grounded with 18 ontologies and controlled vocabularies using the [BioCypher framework](https://github.com/biocypher/biocypher) and the [Biolink Model](https://github.com/biolink/biolink-model).
* Contains 190,531 nodes across 10 entity types, 21,813,816 edges across 27 relation types, and 67,249,863 property instances encoding 110,276,843 values across 150 distinct property keys.
* Independently validated using [PaperQA3](https://github.com/Future-House/paper-qa), a multimodal agent that retrieves and reasons over scientific literature.
* Reproducible, deterministic and infrastructure-agnostic data pipeline with parallel execution.
* Distributed as [Apache Parquet](https://parquet.apache.org/) files and downloadable via the [optimuskg](/docs/optimuskg-client) python client.

OptimusKG is developed at the [Zitnik Lab](https://zitniklab.hms.harvard.edu/), [Harvard Medical School](https://dbmi.hms.harvard.edu/).

Using OptimusKG [#using-optimuskg]

OptimusKG is available via [Harvard Dataverse](https://doi.org/10.7910/DVN/IYNGEV). The graph can be programmatically accessed using the Python client, available on [PyPI](https://pypi.org/project/optimuskg/):

<CodeBlockTabs defaultValue="uv">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="uv">
      uv
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pip">
      pip
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="uv">
    ```bash
    uv add optimuskg
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pip">
    ```bash
    pip install optimuskg
    ```
  </CodeBlockTab>
</CodeBlockTabs>

The client fetches files from the gold layer with local caching, and supports loading the graph either as [Polars DataFrames](https://github.com/pola-rs/polars) or as a [NetworkX MultiDiGraph](https://networkx.org/documentation/stable/reference/classes/multidigraph.html):

```python
import optimuskg

# Download a specific file and store it locally
local_path = optimuskg.get_file("nodes/gene.parquet")

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

# Load nodes and edges as Polars DataFrames
# Set lcc=True to load only the largest connected component
nodes, edges = optimuskg.load_graph(lcc=True)

# Load the graph as a NetworkX MultiDiGraph with metadata
# Set lcc=True to load only the largest connected component
G = optimuskg.load_networkx(lcc=True)
```

<Callout>
  Downloads are cached by default in `platformdirs.user_cache_dir("optimuskg")` (`~/Library/Caches/optimuskg` on macOS, `~/.cache/optimuskg` on Linux). The cache location can be overridden via the `$OPTIMUSKG_CACHE_DIR` environment variable or programmatically with `optimuskg.set_cache_dir(path)`.
</Callout>

<Callout>
  To target a different dataset (e.g., a pre-release), set the `$OPTIMUSKG_DOI` environment variable or use `optimuskg.set_doi("doi:10.xxxx/XXXX")`.
</Callout>

What's Next? [#whats-next]

<Cards>
  <Card title="OptimusKG Client" href="/docs/optimuskg-client" />

  <Card title="Nodes" href="/docs/graph-schema/nodes" />

  <Card title="Edges" href="/docs/graph-schema/edges" />
</Cards>


# License (/docs/license)



The OptimusKG codebase 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.


# MCP Bundle (/docs/mcp-bundle)



The OptimusKG MCP Bundle is a [Desktop Extension](https://www.anthropic.com/engineering/desktop-extensions)
(`.mcpb`) file to query the [OptimusKG](https://optimuskg.ai/) biomedical knowledge graph in natural language.

How it works [#how-it-works]

On first launch the bundle uses the published [optimuskg](https://pypi.org/project/optimuskg/) client to fetch the graph (\~280 MB of Parquet) from Harvard Dataverse, then builds a local, indexed DuckDB database once. Every query after that runs
locally in milliseconds.

The graph data version is pinned per release via the `OPTIMUSKG_DOI` environment variable in `manifest.json`, so a given bundle always queries the same reproducible snapshot.

What you can ask [#what-you-can-ask]

* "What genes are associated with Alzheimer's disease, ranked by evidence?"
* "What does the drug aspirin target?"
* "How is aspirin connected to Alzheimer's disease?"
* "Which diseases have the most associated genes?"
* "What phenotypes are linked to the TP53 gene?"

Tools [#tools]

| Tool              | What it does                                                                          |
| ----------------- | ------------------------------------------------------------------------------------- |
| `list_schema`     | Node types, edge types, and the relation vocabulary of the graph.                     |
| `search_entities` | Resolve a name, gene symbol, synonym, or id to graph entities.                        |
| `get_entity`      | Full properties of an entity plus a summary of its connections.                       |
| `get_neighbors`   | One-hop neighbours, filterable by relation, edge type, direction, and `min_score`.    |
| `count_neighbors` | Aggregate an entity's neighbours by edge type, relation, or neighbour type.           |
| `find_connection` | Shortest path(s) between two entities.                                                |
| `run_sql`         | Read-only SQL query entrypoint over the DuckDB tables for the long tail of questions. |

Install [#install]

1. Download `optimuskg.mcpb` from the [releases page](https://github.com/mims-harvard/optimuskg/releases).
2. Double-click it to install into Claude Desktop.
3. The first query triggers a one-time download + index build; later
   queries are instant.

Requires [`uv`](https://docs.astral.sh/uv/) on your system.

Measured performance [#measured-performance]

One-time index build in 45.0 s (190,531 nodes, 21,813,816 edges) for a 2.54 GB local DuckDB cache. After that every query below runs against the cached, indexed database.

Latencies are wall-clock, warm cache, measured in-process with [`pytest-benchmark`](https://pytest-benchmark.readthedocs.io/).

| Tool              | Scenario                              | Median (ms) | Mean (ms) | Min (ms) | StdDev (ms) | Ops/s | Rounds |
| ----------------- | ------------------------------------- | ----------: | --------: | -------: | ----------: | ----: | -----: |
| `list_schema`     | describe the graph schema             |       36.01 |     36.13 |    35.01 |        0.64 |    28 |     29 |
| `search_entities` | gene symbol exact (TSPAN6)            |       71.04 |     71.58 |    70.06 |        1.37 |    14 |     14 |
| `search_entities` | disease name (Alzheimer disease)      |       28.16 |     27.38 |    22.84 |        2.66 |    37 |     43 |
| `search_entities` | substring (kinase)                    |       91.53 |     90.40 |    79.66 |        5.75 |    11 |     13 |
| `get_entity`      | gene                                  |       19.15 |     19.37 |    17.90 |        0.99 |    52 |     56 |
| `get_entity`      | disease (high-degree)                 |       49.81 |     49.84 |    46.03 |        2.39 |    20 |     23 |
| `get_neighbors`   | drug, all edges (limit 50)            |       24.53 |     24.60 |    23.76 |        0.62 |    41 |     43 |
| `get_neighbors`   | disease→gene, min\_score              |       29.60 |     29.84 |    27.65 |        1.45 |    34 |     37 |
| `count_neighbors` | hub gene, by edge type                |       37.09 |     37.36 |    33.63 |        1.92 |    27 |     31 |
| `find_connection` | 2 hops, direct neighbour              |       18.62 |     18.87 |    17.12 |        1.10 |    53 |     60 |
| `find_connection` | 2 hops, drug↔disease (hubs)           |       62.41 |     61.76 |    57.89 |        2.21 |    16 |     18 |
| `find_connection` | 2 hops, gene↔disease                  |       55.10 |     55.69 |    52.61 |        2.30 |    18 |     20 |
| `run_sql`         | group+join aggregation (top diseases) |      113.28 |    117.50 |   109.59 |       13.24 |     9 |     10 |

*Environment: Intel(R) Core(TM) Ultra 7 165U, Python 3.12.11. Regenerate with `make mcpb-profile`.*


# Showcase (/docs/showcase)



Integrations [#integrations]

* [Importing OptimusKG into TuringDB](https://docs.turingdb.ai/import_data/parquet): TuringDB's official guide on what OptimusKG is, how to use it with their database, and a sample project for spinning up OptimusKG together with TuringDB.
* [neo4j-optimuskg](https://github.com/elizarp/neo4j-optimuskg): A community project for loading OptimusKG into Neo4j.
* [**OptimusKG-lady-mem**](https://github.com/aheev/OptimusKG-lady-mem): An interactive demo of OptimusKG running on Ladybug, an embedded property graph database with a Cypher interface backed by a Parquet-based CSR format.

Featured in [#featured-in]

* [**Zitnik Lab**](https://zitniklab.hms.harvard.edu/data/): OptimusKG is listed among the datasets released by the Zitnik Lab at Harvard Medical School.
* [**Awesome Kedro**](https://github.com/kedro-org/awesome-kedro#example-projects): OptimusKG is listed as an awesome project in the official repository maintained by the Kedro community.
* [**AstraZeneca Awesome Drug Discovery Knowledge Graphs**](https://github.com/AstraZeneca/awesome-drug-discovery-knowledge-graphs/blob/main/chapters/drug_discovery_kgs.md): OptimusKG is featured in AstraZeneca's curated repository of drug discovery knowledge graphs.

Projects [#projects]

* [**WeDaita Biomedical Knowledge Graph (WBKG)**](https://www.linkedin.com/posts/wenliang-zhang_drugdiscovery-biomedicalai-knowledgegraph-share-7464889305363070976-ccOu/): WeDaita announces WBKG, an Adaptive Graph RAG system built on top of OptimusKG v2.0 and powered by Neo4j, supporting context-aware AI agents for drug discovery with local, global, and hybrid reasoning over the graph.
* [**OptimusKGVis**](https://github.com/Morgan11-tech/OptimusKGVis): A community project for visualizing the OptimusKG knowledge graph.
* [**OptimusKG-Neo4j-QA**](https://github.com/ameynarwadkar/OptimusKG-Neo4j-QA): A pipeline that extracts Alzheimer's disease data from OptimusKG into Neo4j and exposes an LLM-powered agent that answers biomedical questions via natural-language-to-Cypher translation.
* [**optimuskg-osc**](https://github.com/jkrull-lab/optimuskg-osc): A reproducible setup from the Krull Lab for running OptimusKG on the Ohio Supercomputer Center (OSC), including install scripts, utilities, and a worked example using graph-based disease discovery to supplement interpretation of disease-specific biomolecular results in hemophagocytic lymphohistiocytosis (HLH).

Media [#media]

* [**OptimusKG: The Next Step in Biomedical Knowledge Revolution**](https://www.machinebrief.com/news/optimuskg-the-next-step-in-biomedical-knowledge-revolution-prgz): News coverage of OptimusKG and its role in advancing biomedical knowledge graphs.
* [**Review of "OptimusKG: Unifying Biomedical Knowledge in a Modern Multimodal Graph"**](https://www.themoonlight.io/en/review/optimuskg-unifying-biomedical-knowledge-in-a-modern-multimodal-graph): The Moonlight's review of the OptimusKG paper.

Have you used OptimusKG in a project, talk, or blog post? [Open a PR](https://github.com/mims-harvard/optimuskg) to add it here.


# Edges (/docs/graph-schema/edges)









































OptimusKG encodes **27 edge types** connecting the node types across molecular, clinical, anatomical, and environmental domains.

| Label     | Relation(s)                                                                                                                                                                                                                                                                                                                                                                               |     Count |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------: |
| `DIS-GEN` | `ASSOCIATED_WITH`                                                                                                                                                                                                                                                                                                                                                                         | 9,734,774 |
| `ANA-GEN` | `EXPRESSION_PRESENT`, `EXPRESSION_ABSENT`                                                                                                                                                                                                                                                                                                                                                 | 8,787,955 |
| `DRG-DRG` | `SYNERGISTIC_INTERACTION`, `PARENT`                                                                                                                                                                                                                                                                                                                                                       | 1,345,376 |
| `PHE-GEN` | `ASSOCIATED_WITH`                                                                                                                                                                                                                                                                                                                                                                         |   793,279 |
| `GEN-GEN` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |   327,924 |
| `DIS-PHE` | `PHENOTYPE_PRESENT`                                                                                                                                                                                                                                                                                                                                                                       |   157,144 |
| `BPO-GEN` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |   158,410 |
| `DRG-DIS` | `INDICATION`, `CONTRAINDICATION`, `OFF_LABEL_USE`                                                                                                                                                                                                                                                                                                                                         |    70,380 |
| `MFN-GEN` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |    90,933 |
| `DRG-PHE` | `ADVERSE_DRUG_REACTION`, `ASSOCIATED_WITH`, `CONTRAINDICATION`, `INDICATION`, `OFF_LABEL_USE`                                                                                                                                                                                                                                                                                             |    13,758 |
| `PWY-GEN` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |    46,977 |
| `BPO-BPO` | `IS_A`                                                                                                                                                                                                                                                                                                                                                                                    |    44,494 |
| `DIS-DIS` | `PARENT`                                                                                                                                                                                                                                                                                                                                                                                  |    44,215 |
| `CCO-GEN` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |   105,309 |
| `DRG-GEN` | `ACTIVATOR`, `AGONIST`, `ALLOSTERIC_ANTAGONIST`, `ANTAGONIST`, `BINDING_AGENT`, `BLOCKER`, `CARRIER`, `DEGRADER`, `ENZYME`, `INHIBITOR`, `INVERSE_AGONIST`, `MODULATOR`, `NEGATIVE_ALLOSTERIC_MODULATOR`, `NEGATIVE_MODULATOR`, `OPENER`, `PARTIAL_AGONIST`, `POSITIVE_ALLOSTERIC_MODULATOR`, `POSITIVE_MODULATOR`, `RELEASING_AGENT`, `STABILISER`, `SUBSTRATE`, `TARGET`, `TRANSPORTER` |    20,694 |
| `PHE-PHE` | `PARENT`                                                                                                                                                                                                                                                                                                                                                                                  |    24,862 |
| `MFN-MFN` | `IS_A`                                                                                                                                                                                                                                                                                                                                                                                    |    12,587 |
| `PWY-PWY` | `PARENT`                                                                                                                                                                                                                                                                                                                                                                                  |     2,819 |
| `EXP-GEN` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |     2,989 |
| `EXP-DIS` | `LINKED_TO`                                                                                                                                                                                                                                                                                                                                                                               |     2,391 |
| `EXP-EXP` | `PARENT`                                                                                                                                                                                                                                                                                                                                                                                  |     2,443 |
| `EXP-BPO` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |     2,260 |
| `ANA-ANA` | `PARENT`                                                                                                                                                                                                                                                                                                                                                                                  |    17,082 |
| `CCO-CCO` | `IS_A`                                                                                                                                                                                                                                                                                                                                                                                    |     4,639 |
| `EXP-MFN` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |        47 |
| `EXP-CCO` | `INTERACTS_WITH`                                                                                                                                                                                                                                                                                                                                                                          |        13 |
| `DRG-BPO` | `INDICATION`                                                                                                                                                                                                                                                                                                                                                                              |        62 |

All edges share the same base schema in the unified `edges.parquet` and `largest_connected_component_edges.parquet` tables:

<DocsSchemaTree fields="baseEdgeSchemaFields" />

<Callout>
  In the stratified per-type parquet files (`edges/<label>.parquet`), `properties` is expanded into native typed columns as a Polars `Struct`.
</Callout>

***

Anatomy-Anatomy [#anatomy-anatomy]

<DocsSchemaTree fields="anaAnaFields" />

***

Anatomy-Gene [#anatomy-gene]

<DocsSchemaTree fields="anaGenFields" />

***

Biological Process-Biological Process [#biological-process-biological-process]

<DocsSchemaTree fields="bpoBpoFields" />

***

Biological Process-Gene [#biological-process-gene]

<DocsSchemaTree fields="bpoGenFields" />

***

Cellular Component-Cellular Component [#cellular-component-cellular-component]

<DocsSchemaTree fields="ccoCcoFields" />

***

Cellular Component-Gene [#cellular-component-gene]

<DocsSchemaTree fields="ccoGenFields" />

***

Disease-Disease [#disease-disease]

<DocsSchemaTree fields="disDisFields" />

***

Disease-Gene [#disease-gene]

<DocsSchemaTree fields="disGenFields" />

***

Disease-Phenotype [#disease-phenotype]

<DocsSchemaTree fields="disPheFields" />

***

Drug-Biological Process [#drug-biological-process]

<DocsSchemaTree fields="drgBpoFields" />

***

Drug-Disease [#drug-disease]

<DocsSchemaTree fields="drgDisFields" />

***

Drug-Drug [#drug-drug]

<DocsSchemaTree fields="drgDrgFields" />

***

Drug-Gene [#drug-gene]

<DocsSchemaTree fields="drgGenFields" />

***

Drug-Phenotype [#drug-phenotype]

<DocsSchemaTree fields="drgPheFields" />

***

Exposure-Biological Process [#exposure-biological-process]

<DocsSchemaTree fields="expBpoFields" />

***

Exposure-Cellular Component [#exposure-cellular-component]

<DocsSchemaTree fields="expCcoFields" />

***

Exposure-Disease [#exposure-disease]

<DocsSchemaTree fields="expDisFields" />

***

Exposure-Exposure [#exposure-exposure]

<DocsSchemaTree fields="expExpFields" />

***

Exposure-Gene [#exposure-gene]

<DocsSchemaTree fields="expGenFields" />

***

Exposure-Molecular Function [#exposure-molecular-function]

<DocsSchemaTree fields="expMfnFields" />

***

Gene-Gene [#gene-gene]

<DocsSchemaTree fields="genGenFields" />

***

Molecular Function-Gene [#molecular-function-gene]

<DocsSchemaTree fields="mfnGenFields" />

***

Molecular Function-Molecular Function [#molecular-function-molecular-function]

<DocsSchemaTree fields="mfnMfnFields" />

***

Pathway-Gene [#pathway-gene]

<DocsSchemaTree fields="pwyGenFields" />

***

Pathway-Pathway [#pathway-pathway]

<DocsSchemaTree fields="pwyPwyFields" />

***

Phenotype-Gene [#phenotype-gene]

<DocsSchemaTree fields="pheGenFields" />

***

Phenotype-Phenotype [#phenotype-phenotype]

<DocsSchemaTree fields="phePheFields" />

<Cards>
  <Card title="OptimusKG Client" href="/docs/optimuskg-client" />

  <Card title="Nodes" href="/docs/graph-schema/nodes" />
</Cards>


# Nodes (/docs/graph-schema/nodes)

























OptimusKG encodes **10 node types** spanning molecular, clinical, anatomical, and environmental entities.

| Label | Type               |  Count |
| ----- | ------------------ | -----: |
| `GEN` | Gene               | 61,306 |
| `DIS` | Disease            | 36,345 |
| `BPO` | Biological Process | 25,754 |
| `PHE` | Phenotype          | 19,341 |
| `DRG` | Drug               | 16,766 |
| `ANA` | Anatomy            | 13,120 |
| `MFN` | Molecular Function | 10,161 |
| `CCO` | Cellular Component |  4,052 |
| `PWY` | Pathway            |  2,805 |
| `EXP` | Exposure           |    881 |

All nodes share the same base schema:

<DocsSchemaTree fields="baseNodeFields" />

<Callout>
  In the stratified per-type parquet files (`nodes/<type>.parquet`), `properties` is expanded into native typed columns as a Polars `Struct`.
</Callout>

***

Gene [#gene]

<DocsSchemaTree fields="geneFields" />

***

Drug [#drug]

<DocsSchemaTree fields="drugFields" />

***

Disease [#disease]

<DocsSchemaTree fields="diseaseFields" />

***

Phenotype [#phenotype]

<DocsSchemaTree fields="phenotypeFields" />

***

Anatomy [#anatomy]

<DocsSchemaTree fields="anatomyFields" />

***

Pathway [#pathway]

<DocsSchemaTree fields="pathwayFields" />

***

Biological Process [#biological-process]

<DocsSchemaTree fields="biologicalProcessFields" />

***

Cellular Component [#cellular-component]

<DocsSchemaTree fields="cellularComponentFields" />

***

Molecular Function [#molecular-function]

<DocsSchemaTree fields="molecularFunctionFields" />

***

Exposure [#exposure]

<DocsSchemaTree fields="exposureFields" />

<Cards>
  <Card title="OptimusKG Client" href="/docs/optimuskg-client" />

  <Card title="Edges" href="/docs/graph-schema/edges" />
</Cards>


# Introduction (/docs/optimuskg-client)



The [`optimuskg`](https://pypi.org/project/optimuskg/) PyPI package is a thin client for loading the OptimusKG biomedical knowledge graph from [Harvard Dataverse](https://doi.org/10.7910/DVN/IYNGEV). The client resolves Dataverse file IDs automatically, caches downloads locally, and returns the graph as [Polars DataFrames](https://github.com/pola-rs/polars) or a [NetworkX MultiDiGraph](https://networkx.org/documentation/stable/reference/classes/multidigraph.html).

<Callout>
  Looking for function signatures and docstrings? Jump to the [**API
  Reference**](/docs/optimuskg-client/reference).
</Callout>

Installation [#installation]

<CodeBlockTabs defaultValue="uv">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="uv">
      uv
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pip">
      pip
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="uv">
    ```bash
    uv add optimuskg
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pip">
    ```bash
    pip install optimuskg
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Quick Start [#quick-start]

```python
import optimuskg

# Download a specific file and store it locally
local_path = optimuskg.get_file("nodes/gene.parquet")

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

# Load nodes and edges as Polars DataFrames
# Set lcc=True to load only the largest connected component
nodes, edges = optimuskg.load_graph(lcc=True)

# Load the graph as a NetworkX MultiDiGraph with metadata
# Set lcc=True to load only the largest connected component
G = optimuskg.load_networkx(lcc=True)
```

See [`get_file`](/docs/optimuskg-client/reference), [`load_parquet`](/docs/optimuskg-client/reference), [`load_graph`](/docs/optimuskg-client/reference), and [`load_networkx`](/docs/optimuskg-client/reference) on the reference page for parameters and return types.

Loader overview [#loader-overview]

Files [#files]

[`get_file`](/docs/optimuskg-client/reference) downloads the file if not already cached and returns its local path. Paths follow the layout of the catalog in the source repository:

```python
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 table
optimuskg.get_file("largest_connected_component_edges.parquet")   # LCC edges table
optimuskg.get_file("nodes/gene.parquet")                          # only Gene nodes
optimuskg.get_file("edges/disease_gene.parquet")                  # only DIS-GEN edges
```

<Callout>
  Pass `force=True` to re-download the file even if it is already cached.
</Callout>

DataFrames [#dataframes]

[`load_parquet`](/docs/optimuskg-client/reference) calls `get_file` then `polars.read_parquet`. Any extra keyword arguments are forwarded directly to `pl.read_parquet`.

```python
drugs = optimuskg.load_parquet("nodes/drug.parquet")
only_ids = optimuskg.load_parquet("nodes/drug.parquet", columns=["id"])
```

[`load_graph`](/docs/optimuskg-client/reference) returns `(nodes, edges)` as Polars DataFrames. Pass `lcc=True` to get only the largest connected component.

```python
nodes, edges = optimuskg.load_graph()          # full graph
nodes, edges = optimuskg.load_graph(lcc=True)  # LCC only
```

<Callout>
  DataFrame schemas are documented in [Nodes](/docs/graph-schema/nodes) and [Edges](/docs/graph-schema/edges).
</Callout>

NetworkX [#networkx]

[`load_networkx`](/docs/optimuskg-client/reference) builds a `networkx.MultiDiGraph` on top of `load_graph`:

```python
G = optimuskg.load_networkx(lcc=True)
print(G.number_of_nodes(), G.number_of_edges())

# Filter by node label
genes = [n for n, attrs in G.nodes(data=True) if attrs["label"] == "GEN"]

# Filter by relation type
expression_edges = [
    (u, v) for u, v, attrs in G.edges(data=True)
    if attrs["relation"] == "EXPRESSION_PRESENT"
]
```

<Callout type="info">
  `properties`

   JSON strings are parsed and merged into node/edge attribute dicts. Set 

  `parse_properties=False`

   to skip this and keep the raw string.
</Callout>

<Callout type="info">
  The graph is always a 

  `MultiDiGraph`

   regardless of edge directionality. Call 

  `G.to_undirected()`

   if you need an undirected view.
</Callout>

Configuration [#configuration]

Cache directory [#cache-directory]

Downloads are cached by default in `platformdirs.user_cache_dir("optimuskg")` (`~/Library/Caches/optimuskg` on macOS, `~/.cache/optimuskg` on Linux, and `C:\Users\<User>\AppData\Local\optimuskg\optimuskg` on Windows). Files within the cache are keyed by `<doi_slug>/<dataset_version>/<relative_path>`, so a new Dataverse release invalidates the cache automatically.

It is possible to override the cache directory from code with [`set_cache_dir`](/docs/optimuskg-client/reference):

```python
optimuskg.set_cache_dir("/data/optimuskg-cache")
```

Or by using environment variables:

```bash
export OPTIMUSKG_CACHE_DIR=/data/optimuskg-cache
```

Pointing at a different dataset [#pointing-at-a-different-dataset]

By default the client targets the published OptimusKG dataset at `doi:10.7910/DVN/IYNGEV`. To target a different version (e.g. a pre-release or private dataset), override the DOI from code with [`set_doi`](/docs/optimuskg-client/reference):

```python
optimuskg.set_doi("doi:10.7910/DVN/EXAMPLE")
```

Or by using environment variables:

```bash
export OPTIMUSKG_DOI=doi:10.7910/DVN/EXAMPLE
```

For a non-Harvard Dataverse installation, override the server URL from code with [`set_server`](/docs/optimuskg-client/reference):

```python
optimuskg.set_server("https://dataverse.example.org")
```

Or by using environment variables:

```bash
export OPTIMUSKG_SERVER=https://dataverse.example.org
```

Agent Skill [#agent-skill]

OptimusKG ships an [agent skill](https://github.com/mims-harvard/optimuskg/blob/main/skills/optimuskg/SKILL.md) that teaches AI agents how to use the `optimuskg` client. With the skill installed, you can ask your agent to load, filter, and analyze the graph in natural language, and it already knows the client's API, file layout, and schema.

Installing the skill [#installing-the-skill]

Add the skill to any project with the `skills` CLI:

```bash
npx skills add https://github.com/mims-harvard/optimuskg --skill optimuskg
```

What the skill does [#what-the-skill-does]

The skill bundles everything an agent needs to be productive with OptimusKG:

* **Loaders**: when to reach for `get_file`, `load_parquet`, `load_graph`, or `load_networkx`, and what each returns.
* **Graph schema**: the node type codes, the node and edge columns, and how `properties` are expanded into typed columns.
* **Common patterns**: filtering DataFrames or a NetworkX graph by entity type and relation for analysis, Graph-RAG, or ML.
* **Configuration**: caching, and pointing the client at a different Dataverse release or server via `set_doi` / `set_server` or environment variables.
* **Citation and license**: reminders to cite OptimusKG and to respect each source dataset's terms.

Using it [#using-it]

Once installed, describe what you want in natural language and the agent applies the skill automatically. For example:

> Load the largest connected component as a NetworkX graph and list the drugs associated with Alzheimer's disease.

The agent installs `optimuskg` if needed, picks the right loader, filters by the correct node labels and relations, and caches the downloads, following the conventions documented in the skill.

See Also [#see-also]

<Cards>
  <Card title="API Reference" href="/docs/optimuskg-client/reference" />

  <Card title="Nodes" href="/docs/graph-schema/nodes" />

  <Card title="Edges" href="/docs/graph-schema/edges" />
</Cards>


# Reference (/docs/optimuskg-client/reference)



Client for the OptimusKG biomedical knowledge graph on Harvard Dataverse.

<PyAttribute name="&#x22;__version__&#x22;" type="null" value="&#x22;'0.1.0'&#x22;" />

<PyAttribute name="&#x22;__all__&#x22;" type="null" value="&#x22;['__version__', 'get_cache_dir', 'get_doi', 'get_file', 'get_server', 'load_graph', 'load_networkx', 'load_parquet', 'set_cache_dir', 'set_doi', 'set_server']&#x22;" />

<PyAttribute name="&#x22;DEFAULT_SERVER&#x22;" type="null" value="&#x22;'https://dataverse.harvard.edu'&#x22;" />

<PyAttribute name="&#x22;DEFAULT_DOI&#x22;" type="null" value="&#x22;'doi:10.7910/DVN/IYNGEV'&#x22;" />

<Tabs items="[&#x22;Functions&#x22;]">
  <Tab value="&#x22;Functions&#x22;">
    <PyFunction name="&#x22;get_file&#x22;" type="&#x22;(relative_path, *, force=False) -> Path&#x22;">
      Return the local path to a parquet file, downloading from Dataverse if missing.

      Paths mirror the layout under `data/gold/kg/parquet/` in the source repo.

      <PySourceCode>
        ```python
        def get_file(relative_path: str, *, force: bool = False) -> Path:
            """Return the local path to a parquet file, downloading from Dataverse if missing.

            Paths mirror the layout under ``data/gold/kg/parquet/`` in the source repo.
            """
            return _dataverse.download(relative_path, force=force)
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;relative_path&#x22;" type="&#x22;str&#x22;" value="null" />

        <PyParameter name="&#x22;force&#x22;" type="&#x22;bool&#x22;" value="&#x22;False&#x22;" />
      </div>

      <PyFunctionReturn type="&#x22;pathlib.Path&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;load_parquet&#x22;" type="&#x22;(relative_path, *, force=False, **read_parquet_kwargs) -> pl.DataFrame&#x22;">
      Download (if needed) and read a parquet file as a Polars DataFrame.

      <PySourceCode>
        ```python
        def load_parquet(
            relative_path: str,
            *,
            force: bool = False,
            **read_parquet_kwargs: Any,
        ) -> pl.DataFrame:
            """Download (if needed) and read a parquet file as a Polars DataFrame."""
            path = get_file(relative_path, force=force)
            return pl.read_parquet(path, **read_parquet_kwargs)
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;relative_path&#x22;" type="&#x22;str&#x22;" value="null" />

        <PyParameter name="&#x22;force&#x22;" type="&#x22;bool&#x22;" value="&#x22;False&#x22;" />

        <PyParameter name="&#x22;read_parquet_kwargs&#x22;" type="&#x22;Any&#x22;" value="&#x22;{}&#x22;" />
      </div>

      <PyFunctionReturn type="&#x22;polars.polars.DataFrame&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;load_graph&#x22;" type="&#x22;(*, lcc=False, force=False) -> tuple[pl.DataFrame, pl.DataFrame]&#x22;">
      Return `(nodes, edges)` Polars DataFrames for the full graph or its LCC.

      <PySourceCode>
        ```python
        def load_graph(
            *,
            lcc: bool = False,
            force: bool = False,
        ) -> tuple[pl.DataFrame, pl.DataFrame]:
            """Return ``(nodes, edges)`` Polars DataFrames for the full graph or its LCC."""
            nodes_file, edges_file = _LCC if lcc else _FULL
            nodes = load_parquet(nodes_file, force=force)
            edges = load_parquet(edges_file, force=force)
            return nodes, edges
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;lcc&#x22;" type="&#x22;bool&#x22;" value="&#x22;False&#x22;" />

        <PyParameter name="&#x22;force&#x22;" type="&#x22;bool&#x22;" value="&#x22;False&#x22;" />
      </div>

      <PyFunctionReturn type="&#x22;tuple[polars.polars.DataFrame, polars.polars.DataFrame]&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;load_networkx&#x22;" type="&#x22;(*, lcc=False, force=False, parse_properties=True) -> nx.MultiDiGraph&#x22;">
      Return the graph as a `nx.MultiDiGraph` with properties loaded onto attrs.

      <PySourceCode>
        ```python
        def load_networkx(
            *,
            lcc: bool = False,
            force: bool = False,
            parse_properties: bool = True,
        ) -> nx.MultiDiGraph:
            """Return the graph as a ``nx.MultiDiGraph`` with properties loaded onto attrs."""
            if not lcc:
                warnings.warn(
                    "Loading the full graph into NetworkX requires several GB of memory "
                    "(190k nodes, 21M edges). Pass lcc=True for a slightly smaller, "
                    "connected variant.",
                    stacklevel=2,
                )
            nodes, edges = load_graph(lcc=lcc, force=force)
            return _graph.build_multidigraph(nodes, edges, parse_properties=parse_properties)
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;lcc&#x22;" type="&#x22;bool&#x22;" value="&#x22;False&#x22;" />

        <PyParameter name="&#x22;force&#x22;" type="&#x22;bool&#x22;" value="&#x22;False&#x22;" />

        <PyParameter name="&#x22;parse_properties&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;" />
      </div>

      <PyFunctionReturn type="&#x22;networkx.networkx.MultiDiGraph&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;get_server&#x22;" type="&#x22;() -> str&#x22;">
      Return the Dataverse server URL.

      <PySourceCode>
        ```python
        def get_server() -> str:
            """Return the Dataverse server URL."""
            return _state["server"] or os.environ.get("OPTIMUSKG_SERVER") or DEFAULT_SERVER
        ```
      </PySourceCode>

      <PyFunctionReturn type="&#x22;str&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;set_server&#x22;" type="&#x22;(url) -> None&#x22;">
      Override the Dataverse server URL for the current process.

      <PySourceCode>
        ```python
        def set_server(url: str) -> None:
            """Override the Dataverse server URL for the current process."""
            _state["server"] = url.rstrip("/")
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="null" />
      </div>

      <PyFunctionReturn type="&#x22;None&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;get_doi&#x22;" type="&#x22;() -> str&#x22;">
      Return the persistent identifier for the OptimusKG dataset.

      <PySourceCode>
        ```python
        def get_doi() -> str:
            """Return the persistent identifier for the OptimusKG dataset."""
            return _state["doi"] or os.environ.get("OPTIMUSKG_DOI") or DEFAULT_DOI
        ```
      </PySourceCode>

      <PyFunctionReturn type="&#x22;str&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;set_doi&#x22;" type="&#x22;(doi) -> None&#x22;">
      Override the dataset DOI for the current process.

      <PySourceCode>
        ```python
        def set_doi(doi: str) -> None:
            """Override the dataset DOI for the current process."""
            _state["doi"] = doi
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;doi&#x22;" type="&#x22;str&#x22;" value="null" />
      </div>

      <PyFunctionReturn type="&#x22;None&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;get_cache_dir&#x22;" type="&#x22;() -> Path&#x22;">
      Return the root directory where downloaded files are cached.

      <PySourceCode>
        ```python
        def get_cache_dir() -> Path:
            """Return the root directory where downloaded files are cached."""
            raw = _state["cache_dir"] or os.environ.get("OPTIMUSKG_CACHE_DIR")
            return Path(raw).expanduser() if raw else Path(user_cache_dir("optimuskg"))
        ```
      </PySourceCode>

      <PyFunctionReturn type="&#x22;pathlib.Path&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;set_cache_dir&#x22;" type="&#x22;(path) -> None&#x22;">
      Override the local cache directory for the current process.

      <PySourceCode>
        ```python
        def set_cache_dir(path: str | os.PathLike[str]) -> None:
            """Override the local cache directory for the current process."""
            _state["cache_dir"] = str(path)
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;path&#x22;" type="&#x22;str | os.PathLike[str]&#x22;" value="null" />
      </div>

      <PyFunctionReturn type="&#x22;None&#x22;" />
    </PyFunction>
  </Tab>
</Tabs>