### Install OptimusKG Client

Source: https://github.com/mims-harvard/optimuskg/blob/main/packages/optimuskg/README.md

Install the OptimusKG client using pip or pipx.

```bash
pip install optimuskg
```

```bash
pipx install optimuskg
```

--------------------------------

### Install OptimusKG Client

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/index.mdx

Install the OptimusKG Python client using either uv or pip.

```bash
uv add optimuskg
```

```bash
pip install optimuskg
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/mims-harvard/optimuskg/blob/main/assets/remotion/README.md

Run this command to install all necessary project dependencies.

```bash
npm i
```

--------------------------------

### Start Neo4j Database

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Starts the Neo4j graph database instance using a make command.

```bash
make neo4j
```

--------------------------------

### Start Remotion Preview Server

Source: https://github.com/mims-harvard/optimuskg/blob/main/assets/remotion/README.md

Use this command to launch the local development server for previewing your Remotion compositions.

```bash
npm run dev
```

--------------------------------

### Start Kedro Visualization

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Launches the Kedro visualization tool to explore the data pipeline.

```bash
make kedro-viz
```

--------------------------------

### Install optimuskg Python Client

Source: https://github.com/mims-harvard/optimuskg/blob/main/README.md

Install the OptimusKG Python client using pip or pipx. This client allows programmatic access to the knowledge graph data.

```bash
# With pip.
pip install optimuskg
```

```bash
# Or pipx.
pipx install optimuskg
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Installs pre-commit hooks to ensure code quality and consistency before commits.

```bash
uv tool run pre-commit install
```

--------------------------------

### Install All Dependencies with uv

Source: https://github.com/mims-harvard/optimuskg/blob/main/CONTRIBUTING.md

Installs all project dependencies, including development groups, using the uv package manager.

```console
uv sync --all-groups

Resolved 234 packages in 1ms
Audited 225 packages in 0.42ms
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Use this command to synchronize project dependencies.

```bash
uv sync --all-groups
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/mims-harvard/optimuskg/blob/main/CONTRIBUTING.md

Installs the pre-commit framework to manage and automate Git hooks for code quality checks.

```console
uv run pre-commit install
pre-commit installed at .git/hooks/pre-commit
```

--------------------------------

### Run Development Server

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/README.md

Commands to start the development server for the Next.js application using npm, pnpm, or yarn.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

--------------------------------

### Quick Start: Load OptimusKG Data

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Demonstrates downloading a file, loading a Parquet file as a Polars DataFrame, and loading the graph as Polars DataFrames or a NetworkX MultiDiGraph.

```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)
```

--------------------------------

### Configure Pipeline Parameters

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Example of pipeline parameters in `parameters.yml` to control dataset validation behavior.

```yaml
# conf/base/parameters.yml — pipeline parameters
gold.validate_biocypher: false

gold.export_formats:
  parquet:
    include_properties: true
  # neo4j:
  #   include_properties: true
```

--------------------------------

### Set Dataverse Server URL via Environment Variable

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Specify the Dataverse server URL by setting the `OPTIMUSKG_SERVER` environment variable. This allows the client to connect to different Dataverse installations.

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

--------------------------------

### Get Dataverse Server URL

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Retrieves the configured Dataverse server URL. It checks the internal state, the OPTIMUSKG_SERVER environment variable, and falls back to a default URL.

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

--------------------------------

### Get File Path

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Use get_file to download a file if not cached and return its local path. Pass force=True to re-download.

```python
optimuskg.get_file("nodes.parquet")                               # full nodes table
```

```python
optimuskg.get_file("edges.parquet")                               # full edges table
```

```python
optimuskg.get_file("largest_connected_component_nodes.parquet")   # LCC nodes table
```

```python
optimuskg.get_file("largest_connected_component_edges.parquet")   # LCC edges table
```

```python
optimuskg.get_file("nodes/gene.parquet")                          # only Gene nodes
```

```python
optimuskg.get_file("edges/disease_gene.parquet")                  # only DIS-GEN edges
```

--------------------------------

### Set Dataverse Server URL Programmatically

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Configure the client to connect to a non-Harvard Dataverse installation by calling `set_server` with the correct server URL. This is necessary when working with custom or private Dataverse instances.

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

--------------------------------

### Get File Path

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Retrieves the local path to a Parquet file, downloading it from Dataverse if it's not found locally. Paths should correspond to the layout in the source repository's data directory.

```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)
```

--------------------------------

### Get Cache Directory

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Returns the root directory where downloaded files are cached. It prioritizes an internal state, then an environment variable, and falls back to a user-specific cache directory if neither is set.

```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"))
```

--------------------------------

### Run Kedro Downstream from Node

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Executes nodes in a Kedro pipeline starting from a specified node and cascading downstream.

