docs: curation report for the has_part-to-CL definition-mining scan

[mellybelly]

Report for #3769.

Documentation only — this PR changes no ontology files. Nothing under src/ is touched, so no axioms are added, removed or altered by merging it.

What this adds

File	Change
docs/reports/has_part_to_cl_scan_2026-09.md	new, 265 lines
mkdocs.yaml	+2 lines, a nav entry under "Uberon Internal Docs" → "Curation reports"

Why

A scan of all 15,621 non-obsolete terms in uberon-edit.obo turned up 113 terms whose textual definition asserts cellular composition but which carry no corresponding has_part axiom to a CL class. Triaging those against the anti-patterns in #2963 took a fair amount of case-by-case reasoning, and most of that reasoning is about candidates that should not be added. That is the part worth writing down: without it, the next person to run a similar scan re-derives the same ~80 rejections from scratch.

What the report contains

• Method, with enough detail to reproduce the scan using only a robot jar, plus the input snapshot it was run against (uberon-edit.obo at f060b3e, cl-base.owl release 2025-07-30).
• 33 proposed axioms, grouped by organ system, each with a PMID verified against Europe PMC, and a citation table for all 18 references.
• The ~80 rejected candidates, with the reason for each: broad structure paired with a specific cell type; matches that name a cell part rather than a whole cell (axon tracts, dendritic fields, synaptic structures); structures that surround rather than contain the cell; subjects already covered by composed_primarily_of or by a superclass; and the deliberate overlaps ... {notes="soma"} modelling on outer nuclear layer of retina, which is the right treatment for a layer holding somata rather than whole cells.
• 10 deferred candidates, each with the specific open question — e.g. glomerular epithelium also subsumes the podocyte-free parietal epithelium; there is no CL class for a spiny stellate cell or a hilar mossy cell; Paneth cells are absent in several mammals, so a taxon GCI may be preferable to a plain assertion.
• Why the UBERON→UBERON variant is not proposed: 788 subjects / 1,359 pairs, but the curator SOP prefers part_of for anatomy-to-anatomy links and the match quality is poor (mouth → digestive tract, tube → anatomical structure).

Checks

• mkdocs.yaml parses and the new nav entry resolves; the one relative link in the report (../uberon-editor-sop.md) points at docs/uberon-editor-sop.md. mkdocs is not installed in this environment, so the site build itself was not run locally.
• No files under src/ in the diff — git diff --name-only master... -- src/ is empty.

Follow-up, not part of this PR

The 33 proposed axioms are implemented on claude/uberon-has-part-cl-report's sibling branch claude/uberon-missing-has-part-jlis59 (+33 lines in uberon-edit.obo, round-trip stable, ELK-clean, no unsatisfiable classes). That branch has no PR open; happy to raise one, or to trim it to whichever subset survives review of #3769.

@ai4c-agent

🤖 Generated with Claude Code

https://claude.ai/code/session_018SafyR4sVmrWYzfV91tJ1p

---

Generated by Claude Code

[ai4c-reviewer]

Claude finished @mellybelly's task in 4m 2s —— View job

---

Review checklist

• Hierarchy and parents are consistent
• Definitions and supporting references look adequate
• Obsolete or replacement handling is safe
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression

Summary

This is a documentation-only PR (docs/reports/has_part_to_cl_scan_2026-09.md + a 2-line mkdocs.yaml nav entry) — confirmed via git diff origin/master...HEAD -- src/ returning empty, so no ontology axioms are touched by merging it. I spot-checked the report's claims against src/ontology/uberon-edit.obo directly rather than taking them on faith.

What I verified:

• The relative link ../uberon-editor-sop.md in the report resolves correctly to docs/uberon-editor-sop.md.
• The new mkdocs.yaml nav entry is consistently indented with its sibling entries under "Uberon Internal Docs".
• All 13 UBERON IDs/labels I spot-checked across the "Proposed axioms" tables (retina, cortex, hippocampus, striatum, kidney, small intestine, cochlea, lymphatics) match uberon-edit.obo exactly — correct id, correct label, and none of them already carry a has_part/composed_primarily_of to the proposed CL filler (so the candidates are genuine gaps, not duplicates of existing axioms).
• The outer nuclear layer of retina claim (overlaps CL:0000287 {notes="soma"}) in the "Rejected candidates" section matches the live term exactly.
• The "already covered by composed_primarily_of" exclusion for Purkinje cell layer of cerebellar cortex (UBERON:0002979 → composed_primarily_of CL:0000121 ! Purkinje cell) is accurate.

🔵 SUGGESTION — exclusion rule isn't applied uniformly (non-blocking, worth a look before the sibling implementation PR):
ganglionic layer of retina (UBERON:0001792) already carries relationship: composed_primarily_of CL:0000740 ! retinal ganglion cell, yet the report proposes adding has_part CL:0000740 — the identical filler — to that same term. That's the exact pattern the report uses to exclude Purkinje cell layer and dentate gyrus granule cell layer ("already covered by an existing axiom"). To be fair, there is real Uberon precedent for asserting both composed_primarily_of and has_part to the same CL class on one term (e.g. visceral striated muscle tissue → CL:0000746, smooth muscle tissue → CL:0000192, slow/fast muscle → CL:0000189/0000190), so the proposed addition isn't necessarily wrong — but the report's stated exclusion criterion wasn't applied consistently between these cases. Similarly, hippocampus pyramidal layer (UBERON:0002313) already carries composed_primarily_of CL:0000598 ! pyramidal neuron and is proposed to additionally get the more specific has_part CL:1001571 ! hippocampal pyramidal neuron — arguably fine since it's more specific, but it highlights that the "already covered" bucket needs a clearer, uniformly-applied rule (e.g. "exclude only when the existing filler is already maximally specific") rather than "excluded because composed_primarily_of exists." Worth tightening before triaging the 33 axioms for real on the sibling branch.

🔵 SUGGESTION — PMIDs not independently re-verified: this review environment had no outbound network access, so I could not re-check the 18 cited PMIDs against Europe PMC myself. The report states they were checked against Europe PMC before use; I'd still recommend a spot re-check when the sibling implementation PR (claude/uberon-missing-has-part-jlis59) comes up for review, since that's where the axioms actually land in uberon-edit.obo.

No 🔴 CRITICAL or 🟡 IMPORTANT issues — nothing here blocks merging this docs-only PR.
· branch claude/uberon-has-part-cl-report

[ai4c-reviewer]

Documentation-only PR (report + mkdocs.yaml nav entry, no src/ changes). Spot-checked 13+ UBERON term IDs/labels cited in the report against uberon-edit.obo directly — all accurate, and none duplicate existing has_part/composed_primarily_of axioms for their proposed CL fillers. Verified the relative SOP link resolves and the mkdocs nav entry is well-formed.

Only two 🔵 non-blocking suggestions (full detail in the PR comment):

1. The report's "already covered by composed_primarily_of" exclusion rule (used to reject Purkinje cell layer / dentate gyrus granule cell layer) isn't applied uniformly — ganglionic layer of retina (UBERON:0001792) already has composed_primarily_of CL:0000740, yet gets a proposed has_part CL:0000740 to the identical filler. There is Uberon precedent for asserting both properties to the same class, so this isn't necessarily wrong, but the stated rule should be tightened before the sibling implementation PR is triaged.
2. I had no network access in this review environment to re-verify the 18 cited PMIDs against Europe PMC; worth a spot re-check when the sibling branch (with the actual axioms) comes up for review.

No CRITICAL or IMPORTANT issues. Approving.

[matentzn]

What precisely is the rationale to have this kind of information in git rather than simply as GitHub issues?

[cmungall]

What precisely is the rationale to have this kind of information in git rather than simply as GitHub issues?

I think the 3 of us + @dosumis should have a conversation about the general strategy re issues vs docs

...but in this case it's not so important we can leave this as is for now and just start doing the work that is outlined, IMO it all makes sense, let's start making PRs!