HKAI-Sci/qkg-primekg-entities-with-cui

Data Card: qkg-primekg-entities-with-cui

## Summary

qkg-primekg-entities-with-cui.jsonl is the QKG entity table derived from PrimeKG and enriched with UMLS CUI annotations. It provides the entity inventory used by the QKG runtime for entity lookup and UMLS- backed synonym matching.

This artifact is intended to be loaded into MongoDB collection:

• —primeKG.entities

## Paper

This artifact is released with the paper:

• —Yao Wang, Zixu Geng, and Jun Yan. Quantum Knowledge Graph: Modeling Context-Dependent Triplet Validity. arXiv:2604.23972, 2026.

The paper PDF is available at <https://arxiv.org/pdf/2604.23972>.

## Intended Use

This artifact is released for:

• —reproducing the QKG paper runtime
• —loading primeKG.entities for conditionKgTestAgentic.py
• —supporting entity lookup through PrimeKG entity metadata plus UMLS CUI alignment

This artifact is not intended to be treated as a standalone biomedical ontology or a clinically validated mapping resource.

## Provenance

The collection was constructed from the PrimeKG relation graph by:

1. 1.extracting all unique entities from primeKG.relations
2. 2.assigning UMLS CUI values when available
3. 3.exporting the final Mongo collection primeKG.entities to JSONL

In the codebase, the entity construction logic is implemented in:

• —tools/create_primekg_entities.py

The public JSONL export is produced by:

• —tools/export_primekg_entities.py

## Upstream Sources

This artifact depends on:

• —PrimeKG, as the source of the base entity inventory
• —official UMLS data loaded into umls_test.umls_strings_raw_test, used for direct source-code-based CUI mapping
• —an offline prepared entity-to-UMLS mapping file used during entity construction

QKG distributes the final entity artifact used for reproduction, rather than requiring users to rebuild the internal grounding pipeline.

## File Format

The file is JSONL: one JSON object per line.

Each record contains:

• —index: PrimeKG node index
• —id: source-specific entity identifier
• —type: entity type in PrimeKG
• —name: entity name
• —source: source vocabulary or database
• —cui: mapped UMLS CUI, or null
• —cui_score: mapping confidence score, or null
• —cui_method: mapping method, or null

Example:

  {"index": 0, "id": "9796", "type": "gene/protein", "name": "PHYHIP", "source": "NCBI", "cui": "C0019944", "cui_score": 0.0, "cui_method": "source_code"}

## Size and Coverage

Current exported statistics:

• —total entities: 129,375
• —entities with non-null cui: 80,726
• —CUI coverage: 62.4%

Mapping method counts:

• —source_code: 61,556
• —entity_map: 19,170
• —unmapped: 48,649

Top source vocabularies by entity count:

• —GO: 43,987
• —NCBI: 27,671
• —MONDO: 15,813
• —HPO: 15,311
• —UBERON: 14,035
• —DrugBank: 7,957
• —REACTOME: 2,516
• —MONDO_grouped: 1,267
• —CTD: 818

Top entity types by count:

• —biological_process: 28,642
• —gene/protein: 27,671
• —disease: 17,080
• —effect/phenotype: 15,311
• —anatomy: 14,035
• —molecular_function: 11,169
• —drug: 7,957
• —cellular_component: 4,176
• —pathway: 2,516
• —exposure: 818

## How It Is Used in QKG

The public QKG runtime uses this artifact after loading it into:

• —primeKG.entities

It supports:

• —entity lookup by name and source metadata
• —UMLS-backed fallback via cui
• —linking entity search results to PrimeKG relation traversal

## Recommended Loading

JSONL import path:

mongoimport \ --uri "$QKGPRIMEKGMONGO_URI" \ --db primeKG \ --collection entities \ --file /path/to/qkg-primekg-entities-with-cui.jsonl

Mongo dump restore path is also supported when using the corresponding published dump artifact.

## Limitations

• —Not every PrimeKG entity maps to a UMLS CUI.
• —cui coverage is partial and depends on the original grounding pipeline.
• —The artifact is designed for QKG reproduction, not as a canonical biomedical identifier mapping benchmark.
• —Some mappings are derived from source-code alignment, while others come from a prepared offline mapping resource.
• —Downstream behavior may differ if users rebuild entities from raw sources instead of using this published artifact.

## Redistribution and Licensing Notes

Users should separately review the licenses and terms for the upstream resources used in constructing this artifact, especially:

• —PrimeKG
• —UMLS

This artifact is released as a reproduction artifact for the QKG project.

## Citation

If you use this artifact, please cite the QKG paper and acknowledge the upstream PrimeKG and UMLS resources.

  @misc{wang2026quantumknowledgegraph,
    title = {Quantum Knowledge Graph: Modeling Context-Dependent Triplet Validity},
    author = {Wang, Yao and Geng, Zixu and Yan, Jun},
    year = {2026},
    eprint = {2604.23972},
    archivePrefix = {arXiv},
    primaryClass = {cs.CL},
    doi = {10.48550/arXiv.2604.23972},
    url = {https://arxiv.org/abs/2604.23972}
  }