```bash
uv run kedro run --from-nodes=<node_name>
```

--------------------------------

### Display CLI Help

Source: https://github.com/mims-harvard/optimuskg/blob/main/CONTRIBUTING.md

Shows the help message for the OptimusKG CLI, listing available commands and options.

```console
uv run cli --help
```

--------------------------------

### CLI Utilities for OptimusKG

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Provides access to command-line interface utilities for managing the OptimusKG project, including help, checksum validation, catalog synchronization, and metric generation.

```bash
uv run cli --help
```

```bash
uv run cli checksum           # Validate file checksums
```

```bash
uv run cli sync-catalog       # Sync schema + checksum from parquet to catalog YAML
```

```bash
uv run cli metrics            # Generate graph metrics
```

--------------------------------

### Download and Load OptimusKG Data

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/index.mdx

Demonstrates how to download specific files, load Parquet files as Polars DataFrames, and load the entire graph as DataFrames or a NetworkX MultiDiGraph.

```python
import optimuskg

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

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

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

```python
# 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)
```

--------------------------------

### Get Dataset DOI

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Retrieves the persistent identifier for the OptimusKG dataset. It first checks an internal state, then an environment variable, and finally a default value.

```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
```

--------------------------------

### Format Code with Make

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Applies code formatting rules to the project.

```bash
make format
```

--------------------------------

### Run full data pipeline

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Executes the complete OptimusKG data pipeline, including downloading, processing (bronze, silver), and exporting the knowledge graph. Utilizes Kedro for workflow management.

```bash
# Run the full pipeline with parallel execution and async I/O
uv run kedro run --to-nodes gold.export_kg \
    --runner=optimuskg.runners.FixedParallelRunner \
    --async

# Run only the bronze layer (data extraction and standardization)
uv run kedro run --pipeline bronze

# Run only the silver layer (entity consolidation and edge construction)
uv run kedro run --pipeline silver

# Run a specific node by name
uv run kedro run --nodes bronze.opentargets_disease

# Run all nodes downstream from a specific node (cascade)
uv run kedro run --from-nodes=bronze.opentargets_disease

# Dry run: list nodes that would execute without running anything
uv run kedro run --from-nodes=silver.gene \
    --runner=optimuskg.runners.DryRunner
# INFO - Actual run would execute 12 nodes:
# silver.gene: consolidate_genes([...]) -> [silver.nodes.gene]
# ...
```

--------------------------------

### Render Video with Remotion CLI

Source: https://github.com/mims-harvard/optimuskg/blob/main/assets/remotion/README.md

Execute this command to render your Remotion video compositions using the command-line interface.

```bash
npx remotion render
```

--------------------------------

### Run OptimusKG Data Pipeline

Source: https://github.com/mims-harvard/optimuskg/blob/main/README.md

Execute the full knowledge graph generation pipeline. This command downloads data, processes it through bronze, silver, and gold layers, and exports the graph. It utilizes a fixed parallel runner for concurrency and an async flag for potential performance gains.

```console
$ uv run kedro run --to-nodes gold.export_kg --runner=optimuskg.runners.FixedParallelRunner --async

[01/28/25 19:29:07] INFO     Using 'conf/logging.yml' as logging configuration. You can change this by setting the KEDRO_LOGGING_CONFIG environment variable accordingly.
[01/28/25 19:29:08] INFO     Kedro project optimuskg
[01/28/25 19:29:09] INFO     Using synchronous mode for loading and saving data. Use the --async flag for potential performance gains.
```

--------------------------------

### Download and Cache a File

Source: https://github.com/mims-harvard/optimuskg/blob/main/packages/optimuskg/README.md

Download a file from the gold layer and cache it locally. This is typically done once.

```python
import optimuskg

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

--------------------------------

### Override Dataverse server URL

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Redirects API calls to an alternative Dataverse server instance, useful for testing or using local installations. This can also be set via the `$OPTIMUSKG_SERVER` environment variable.

```python
import optimuskg

print(optimuskg.get_server())
# https://dataverse.harvard.edu

# Point to a custom Dataverse instance
optimuskg.set_server("https://my-institution.dataverse.org")

# Downloads now resolve files from the new server
path = optimuskg.get_file("nodes/gene.parquet")
```

--------------------------------

### Configure OptimusKG Cache Directory

Source: https://github.com/mims-harvard/optimuskg/blob/main/README.md

The download cache location can be overridden using the $OPTIMUSKG_CACHE_DIR environment variable or programmatically with optimuskg.set_cache_dir().

```python
optimuskg.set_cache_dir(path)
```

--------------------------------

### Upgrade Remotion Version

Source: https://github.com/mims-harvard/optimuskg/blob/main/assets/remotion/README.md

