review-hp-diff

name	review-hp-diff
description	Use when asked to review an HPO chemical phenotype diff report (reports/hp_chemical_phenotype_diff.md) generated by the EQ normalisation pipeline. Verifies renames preserve semantics, using OLS synonym lookups.

Review HPO Chemical Phenotype Diff

Review reports/hp_chemical_phenotype_diff.md — the output of the HPO chemical phenotype EQ normalisation pipeline — to verify renames do not change term semantics.

Context

The diff is generated by sh run.sh make hpo_phenotype_pipeline -B. Never run this yourself — always ask the user to run it.

The pipeline:

1. Downloads a normalisation spreadsheet ($(TMPDIR)/normalised_patterns.tsv) mapping HP terms to DOSDP patterns
2. Generates new labels/definitions/EQs from DOSDP patterns
3. Applies SPARQL label replacements (../sparql/update-chemical-labels.ru) — these handle known synonym mappings (e.g. "serotransferrin" → "transferrin", "mucin-16" → "CA-125", ion charge stripping like "calcium(2+)" → "calcium", enzyme "concentration" → "activity")
4. Merges old labels as exact synonyms
5. Diffs old vs new using OAK

Key source files for tracing issues:

• $(TMPDIR)/normalised_patterns.tsv — the input spreadsheet driving the rename
• ../sparql/update-chemical-labels.ru — SPARQL-based label transformations
• $(PATTERNDIR)/dosdp-patterns-hpo/*.yaml — DOSDP pattern templates

Workflow

digraph review_flow {
  "Read diff file" -> "Review Nodes renamed";
  "Review Nodes renamed" -> "Verify chemical names in OLS";
  "Verify chemical names in OLS" -> "Review Text definitions changed";
  "Review Text definitions changed" -> "Review Relationships added/removed";
  "Review Relationships added/removed" -> "Produce report";
}

1. Read the diff file — default path: reports/hp_chemical_phenotype_diff.md
2. Review "Nodes renamed" — primary focus (see classification below)
3. Verify suspect chemical names via OLS — when a chemical entity name changed, use OLS MCP search or searchClasses to confirm the new name is a valid synonym of the old name in CHEBI or the relevant source ontology
4. Review "Text definitions changed" — check for meaning drift, especially:
   • "concentration" → "activity" changes (should only happen for enzymes, per the SPARQL rule)
   • Definitions that lost clinically important qualifiers
   • Typos introduced by the pipeline (e.g. truncated names like "o-decenoylcarnitin" missing final 'e')
5. Review "Relationships added/removed" — check for classification errors
6. Skip "Synonyms added" — these are old labels preserved as exact synonyms, generally safe

Classifying Renames

CRITICAL — Semantic change

The new label refers to a different concept. Examples specific to this pipeline:

• "concentration" → "activity" for a non-enzyme (SPARQL rule misfired)
• Chemical entity changed to a different substance (not just a synonym)
• Qualifier lost that changes what's measured (e.g. "non-ceruloplasmin-bound copper" → "copper")

IMPORTANT — Lost specificity or suspect name

• "serum"/"plasma" → "circulating" (serum/plasma are more specific compartments)
• A well-known clinical term (e.g. "Hyperchloremia") replaced as primary label
• Chemical name looks like a possible typo or truncation (e.g. "o-decenoylcarnitin" — missing final 'e')
• New chemical name not found as synonym in OLS/CHEBI for the old name

MINOR — Lexical rewording

• "blood" → "circulating"
• Ion charge notation added/removed: "calcium(2+)" → "calcium"
• "atom"/"molecular entity" suffix stripped (per SPARQL rules)
• Hyphenation changes: "fatty-acid" → "fatty acid"
• Article dropped: "a carboxylic acid" → "carboxylic acid"

OLS Verification

When a chemical name changes (not just wording), verify via OLS MCP:

1. Search for the old chemical name in CHEBI
2. Search for the new chemical name in CHEBI
3. Confirm both resolve to the same CHEBI class (or that one is a listed synonym of the other)

Only do this for names that look substantively different — skip trivial ion charge or suffix changes.

SPARQL Replacement Awareness

The update-chemical-labels.ru file applies these known replacements. If a rename matches one of these, it is expected and low-risk:

• " atom" / " molecular entity" suffix removal
• " (human)" removal
• Ion charge stripping: "calcium(2+)" → "calcium", "magnesium(2+)" → "magnesium", etc.
• Protein name mappings: "alpha-2-HS-glycoprotein" → "fetuin-A", "serotransferrin" → "transferrin", etc.
• Enzyme concentration → activity rule (verify the target is actually an enzyme)

Flag if a rename does NOT match any known SPARQL rule and also doesn't come from a DOSDP pattern change — this may indicate an issue in the input spreadsheet.

CHEBI Role Terms — Unsatisfiability Watch-out

The abnormalLevelOfChemicalEntityInBlood (and sibling) DOSDP patterns model the CHEBI filler as the material bearer of an amount: inheres_in some (<FILLER> and part_of some <location>). This is only valid when the filler is a material chemical entity (under CHEBI:24431 'chemical entity'). Some CHEBI classes are roles (under CHEBI:50906 'role' / 'biological role'), not material entities — e.g. coenzyme (CHEBI:23354), metabolite (CHEBI:25212), vitamin, cofactor, nutrient. Feeding a role into this pattern produces an unsatisfiable class (a role cannot bear a concentration), which surfaces at reasoning/CI time (make explain_unsat, ROBOT reason error "N unsatisfiable classes"), not in the OAK diff.

Watch for it: if a renamed/re-defined term's chemical filler is a role word (coenzyme, metabolite, vitamin, cofactor, hormone-as-role, etc.), flag it. Beware knock-on unsats — any subclass of an unsatisfiable class is also unsatisfiable (e.g. HP:0034617 SAM was unsat only because it is SubClassOf HP:0034616 coenzyme).

Correct modelling (per issue #4952): replace the direct filler with 'chemical entity' and 'has role' some <role>, i.e. the bearer is a chemical entity that has the role, located in the compartment. Example — HP:0034616 coenzyme fixed to: inheres_in some ('chemical entity' (CHEBI:24431) and 'has role' (RO:0000087) some coenzyme (CHEBI:23354) and part_of some blood). Until the DOSDP patterns emit this form for role fillers, such terms need a hand-edited EQ in hp-edit.owl (a temporary hack) — so re-running the normalisation pipeline can silently reintroduce the broken direct form. After any pipeline run touching role-filler terms, run a consistency/explain_unsat check, not just the OAK diff review.

Output Format

## HPO Chemical Phenotype Diff Review

### CRITICAL Issues (semantic changes)
| ID | Old Label | New Label | Issue |
|----|-----------|-----------|-------|
(list or "None found")

### IMPORTANT Issues (lost specificity / suspect names)
| ID | Old Label | New Label | Issue |
|----|-----------|-----------|-------|
(list or "None found")

### Definition Issues
| Term | Issue |
|------|-------|
(list or "None found")

### Relationship Issues
| Subject | Change | Issue |
|---------|--------|-------|
(list or "None found")

### MINOR Notes
- Brief summary of acceptable changes

### Summary
- X renames reviewed, N critical, N important, N minor
- Y definition changes reviewed
- Z relationship changes reviewed
- Recommendation: [proceed / fix critical issues first / discuss with curator]

Tracing Issues to Source

When flagging an issue, indicate the likely source:

• SPARQL rule — the replacement in update-chemical-labels.ru is incorrect or overly broad
• Input spreadsheet — the pattern assignment in normalised_patterns.tsv mapped to the wrong pattern or wrong filler
• DOSDP pattern — the pattern template itself produces incorrect labels
• Pipeline bug — e.g. truncated names, encoding issues