Schema Expansion: PTMs, Variants & Data Model Discussion¶
Context: Preparation for PTM/variant discussion. Covers current schema state, Staffan's proposed expansion, and open questions about modeling protein forms that deviate from UniProt.
See also: Data Model for the full production schema reference.
Current State (in production / merged to dev)¶
The schema defines 11 entity types and 13 relationship types for LLM extraction. Entities are validated against it during ingestion.
Core Relationships (13 types)¶
ASSOCIATED_WITH, BIOMARKER_FOR, INTERACTS_WITH, TREATS, TARGETS, CAUSES, PARTICIPATES_IN, EXPRESSED_IN, UPREGULATED_IN, DOWNREGULATED_IN, HAS_PTM, PART_OF_PANEL, MANUFACTURED_BY
Extraction Rules (enforced at ingestion)¶
- Only extract SPECIFIC named entities — never generic terms
- Proteins must be real protein/gene names (UniProt naming patterns)
- Diseases must be specific conditions, not symptoms
- Every relationship MUST have a
source_sentence(verbatim from text) - If unsure Protein vs Gene, default to Protein
- Prefer specific relationship types over ASSOCIATED_WITH
Infrastructure¶
Side-by-Side Comparison¶
| Metric | Neo4j Prod | Neptune Beta | Delta |
|---|---|---|---|
| Total Nodes | 575K | 485K | — |
| Total Relationships | 820K | 1.19M | +45% |
| Embeddings | 264K | 216K (Aurora) | — |
| ASSOCIATED_WITH | 301K | 353K | +17% |
| BIOMARKER_FOR | — | 134K | |
| CAUSES | 4.7K | 35K | +7.5× |
| TREATS | 9.3K | 19K | +2× |
| INHIBITS | — | 4.9K | |
| REGULATES | — | 4.7K | |
| IS_A (hierarchy) | 30K | 142K | +4.7× |
| Protein | 60K | 28K | Neo4j has more (consolidated) |
| Disease | 55K | 119K | Neptune has MONDO full ontology |
| Gene | 146 | 313 | +2× |
| Phenotype | 443 | 886 | +2× |
| Biomarker | — | 477 | |
| Therapy | — | 349 |
Takeaway: Neptune beta has significantly richer biological relationships (BIOMARKER_FOR, CAUSES, TREATS, INHIBITS, REGULATES) because the bulk extraction targeted these types explicitly. Neo4j prod has more consolidated proteins (UniProt-mapped, deduplicated). The goal is to combine both: Neptune's relationship density + Neo4j's entity quality.
| Backend | Nodes | Relationships | Embeddings |
|---|---|---|---|
Neo4j (prod, psx) |
575K | 820K | 264K |
| Neptune (beta) | 485K | 1.19M | — |
| Aurora pgvector (beta) | — | — | 216K |
Neo4j Prod Entity Breakdown¶
| Label | Count | Notes |
|---|---|---|
| Chunk | 156,422 | Text segments for retrieval |
| ProcessingMarker | 120,214 | Pipeline tracking |
| Abstract | 118,041 | PubMed/bioRxiv papers |
| Protein | 59,614 | 57,280 + 2,334 dual-labeled |
| Synonym | 48,338 | Alternative names |
| Disease | 55,189 | 28,742 Reference + 26,447 Disease |
| Entity (untyped) | 8,809 | Extracted but not classified |
| OntologyTerm | 7,058 | MONDO hierarchy |
| Phenotype | 443 | Observable traits |
| Gene | 146 | Genomic context |
| CellType | 81 | From HPA enrichment |
| SubcellularLocation | 49 | From UniProt |
| Panel | 30 | Olink panels |
| Virus | 25 | Pathogen entities |
Neptune Beta Entity Breakdown¶
| Label | Count | Notes |
|---|---|---|
| Disease | 118,858 | MONDO ontology + extracted |
| Entity (untyped) | 115,202 | From bulk extraction |
| Chunk | 102,798 | Text segments |
| Synonym | 95,306 | Alternative names |
| Protein | 27,529 | 24,968 + 2,561 dual-labeled |
| OntologyTerm | 10,718 | MONDO hierarchy |
| Author | 1,307 | Publication authors |
| Person | 1,093 | Named persons |
| Phenotype | 886 | Observable traits |
| Biomarker | 477 | Explicit biomarker mentions |
| Therapy | 349 | Treatment entities |
| GeneOntologyTerm | 342 | GO annotations |
| Gene | 313 | Genomic context |
Neptune Beta Relationship Breakdown¶
| Relationship | Count | Category |
|---|---|---|
| ASSOCIATED_WITH | 353,459 | Core biology |
| IS_A | 142,089 | Disease hierarchy |
| HAS_RELATED_SYNONYM | 140,396 | Ontology |
| BIOMARKER_FOR | 133,875 | Protein → Disease |
| MENTIONS | 88,283 | Chunk → Entity |
| MENTIONS_DISEASE | 82,200 | Chunk → Disease |
| CAUSES | 35,322 | Gene/Protein → Disease |
| TREATS | 18,608 | Drug → Disease |
| RELATED_TO | 17,131 | Generic association |
| HAS_MATERIAL_BASIS_IN_GERMLINE_MUTATION_IN | 11,133 | Genetic basis |
| HAS_CHARACTERISTIC | 8,000 | Disease features |
| IN_TAXON | 5,985 | Species annotation |
| INHIBITS | 4,862 | Drug/Protein → Protein |
| REGULATES | 4,666 | Regulatory relationships |
Neo4j Prod Relationship Breakdown¶
| Relationship | Count | Category |
|---|---|---|
| ASSOCIATED_WITH | 301,252 | Core biology |
| HAS_CHUNK | 151,760 | Document structure |
| PROCESSED | 114,876 | Pipeline tracking |
| MENTIONS | 71,235 | Chunk → Entity |
| HAS_RELATED_SYNONYM | 34,826 | Ontology |
| BELONGS_TO | 33,931 | Community membership |
| IS_A | 30,169 | Disease hierarchy |
| MENTIONS_DISEASE | 25,610 | Chunk → Disease |
| RELATED_TO | 10,462 | Generic association |
| FROM_CHUNK | 9,513 | Provenance |
| TREATS | 9,299 | Drug → Disease |
| CAUSES | 4,712 | Gene/Protein → Disease |
| SECRETES | 2,607 | Cell → Protein |
| IN_TAXON | 1,997 | Species annotation |
Key insight: Neptune beta has significantly more biological relationships than Neo4j prod — 134K BIOMARKER_FOR, 35K CAUSES, 19K TREATS, 5K INHIBITS, 5K REGULATES — because the bulk extraction targeted these relationship types explicitly. The expanded schema will further increase coverage of PTM, complex, and isoform relationships.
Proposed Expansion (Staffan's branch — ready to merge)¶
Staffan's comprehensive schema expands to 26 entity types and 62 relationship types.
New Entity Types¶
| Entity | Purpose | Status |
|---|---|---|
| ProteinComplex | Multi-subunit assemblies (hemoglobin, proteasome) | Ready |
| ProteinIsoform | Splice variants (VEGF-A165, CD44v6) | Ready |
| Metabolite | Small molecules (glucose, ATP, cholesterol) | Ready |
| Phenotype | Observable traits (insulin resistance, hypertension) | Ready |
| Product | Olink panels (Explore HT, Target 96) | Ready |
| Organization | Companies + institutions | Ready |
| Document/Abstract/Chunk | Provenance graph | Already exists |
| Mention/CandidateEntity/Provisional* | Staging pipeline | Pipeline internal |
| Synonym | Ontology aliases | Already exists |
| Community | Graph analysis clusters | Already exists |
PTM Enzyme-Substrate Relationships (11 new types)¶
| Relationship | Description | Example |
|---|---|---|
PHOSPHORYLATES |
Kinase → substrate | CDK2 PHOSPHORYLATES RB1 |
DEPHOSPHORYLATES |
Phosphatase → substrate | PP2A DEPHOSPHORYLATES AKT |
UBIQUITINATES |
E3 ligase → substrate | MDM2 UBIQUITINATES TP53 |
DEUBIQUITINATES |
DUB → substrate | USP7 DEUBIQUITINATES TP53 |
ACETYLATES |
HAT → substrate | p300 ACETYLATES Histone H3 |
DEACETYLATES |
HDAC → substrate | HDAC1 DEACETYLATES Histone H3 |
METHYLATES |
Methyltransferase → substrate | EZH2 METHYLATES Histone H3 |
DEMETHYLATES |
Demethylase → substrate | KDM6A DEMETHYLATES H3K27 |
SUMOYLATES |
SUMO ligase → substrate | UBC9 SUMOYLATES RanGAP1 |
GLYCOSYLATES |
Glycosyltransferase → substrate | OGT GLYCOSYLATES TP53 |
CLEAVES |
Protease → substrate | Caspase-3 CLEAVES PARP |
Properties on PTM relationships:
- site: residue and position (e.g., "Ser473", "Lys48")
- modification_type: phosphorylation, ubiquitination, etc.
- functional_effect: activation, degradation, localization change
- confidence, pmids
Protein Complex Model¶
graph TD
P1[Protein: α-subunit] -->|PART_OF_COMPLEX| C[ProteinComplex: Hemoglobin]
P2[Protein: β-subunit] -->|PART_OF_COMPLEX| C
P1 -->|FORMS_COMPLEX_WITH| P2
C -->|ASSOCIATED_WITH| D[Disease: Sickle Cell]Isoform Model¶
graph TD
G[Gene: VEGFA] -->|ENCODES| P[Protein: VEGF-A canonical]
G -->|ENCODES| I1[ProteinIsoform: VEGF-A165]
G -->|ENCODES| I2[ProteinIsoform: VEGF-A121]
P -->|HAS_ISOFORM| I1
P -->|HAS_ISOFORM| I2
P -->|CANONICAL_FORM_OF| I1Olink relevance: Olink antibodies may bind specific isoforms. The panel target is the canonical protein, but the actual measured species could be an isoform.
Additional Relationship Categories¶
| Category | Types | Count |
|---|---|---|
| Regulation | UPREGULATES, DOWNREGULATES, REGULATES, ACTIVATES, INHIBITS, BINDS | 6 |
| Complex/isoform | PART_OF_COMPLEX, FORMS_COMPLEX_WITH, HOMODIMERIZES, HAS_ISOFORM, CANONICAL_FORM_OF, ENCODES | 6 |
| Document/provenance | HAS_ABSTRACT, HAS_CHUNK, FROM_DOCUMENT, MENTIONS, CONTAINS, FROM_CHUNK | 12 |
| Cross-species | ORTHOLOG_OF, PARALOG_OF, HOMOLOG_OF, ANIMAL_MODEL | 4 |
| Ontology | IS_A, HAS_RELATED_SYNONYM, HAS_NARROW_SYNONYM, HAS_BROAD_SYNONYM | 4 |
| Product/org | CONTAINS_TARGET, SOLD_BY, COMPETES_WITH, CITED_IN, DESCRIBES | 5 |
How PTMs Flow Through the System¶
Paper text → LLM extraction → PTM node + enzyme relationship
↓
Entity resolution
↓
Match protein to UniProt ID
Match PTM site to UniProt feature
↓
If site NOT in UniProt → flag as novel/variant
Discussion: PTMs and Variants Deviating from UniProt¶
Key question: How do we model protein forms that don't map cleanly to a single UniProt entry?
The UniProt Gap¶
| Scenario | UniProt coverage | Our model needs |
|---|---|---|
| Phosphorylated TP53 at Ser15 | ✅ Annotated as feature | Protein → HAS_PTM → PTM |
| Truncated protein (proteolytic) | ⚠️ Sometimes annotated | Protein → CLEAVES → Protein |
| Splice isoform (VEGF-A165 vs VEGF-A121) | ✅ UniProt isoform IDs | Protein → HAS_ISOFORM → ProteinIsoform |
| Disease-specific mutant (BRAF V600E) | ❌ Not a UniProt entry | Gap — needs Variant node? |
| Protein complex (hemoglobin) | ❌ No single UniProt ID | ProteinComplex with PART_OF_COMPLEX |
| Glycoform (different glycosylation patterns) | ⚠️ Partial | PTM node with glycosylation type |
| Citrullinated protein (autoimmune) | ❌ Rarely annotated | PTM node — but which UniProt ID? |
Proposed: Variant Node¶
- name: Variant
description: "A specific sequence variant (mutation, SNP) of a protein or gene"
identifiers: [variant_id, hgvs_notation, dbsnp_id, clinvar_id]
examples: ["BRAF V600E", "TP53 R175H", "EGFR T790M", "rs1234567"]
anti_examples: ["variant", "mutation", "SNP", "polymorphism"]
Relationships needed:
- HAS_VARIANT: Protein/Gene → Variant
- VARIANT_ASSOCIATED_WITH: Variant → Disease
- GAIN_OF_FUNCTION / LOSS_OF_FUNCTION: Variant → Phenotype
- DRUG_RESISTANT_VARIANT: Variant → Drug (resistance)
Proposed: Proteoform Node¶
A proteoform = specific molecular form of a protein (sequence + all PTMs + processing state). This is what mass spec actually measures.
- name: Proteoform
description: "A specific molecular form of a protein including all modifications"
identifiers: [proteoform_id, proforma_notation]
examples: ["TP53[Ser15-phospho,Lys382-acetyl]", "Histone H3[K4me3,K27ac]"]
Uses the ProForma standard (HUPO-PSI) for notation.
What Olink Measures vs What Exists¶
| What Olink measures | What the KG models | Gap |
|---|---|---|
| NPX signal for "IL-6" | Protein node (UniProt P05231) | None |
| NPX signal for "TNF-alpha" | Protein node (UniProt P01375) | Soluble vs membrane-bound? |
| NPX for phospho-tau | PTM node? Proteoform? | Need proteoform model |
| NPX for a protein complex | Complex node? Subunit? | Antibody epitope matters |
| NPX for a cleaved form | Protein + CLEAVES relationship | Which fragment? |
Proposed: Olink Measurement Model¶
Olink Panel Target (e.g., "IL-6")
↓
Protein node (UniProt P05231)
↓ PART_OF_PANEL
Product node (Olink Explore HT)
↓
Antibody specificity annotation (future)
- binds_epitope: "aa 45-60"
- detects_isoforms: ["canonical", "isoform 2"]
- detects_ptm_state: "any" | "phospho-only"
Entities NOT in any schema yet (discussion topics)¶
| Entity | Purpose | Complexity |
|---|---|---|
| Variant | BRAF V600E, SNPs, ClinVar entries | High — needs HGVS notation, allele freq |
| Proteoform | Specific modified form measured | High — ProForma standard |
| Antibody | What Olink actually uses to measure | Medium — links panel to epitope |
| ClinicalTrial | Drug-disease evidence | Low — from ClinicalTrials.gov |
| Cohort/Study | Population context | Medium — links findings to populations |
Migration Path¶
- Now: Production schema (11 entities, 13 rels) — working, validated
- Next: Merge Staffan's expansion (26 entities, 62 rels) — update extraction prompt
- Future: Add Variant/Proteoform nodes after discussion alignment
- Future: Re-run extraction on existing corpus with expanded schema