Run this command to upgrade your Remotion project to the latest version.

```bash
npx remotion upgrade
```

--------------------------------

### Data Pipeline API - Running the full pipeline

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Build the complete knowledge graph by running the full data pipeline, which downloads, processes, and exports graph data.

```APIDOC
## Running the full pipeline

### Description
Build the complete knowledge graph by running the full data pipeline, which downloads all source data (landing layer), processes it through bronze and silver transformations, and exports the final graph to `data/gold/kg/`.

### Commands
- **Run the full pipeline**: `uv run kedro run --to-nodes gold.export_kg --runner=optimuskg.runners.FixedParallelRunner --async`
- **Run only the bronze layer**: `uv run kedro run --pipeline bronze`
- **Run only the silver layer**: `uv run kedro run --pipeline silver`
- **Run a specific node**: `uv run kedro run --nodes bronze.opentargets_disease`
- **Run all nodes downstream from a specific node**: `uv run kedro run --from-nodes=bronze.opentargets_disease`
- **Dry run (list nodes without executing)**: `uv run kedro run --from-nodes=silver.gene --runner=optimuskg.runners.DryRunner`
```

--------------------------------

### Preview Catalog Sync Changes

Source: https://github.com/mims-harvard/optimuskg/blob/main/CONTRIBUTING.md

Performs a dry run of the catalog synchronization, showing potential changes without modifying files.

```console
# Preview changes without writing files
$ uv run cli sync-catalog --dry-run
```

--------------------------------

### Set Cache Directory via Environment Variable

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Configure the cache directory by setting the `OPTIMUSKG_CACHE_DIR` environment variable. This method allows for environment-specific configurations without code changes.

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

--------------------------------

### Run Pipeline with Automatic Data Downloads

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Execute Kedro runs where OriginHooks automatically download datasets if they are missing. Downloaded data is cached and reused for subsequent runs.

```bash
# Origins are resolved automatically when the pipeline runs.
# Data is downloaded once and reused on subsequent runs.
uv run kedro run --pipeline bronze
# INFO - Attempting download for landing.ctd.ctd_exposure_events using http provider.
# Downloading... ━━━━━━━━━━━━━━━━ 142.3 MB/142.3 MB 8.1 MB/s 0:00:00
# INFO - Skipping download for landing.opentargets.disease because it already exists.
```

--------------------------------

### optimuskg.load_networkx

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Downloads the graph and constructs a networkx.MultiDiGraph with nodes and edges carrying full metadata. JSON property strings are parsed and splatted onto node/edge attributes when parse_properties=True (default).

```APIDOC
## optimuskg.load_networkx

### Description
Downloads the graph and constructs a `networkx.MultiDiGraph` with nodes and edges carrying full metadata. JSON property strings are parsed and splatted onto node/edge attributes when `parse_properties=True` (default).

### Parameters
#### Query Parameters
- **lcc** (bool) - Optional - If True, loads only the largest connected component of the graph.
- **parse_properties** (bool) - Optional - If True, parses JSON property strings into node/edge attributes. Defaults to True.

### Request Example
```python
import optimuskg

G = optimuskg.load_networkx(lcc=True)
```

### Response
- **G** (networkx.MultiDiGraph) - A MultiDiGraph object representing the knowledge graph.
```

--------------------------------

### Download a single Parquet file with caching

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Use `get_file` to download a specific Parquet file from the gold layer. Subsequent calls will use the cached file unless `force=True` is specified. The cache location is configurable and follows a structured path.

```python
import optimuskg

# Download nodes/gene.parquet (cached after first call)
path = optimuskg.get_file("nodes/gene.parquet")
print(path)
# ~/.cache/optimuskg/doi_10_7910_DVN_IYNGEV/1.0/nodes/gene.parquet

# Force re-download even if the file exists locally
path = optimuskg.get_file("nodes/drug.parquet", force=True)

# Available paths mirror data/gold/kg/parquet/ in the pipeline:
# nodes/gene.parquet, nodes/drug.parquet, nodes/disease.parquet, ...
# edges/drug_gene.parquet, edges/disease_gene.parquet, ...
# nodes.parquet  (consolidated all nodes, JSON-encoded properties)
# edges.parquet  (consolidated all edges, JSON-encoded properties)
# largest_connected_component_nodes.parquet
# largest_connected_component_edges.parquet
```

--------------------------------

### optimuskg.set_server / get_server

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Override the Dataverse server URL to redirect all API calls to an alternative Dataverse server instance.

