ksk-1729/optimuskg-neo4j-graph

OptimusKG → Neo4j Graph

A property-graph conversion of [OptimusKG](https://github.com/mims-harvard/OptimusKG), ready for direct import into Neo4j or general tabular/graph use, published in two formats (see "Files" below).

OptimusKG is a modern biomedical knowledge graph developed by the Zitnik Lab, Harvard Medical School (Department of Biomedical Informatics). It integrates 65 heterogeneous source resources — spanning molecular, anatomical, clinical, and environmental domains — grounded in 18 ontologies, built with the BioCypher framework. The upstream data is distributed via Harvard Dataverse (DOI: 10.7910/DVN/IYNGEV).

This repository does not add or change any data — it's a straight structural conversion of the same 190,531 nodes / 21,813,816 edges into formats more convenient for graph tooling and tabular analysis than the upstream flat Parquet + JSON-string-properties representation.

Files

flat/ — full-fidelity original shape

Two files, mirroring OptimusKG's own upstream format exactly:

label on nodes is one of 10 entity-type codes (DRG drug, GEN gene, DIS disease, PHE phenotype, PWY pathway, BPO biological process ontology, CCO cellular component ontology, MFN molecular function, ANA anatomy, EXP exposure). relation on edges is one of 36 relationship types (TARGET, INDICATION, INTERACTS_WITH, ASSOCIATED_WITH, PARENT, IS_A, etc. — see neo4j_shaped/ file names below for the full list). properties holds every type-specific field as a JSON object; schemas differ substantially between labels/relations (a drug's properties look nothing like a gene's), which is exactly why the JSON-string form is what OptimusKG ships upstream.

neo4j_shaped/ — flattened per-type, ready for Neo4j bulk import

46 Parquet files (10 node-label files + 36 edge-relation files), one per distinct label/relation, each with properties already decoded and unnested into real typed columns (schema varies per file, since each label/relation's properties are structurally different). Column names are plain (id, label, start_id, end_id, type, plus whatever property fields that label/relation has) rather than Neo4j's raw id:ID/:START_ID import syntax — see "Reimporting into Neo4j" below for how to convert back.

Node files (nodes_<LABEL>.parquet): ANA 13,120 · BPO 25,754 · CCO 4,052 · DIS 36,345 · DRG 16,766 · EXP 881 · GEN 61,306 · MFN 10,161 · PHE 19,341 · PWY 2,805.

Edge files (edges_<RELATION>.parquet): ASSOCIATED_WITH 10,531,730 · EXPRESSION_PRESENT 6,616,463 · EXPRESSION_ABSENT 2,171,492 · SYNERGISTIC_INTERACTION 1,341,086 · INTERACTS_WITH 734,862 · PARENT 95,711 · IS_A 61,720 · INDICATION 58,690 · PHENOTYPE_PRESENT 157,144 · CONTRAINDICATION 19,997 · TARGET 9,465 · OFF_LABEL_USE 1,262 · TRANSPORTER 2,764 · LINKED_TO 2,391 · ENZYME 4,857 · CARRIER 711 · ADVERSE_DRUG_REACTION 574 · AGONIST 499 · ANTAGONIST 475 · POSITIVE_ALLOSTERIC_MODULATOR 564 · POSITIVE_MODULATOR 108 · INHIBITOR 845 · BLOCKER 241 · NEGATIVE_ALLOSTERIC_MODULATOR 17 · NEGATIVE_MODULATOR 3 · PARTIAL_AGONIST 35 · MODULATOR 35 · ALLOSTERIC_ANTAGONIST 16 · INVERSE_AGONIST 6 · ACTIVATOR 7 · OPENER 10 · RELEASING_AGENT 6 · STABILISER 21 · BINDING_AGENT 4 · DEGRADER 2 · SUBSTRATE 3.

Imported into Neo4j, this totals: 190,531 nodes, 21,813,816 relationships, 111,512,054 properties — exact match against the source counts, zero rows skipped (--skip-bad-relationships / --skip-duplicate-nodes triggered on nothing).

Reimporting into Neo4j

The neo4j_shaped/ files use plain column names for readability; neo4j-admin database import needs its own header convention. Convert back with DuckDB (or rename columns with any Parquet-aware tool):

-- example for one node file; repeat per file with the right rename
COPY (SELECT id AS "id:ID", label AS ":LABEL", * EXCLUDE (id, label)
      FROM 'nodes_DRG.parquet')
  TO 'nodes_DRG.csv' (HEADER, DELIMITER ',');
-- for edge files: start_id AS ":START_ID", end_id AS ":END_ID", type AS ":TYPE"

then:

neo4j-admin database import full \
  --nodes=nodes_ANA.csv --nodes=nodes_BPO.csv --nodes=nodes_CCO.csv \
  --nodes=nodes_DIS.csv --nodes=nodes_DRG.csv --nodes=nodes_EXP.csv \
  --nodes=nodes_GEN.csv --nodes=nodes_MFN.csv --nodes=nodes_PHE.csv \
  --nodes=nodes_PWY.csv \
  --relationships=edges_ACTIVATOR.csv --relationships=edges_ADVERSE_DRUG_REACTION.csv \
  ... (one --relationships= flag per edges_*.csv file) \
  --overwrite-destination \
  --skip-bad-relationships=true \
  --skip-duplicate-nodes=true \
  --multiline-fields=true \
  optimuskg-db

`--multiline-fields=true` is required, not optional — some free-text properties (e.g. disease description fields) legitimately contain literal embedded newlines inside a properly quoted CSV field, and the importer rejects those by default without this flag.

Conversion notes

Two real bugs were found and fixed while producing this conversion, worth knowing if you're working with the upstream properties JSON directly: (1) properties schemas are genuinely sparse — different rows of the same label/relation can have different sets of populated keys — so any pipeline that infers a properties schema from a subset of rows rather than the complete set risks silently dropping or misaligning columns; (2) a small number of properties (e.g. common.document-style free-text fields, and some ontology cross-reference lists) are large or irregular enough that naive whole-column JSON decoding can be memory- expensive at 190K–10M+ row scale — batching the decode, not just the write, matters on constrained hardware.

License / attribution

OptimusKG's own code is MIT-licensed. The data is a composite of 65 primary source datasets, each under its own license — some permissive, some restricted to academic/noncommercial use. Per the OptimusKG repository:

Users are responsible for reviewing and complying with the license and terms of use of each primary dataset.

This derived conversion makes no claim to relax, override, or unify those terms — it is a structural reformatting only. Before using this data for anything beyond personal exploration (and especially before any commercial or redistribution use), consult the OptimusKG repository and the Harvard Dataverse listing for the specific licensing terms of the source(s) relevant to your use case.

If you use this data, please cite the original OptimusKG work:

@article{vittor2026optimuskg,
  title={OptimusKG: Unifying biomedical knowledge in a modern multimodal graph},
  author={Vittor, Lucas and Noori, Ayush and Arango, Iñaki and Polonuer, Joaquín and Rodriques, Sam and White, Andrew and Clifton, David A. and Zitnik, Marinka},
  journal={In review},
  year={2026}
}

and the dataset itself:

OptimusKG (2026). Harvard Dataverse. https://doi.org/10.7910/DVN/IYNGEV

This repository is an independent, community-derived Neo4j/Parquet conversion, not an official Zitnik Lab / Harvard release, and is not endorsed by the OptimusKG authors.