```APIDOC
## optimuskg.set_server / get_server

### Description
Redirects all API calls to an alternative Dataverse server instance. Useful for testing against a local or institutional Dataverse installation.

### Methods
- **get_server()**: Returns the current Dataverse server URL.
- **set_server(url: str)**: Sets the Dataverse server URL for all subsequent API calls.

### Environment Variable
- **OPTIMUSKG_SERVER**: Can be set to specify the Dataverse server URL.

### Request Example
```python
import optimuskg

print(optimuskg.get_server())
optimuskg.set_server("https://my-institution.dataverse.org")
```
```

--------------------------------

### Check Docstring Coverage with Make

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Measures docstring coverage as a CI check.

```bash
make interrogate
```

--------------------------------

### get_server

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Return the Dataverse server URL.

```APIDOC
## get_server

### Description
Return the Dataverse server URL.

### Method
`get_server() -> str`

### Response
- **str** - The Dataverse server URL.
```

--------------------------------

### Sync Catalog Schemas and Checksums

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Synchronizes catalog schemas and checksums by reading Parquet files and updating the catalog YAML. Essential after dataset modifications.

```bash
# Sync all datasets across all layers
uv run cli sync-catalog

```

```bash
# Sync only the bronze layer
uv run cli sync-catalog --layer bronze

```

```bash
# Sync a single specific dataset
uv run cli sync-catalog --dataset bronze.opentargets.disease

```

```bash
# Validate without writing (check for drift)
uv run cli sync-catalog --validate

```

```bash
# Preview changes without writing (dry run)
uv run cli sync-catalog --layer silver --dry-run

```

```bash
# Sync with custom paths
uv run cli sync-catalog \
    --catalog-dir conf/base/catalog \
    --data-dir data

```

--------------------------------

### Load Final Gold Knowledge Graph in Kedro Jupyter Session

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Loads the final 'gold.kg.parquet' dataset from the Kedro catalog and prints the head of both the nodes and edges DataFrames. Assumes a Kedro Jupyter session.

```python
# Load the final gold knowledge graph
kg = catalog.load("gold.kg.parquet")
print(kg["nodes"].head())
print(kg["edges"].head())
```

--------------------------------

### Generate Graph Metrics Parquet Files

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Generates graph metrics (degree distribution, centrality, etc.) from gold KG Parquet files and writes summary metrics to specified output directories.

```bash
# Generate metrics from the default gold KG output
uv run cli metrics

```

```bash
# Specify custom input/output directories
uv run cli metrics \
    --nodes data/gold/kg/parquet/nodes \
    --edges data/gold/kg/parquet/edges \
    --out data/gold/metrics

```

```bash
# Generate and display specific figure types
uv run cli figure degree-distribution
uv run cli figure ccdf-degree-distribution
uv run cli figure adjacency-heatmap
uv run cli figure metaedge-bubble-plot
uv run cli figure closeness-centrality

```

--------------------------------

### Sync Catalog with CLI

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Synchronizes the Kedro catalog, updating schema and checksums from Parquet files to catalog YAML. This is a critical step after editing nodes.

```bash
uv run cli sync-catalog --dataset {catalog_id}
```

--------------------------------

### Resolve Raw Database Strings to Canonical Source Names

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Demonstrates the use of the resolve_source function to map raw database strings to their canonical source names.

```python
print(resolve_source("drugbank"))     # 'DRUG_BANK'
print(resolve_source("OnSIDES"))      # 'ONSIDES'
print(resolve_source("opentargets"))  # 'OPEN_TARGETS'
```

--------------------------------

### Run Pytest with Hatch

Source: https://github.com/mims-harvard/optimuskg/blob/main/CONTRIBUTING.md

Executes the test suite using pytest, managed by hatch to apply pre-configured flags from pyproject.toml.

```console
uv tool run hatch run pytest
```

--------------------------------

### Manually Calculate and Verify Checksums

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Use the `calculate_checksum` utility or the CLI to compute and verify file checksums. This is useful for debugging or manual checks.

```python
# Checksums are validated automatically before each dataset load.
# To manually compute and verify a checksum:
from optimuskg.utils import calculate_checksum
from pathlib import Path

checksum = calculate_checksum(Path("data/bronze/opentargets/disease.parquet"))
print(checksum)  # "a3f9c1b2e4d8f6a0"

# Or via CLI
uv run cli checksum data/bronze/opentargets/disease.parquet
# INFO - The checksum of 'data/bronze/opentargets/disease.parquet' is: a3f9c1b2e4d8f6a0

# Compare against an expected value
uv run cli checksum data/bronze/opentargets/disease.parquet \
    --checksum a3f9c1b2e4d8f6a0
# INFO - The checksum of '...' is correct
```

--------------------------------

### Configure Data Origins for Automatic Downloads

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Define data origins in catalog entries for automatic downloading before pipeline runs. OriginHooks handle downloads for `landing.*` datasets using specified providers and URLs.

```yaml
# conf/base/catalog/landing/opentargets.yaml
landing.opentargets.disease:
  type: kedro_datasets.polars.CSVDataset
  filepath: data/landing/opentargets/disease.csv
  metadata:
    origin:
      provider: opentargets    # Uses OpenTargets FTP provider
      dataset: disease

landing.ctd.ctd_exposure_events:
  type: kedro_datasets.polars.CSVDataset
  filepath: data/landing/ctd/ctd_exposure_events.csv
  metadata:
    origin:
      provider: http
      url: "https://ctdbase.org/reports/CTD_exposure_events.csv.gz"
      decompress: true
```

--------------------------------

### Configure local cache directory

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Sets or retrieves the local directory for storing downloaded Parquet files. The default is determined by `platformdirs.user_cache_dir`. This can also be configured via the `$OPTIMUSKG_CACHE_DIR` environment variable.

```python
import optimuskg
from pathlib import Path

# Check current cache directory
print(optimuskg.get_cache_dir())
# /home/user/.cache/optimuskg  (Linux)
# /Users/user/Library/Caches/optimuskg  (macOS)

# Override programmatically for this process
optimuskg.set_cache_dir("/data/optimuskg-cache")
print(optimuskg.get_cache_dir())
# /data/optimuskg-cache

# Or use the environment variable before running:
# OPTIMUSKG_CACHE_DIR=/data/optimuskg-cache python my_script.py
```

--------------------------------

### Target Different OptimusKG Datasets

Source: https://github.com/mims-harvard/optimuskg/blob/main/README.md

To access datasets other than the default (e.g., pre-releases), set the $OPTIMUSKG_DOI environment variable or use optimuskg.set_doi().

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

--------------------------------

### Run Full Kedro Pipeline

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Executes the entire Kedro pipeline, targeting the gold export node and using a fixed parallel runner for asynchronous execution.

```bash
uv run kedro run --to-nodes gold.export_kg --runner=optimuskg.runners.FixedParallelRunner --async
```

--------------------------------

### load_parquet

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Download (if needed) and read a parquet file as a Polars DataFrame.

```APIDOC
## load_parquet

### Description
Download (if needed) and read a parquet file as a Polars DataFrame.

### Method
`load_parquet(relative_path: str, *, force: bool = False, **read_parquet_kwargs) -> pl.DataFrame`

### Parameters
#### Path Parameters
- **relative_path** (str) - Required - The relative path to the parquet file.
- **force** (bool) - Optional - If True, force download even if the file exists. Defaults to False.
- **read_parquet_kwargs** (Any) - Optional - Additional keyword arguments to pass to `pl.read_parquet`.

### Response
- **pl.DataFrame** - A Polars DataFrame containing the data from the parquet file.
```

--------------------------------

### optimuskg.get_file

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Downloads a single Parquet file from the gold layer of Harvard Dataverse with local caching. Subsequent calls reuse the cached file unless `force=True` is specified. The function returns the local `Path` to the cached file.

```APIDOC
## optimuskg.get_file

### Description
Downloads a single Parquet file from the gold layer of Harvard Dataverse with local caching. Subsequent calls reuse the cached file unless `force=True` is specified. The function returns the local `Path` to the cached file.

### Parameters
- **file_path** (str) - Required - The relative path to the file within the Dataverse repository (e.g., "nodes/gene.parquet").
- **force** (bool) - Optional - If `True`, forces a re-download of the file even if it exists locally. Defaults to `False`.

### Returns
- **pathlib.Path** - The local path to the downloaded or cached Parquet file.

### Request Example
```python
import optimuskg

# Download nodes/gene.parquet (cached after first call)
path = optimuskg.get_file("nodes/gene.parquet")
print(path)
# ~/.cache/optimuskg/doi_10_7910_DVN_IYNGEV/1.0/nodes/gene.parquet

# Force re-download even if the file exists locally
path = optimuskg.get_file("nodes/drug.parquet", force=True)
```

### Available Paths
Available paths mirror `data/gold/kg/parquet/` in the pipeline:
- `nodes/gene.parquet`
- `nodes/drug.parquet`
- `nodes/disease.parquet`
- `edges/drug_gene.parquet`
- `edges/disease_gene.parquet`
- `nodes.parquet` (consolidated all nodes, JSON-encoded properties)
- `edges.parquet` (consolidated all edges, JSON-encoded properties)
- `largest_connected_component_nodes.parquet`
- `largest_connected_component_edges.parquet`
```

--------------------------------

### Set Target Dataset DOI via Environment Variable

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Specify the target dataset DOI by setting the `OPTIMUSKG_DOI` environment variable. This is an alternative to programmatic configuration for targeting specific datasets.

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

--------------------------------

### Lint Code with Make

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Performs code linting as a CI check to identify potential issues.

```bash
make lint
```

--------------------------------

### optimuskg.load_parquet

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Downloads (if needed) and reads a single Parquet file from Harvard Dataverse, returning a Polars `DataFrame`. Any keyword arguments are forwarded to `polars.read_parquet`.

```APIDOC
## optimuskg.load_parquet

### Description
Downloads (if needed) and reads a single Parquet file from Harvard Dataverse, returning a Polars `DataFrame`. Accepts any keyword arguments forwarded to `polars.read_parquet`.

### Parameters
- **file_path** (str) - Required - The relative path to the file within the Dataverse repository (e.g., "nodes/drug.parquet").
- ****kwargs - Optional - Additional keyword arguments to be passed to `polars.read_parquet`.

### Returns
- **polars.DataFrame** - A Polars DataFrame containing the data from the specified Parquet file.

### Request Example
```python
import optimuskg
import polars as pl

# Load the drug node table
drugs = optimuskg.load_parquet("nodes/drug.parquet")
print(drugs.schema)
# Schema({'id': String, 'label': String, 'properties': Struct({...})})

# Unnest the properties struct to access individual fields
drugs_flat = drugs.unnest("properties")
print(drugs_flat.select(["id", "name", "is_approved", "year_of_first_approval"]).head(5))

# Load a specific edge file
drug_gene = optimuskg.load_parquet("edges/drug_gene.parquet")
print(drug_gene.schema)
# Schema({'from': String, 'to': String, 'label': String,
#         'relation': String, 'undirected': Boolean, 'properties': Struct({...})})

# Filter for INHIBITOR relations
inhibitors = drug_gene.unnest("properties").filter(
    pl.col("relation") == "INHIBITOR"
)
print(f"Found {len(inhibitors)} drug→gene inhibitor edges")
```
```

--------------------------------

### Load Graph as NetworkX MultiDiGraph

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Constructs and returns a NetworkX MultiDiGraph from the graph data. Properties are loaded onto attributes. A warning is issued if loading the full graph due to high memory requirements; use `lcc=True` for a smaller variant.

```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)
```

--------------------------------

### set_server

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Override the Dataverse server URL for the current process.

```APIDOC
## set_server

### Description
Override the Dataverse server URL for the current process.

### Method
`set_server(url: str) -> None`

### Parameters
#### Path Parameters
- **url** (str) - Required - The new Dataverse server URL.
```

--------------------------------

### Print Relation Types

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Demonstrates how to print different relation types available in the Relation enum.

```python
print(Relation.INHIBITOR)
# 'INHIBITOR'
print(Relation.INDICATION)
# 'INDICATION'
print(Relation.ADVERSE_DRUG_REACTION)
# 'ADVERSE_DRUG_REACTION'
```

--------------------------------

### Sync Catalog for a Specific Layer

Source: https://github.com/mims-harvard/optimuskg/blob/main/CONTRIBUTING.md

Targets a specific layer (e.g., 'bronze') for catalog synchronization.

```console
# Target a specific layer
$ uv run cli sync-catalog --layer bronze
```

--------------------------------

### get_file

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

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.

```APIDOC
## get_file

### Description
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.

### Method
`get_file(relative_path: str, *, force: bool = False) -> Path`

### Parameters
#### Path Parameters
- **relative_path** (str) - Required - The relative path to the parquet file.
- **force** (bool) - Optional - If True, force download even if the file exists. Defaults to False.

### Response
- **Path** - The local path to the parquet file.
```

--------------------------------

### Load Parquet File as DataFrame

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Downloads a Parquet file if necessary and reads it into a Polars DataFrame. Supports additional keyword arguments for `pl.read_parquet`.

```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)
```

--------------------------------

### Run Specific Kedro Pipeline or Node

Source: https://github.com/mims-harvard/optimuskg/blob/main/CLAUDE.md

Executes a specific Kedro pipeline or a single node within the pipeline.

```bash
uv run kedro run --pipeline bronze
```

```bash
uv run kedro run --nodes <node_name>
```

--------------------------------

### Load graph as NetworkX MultiDiGraph

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Loads the graph into a NetworkX MultiDiGraph. Set `parse_properties=False` for faster loading and lower memory usage if property parsing is not needed.

```python
import optimuskg
import networkx as nx

# Load the LCC as a MultiDiGraph (recommended — full graph requires ~several GB RAM)
G = optimuskg.load_networkx(lcc=True)
print(f"Nodes: {G.number_of_nodes()}, Edges: {G.number_of_edges()}")

# Node attributes: label + all properties splatted
gene_id = "ENSG00000163513"
if gene_id in G.nodes:
    attrs = G.nodes[gene_id]
    print(f"Label: {attrs['label']}")   # 'GEN'
    print(f"Name:  {attrs.get('name')}")  # 'TGFBR2'

# Edge attributes: label, relation, undirected, + splatted properties
for u, v, data in G.edges("ENSG00000163513", data=True):
    print(f"  {u} --[{data['relation']}]--> {v}")

# Standard NetworkX algorithms work directly
neighbors = list(G.neighbors("ENSG00000163513"))
degree_centrality = nx.degree_centrality(G)
top5 = sorted(degree_centrality.items(), key=lambda x: x[1], reverse=True)[:5]

# Load raw JSON strings without parsing (faster, lower memory)
G_raw = optimuskg.load_networkx(lcc=True, parse_properties=False)
print(G_raw.nodes["ENSG00000163513"]["properties"])
```

--------------------------------

### Load as NetworkX Graph

Source: https://github.com/mims-harvard/optimuskg/blob/main/packages/optimuskg/README.md

Load the graph data as a NetworkX MultiDiGraph. JSON properties are automatically parsed.

```python
import optimuskg

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

--------------------------------

### Set Custom Cache Directory

Source: https://github.com/mims-harvard/optimuskg/blob/main/packages/optimuskg/README.md

Programmatically set a custom directory for caching downloaded files. This overrides the default location and the environment variable.

```python
import optimuskg

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

--------------------------------

### Load Parquet Files as DataFrames

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Load Parquet files into Polars DataFrames. Extra keyword arguments are forwarded to polars.read_parquet.

```python
drugs = optimuskg.load_parquet("nodes/drug.parquet")
```

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

--------------------------------

### Load Graph as NetworkX MultiDiGraph

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Build a NetworkX MultiDiGraph from the loaded graph data. Supports filtering by node label or relation type.

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

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

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

--------------------------------

### load_networkx

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Return the graph as a `nx.MultiDiGraph` with properties loaded onto attrs.

```APIDOC
## load_networkx

### Description
Return the graph as a `nx.MultiDiGraph` with properties loaded onto attrs.

### Method
`load_networkx(*, lcc: bool = False, force: bool = False, parse_properties: bool = True) -> nx.MultiDiGraph`

### Parameters
#### Path Parameters
- **lcc** (bool) - Optional - If True, load the Largest Connected Component (LCC) of the graph. Defaults to False.
- **force** (bool) - Optional - If True, force download of data even if it exists. Defaults to False.
- **parse_properties** (bool) - Optional - If True, parse properties into node/edge attributes. Defaults to True.

### Response
- **nx.MultiDiGraph** - A NetworkX MultiDiGraph object representing the graph.
```

--------------------------------

### optimuskg.set_cache_dir / get_cache_dir

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Controls where downloaded Parquet files are stored on disk. The default is platformdirs.user_cache_dir("optimuskg"). Can also be set via the $OPTIMUSKG_CACHE_DIR environment variable.

```APIDOC
## optimuskg.set_cache_dir / get_cache_dir

### Description
Configures and retrieves the local cache directory for downloaded Parquet files.

### Methods
- **get_cache_dir()**: Returns the current cache directory.
- **set_cache_dir(path: str)**: Sets the cache directory to the specified path.

### Environment Variable
- **OPTIMUSKG_CACHE_DIR**: Can be set to specify the cache directory.

### Request Example
```python
import optimuskg

print(optimuskg.get_cache_dir())
optimuskg.set_cache_dir("/data/optimuskg-cache")
print(optimuskg.get_cache_dir())
```
```

--------------------------------

### Rerun Node and Sync Catalog

Source: https://github.com/mims-harvard/optimuskg/blob/main/CONTRIBUTING.md

Reruns a specific Kedro node and then synchronizes the catalog entries for the updated dataset.

```console
$ uv run kedro run --from-nodes=<node_name>
$ uv run cli sync-catalog --dataset <catalog_id>
```

--------------------------------

### Load and Filter Silver Phenotype-Gene Edges in Kedro Jupyter Session

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Loads 'silver.edges.phenotype_gene' dataset from the Kedro catalog, filters by phenotype ID and non-null disease specificity index, and displays the head of the filtered data. Assumes a Kedro Jupyter session.

```python
# Load silver phenotype-gene edges
edges = catalog.load("silver.edges.phenotype_gene").unnest("properties")
edges_filtered = edges.filter(
    pl.col("from").str.contains("HP_0000023") &
    pl.col("disease_specificity_index").is_not_null()
)
print(edges_filtered.head())
```

--------------------------------

### Load and Filter Phenotype Data

Source: https://github.com/mims-harvard/optimuskg/blob/main/notebooks/quickstart.ipynb

Loads phenotype data from 'silver.nodes.phenotype', filters by phenotype ID, and writes the first result to a JSON file. Ensure the 'polars' library is imported.

```python
import polars as pl
catalog.load("silver.nodes.phenotype").unnest("properties").filter(
    (pl.col("id").str.contains("HP_0000023"))
).head().write_json("phenotype.json")
```

--------------------------------

### Load a Parquet file as a Polars DataFrame

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

The `load_parquet` function downloads a specified Parquet file if it's not cached and then reads it into a Polars DataFrame. It forwards any additional keyword arguments to `polars.read_parquet` for advanced reading options.

```python
import optimuskg
import polars as pl

# Load the drug node table
drugs = optimuskg.load_parquet("nodes/drug.parquet")
print(drugs.schema)
# Schema({'id': String, 'label': String, 'properties': Struct({...})})

# Unnest the properties struct to access individual fields
drugs_flat = drugs.unnest("properties")
print(drugs_flat.select(["id", "name", "is_approved", "year_of_first_approval"]).head(5))

# Load a specific edge file
drug_gene = optimuskg.load_parquet("edges/drug_gene.parquet")
print(drug_gene.schema)
# Schema({'from': String, 'to': String, 'label': String,
#         'relation': String, 'undirected': Boolean, 'properties': Struct({...})})

# Filter for INHIBITOR relations
inhibitors = drug_gene.unnest("properties").filter(
    pl.col("relation") == "INHIBITOR"
)
print(f"Found {len(inhibitors)} drug→gene inhibitor edges")
```

--------------------------------

### Checksum Validation with ChecksumHooks

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Configure datasets with metadata checksums for integrity validation. ChecksumHooks automatically verify file integrity before loading `landing.*`, `bronze.*`, and `silver.*` datasets.

```yaml
# conf/base/catalog/bronze/opentargets.yaml
bronze.opentargets.disease:
  type: optimuskg.datasets.polars.ParquetDataset
  filepath: data/bronze/opentargets/disease.parquet
  metadata:
    checksum: "a3f9c1b2e4d8f6a0"   # blake2b hex digest
    origin:
      provider: http
      url: "https://ftp.ebi.ac.uk/pub/databases/opentargets/..."
```

--------------------------------

### Sync Catalog for a Specific Dataset

Source: https://github.com/mims-harvard/optimuskg/blob/main/CONTRIBUTING.md

Targets a specific dataset within a layer (e.g., 'bronze.opentargets.disease') for catalog synchronization.

```console
# Target a specific dataset
$ uv run cli sync-catalog --dataset bronze.opentargets.disease
```

--------------------------------

### Load Parquet File

Source: https://github.com/mims-harvard/optimuskg/blob/main/packages/optimuskg/README.md

Load a single Parquet file into a Polars DataFrame.

```python
import optimuskg

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

--------------------------------

### Pipeline Utility Functions

Source: https://context7.com/mims-harvard/optimuskg/llms.txt

Provides utility functions for parsing Polars types from YAML strings, normalizing column names to snake_case, and calculating blake2b checksums for files or directories.

```python
from optimuskg.utils import parse_polars_type, to_snake_case, calculate_checksum
from pathlib import Path

# Parse YAML schema type strings to Polars types
print(parse_polars_type("String"))           # String
print(parse_polars_type("List(String)"))     # List(String)
print(parse_polars_type("pl.Int64"))         # Int64
print(parse_polars_type("Struct({name: String, score: Float64})"))
# Struct({'name': String, 'score': Float64})

# Normalize column names to snake_case
print(to_snake_case("HelloWorld"))     # 'hello_world'
print(to_snake_case("camelCase"))      # 'camel_case'
print(to_snake_case("hello-world"))    # 'hello_world'
print(to_snake_case("hello__world"))   # 'hello_world'

# Compute blake2b checksum for a file or directory
checksum = calculate_checksum(Path("data/bronze/opentargets/disease.parquet"))
print(checksum)  # "a3f9c1b2..."

checksum_dir = calculate_checksum(Path("data/bronze/opentargets/"))
print(checksum_dir)  # "d7e1f4a8..." (includes all files + relative paths in hash)

```

--------------------------------

### Load Graph as Polars DataFrames

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/index.mdx

Load the entire graph or its largest connected component (LCC) as Polars DataFrames for nodes and edges.

```python
nodes, edges = optimuskg.load_graph()          # full graph
```

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

--------------------------------

### Set Dataverse Server URL

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Overrides the Dataverse server URL for the current process. The provided URL will have trailing slashes removed.

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

--------------------------------

### Set Cache Directory

Source: https://github.com/mims-harvard/optimuskg/blob/main/docs/content/docs/optimuskg-client/reference.mdx

Overrides the local cache directory for the current process. Accepts string paths or path-like objects.

```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)
```