term-obsoletion

About obsoletion

Obsoletions can fall into these categories:

1. Obsoletion with direct replacement (replaced_by)
2. Obsoletion with candidate replacements (consider)
3. Obsoletion with no candidate replacements.

The first category is easiest. If you are asked to do an obsoletion and are given a direct equivalent replacement, and the replacement looks reasonable, you don't need to do a detailed impact assessment. But you do need to do the "rewiring" yourself.

For the other two categories, you need to think hard about impacts. If the course of action is unclear, don't make changes, instead communicate questions in your issue comments.

We never do complete merges now, so there should be no alt_ids or disappearing obo format stanzas. If a user asks for a merge, they usually mean obsoletion with direct replacement

Obsolete terms should have no logical axioms, and must have the correct metadata

An obsolete term should have

• no is_a, relationship, or intersection_of tags
• the name MUST be name: obsolete <original name>
• the definition MUST be def: "OBSOLETE. <original def>" [<original dbxrefs>]
• a term tracker item
• a reason for obsoletion in the comment
• synonyms preserved from the original term (see "Synonyms on obsolete terms" below)
• original axioms transferred to other terms as appropriate

Here is an exemplar obsoleted term:

[Term]
id: GO:0000170
name: obsolete sphingosine hydroxylase activity
namespace: molecular_function
def: "OBSOLETE. Catalysis of the hydroxylation of sphingolipid long chain bases." [PMID:9556590]
comment: The reason for obsoletion is that this term is equivalent to sphingolipid C4-monooxygenase activity.
synonym: "sphingosine hydroxylase" RELATED [PMID:9556590]
property_value: term_tracker_item "https://github.com/geneontology/go-ontology/issues/29717" xsd:anyURI
is_obsolete: true
replaced_by: GO:0102772

Note that the information that remains is critical provenance about either the history of the term (name, definition, placement via namespace, synonyms with their source attribution), or obsoletion metadata. There are no relationships or logical axioms.

Synonyms on obsolete terms

For GO, synonyms are preserved on obsoleted terms by default. This includes:

• All synonyms regardless of scope (EXACT, BROAD, NARROW, RELATED)
• All synonym metadata, including any PMID or other dbxref attributions on the synonym
• Synonyms remain useful as a search aid: a curator looking up an old synonym still lands on the obsolete stanza and can follow the replaced_by / consider pointers to the current term(s)

Do not strip synonyms when obsoleting a GO term unless the requester explicitly asks for it (e.g. because a synonym is misleading, or because it has been transferred to a replacement term and would now be ambiguous on the obsolete stanza).

Transferring axioms

Usually when a term is obsoleted, any "good" information is typically transferred to other terms. For obsoletions with direct replacement, this is a straightforward transfer. For more complex cases (e.g. splits or merges, cases where the original term was ambiguous), then judgment should be applied, and in general we want to preserve where things go.

Note that synonym transfer to a replacement term is separate from synonym retention on the obsolete stanza — for GO, do both where appropriate: copy useful synonyms onto the replacement term AND keep them on the obsolete term.

For example consider a poor ontology term that is ambiguous:

[Term]
id: GO:ORIGINAL1
name: leg development
def: "Development of a leg. A leg is an appendage on which an organism walks" [Wikipedia:Leg]
synonym: "limb development" EXACT []
synonym: "appendage development" EXACT []
synonym: "development of limb" EXACT []
is_a: ...

This may be obsoleted with two potential replacements:

[Term]
id: GO:ORIGINAL1
name: obsolete leg development
def: "OBSOLETE. Development of a leg. A leg is an appendage on which an organism walks" [Wikipedia:Leg]
synonym: "limb development" EXACT []
synonym: "appendage development" EXACT []
synonym: "development of limb" EXACT []

[Term]
id: GO:NEW1
name: limb development
def: "Development of a limb. A limb is a tetrapod appendange evolved from a fin." [PMID:<...>]
synonym: "appendage development" RELATED []
synonym: "development of limb" EXACT []
is_a: ...

[Term]
id: GO:NEW1
name: insect leg development
def: "Development of an insect limb." [PMID:<...>]
is_a: ...

Note the obsoleted term retains its synonyms (per GO convention) — even though some have also been transferred to replacement terms or have become the primary label ("limb development") on a replacement. Keeping them on the obsolete stanza preserves the search aid: a curator looking up "limb development" against the historical ID still lands on the obsolete term and can follow replaced_by / consider. The provenance for the original (poor) definition also remains, as a matter of history.

Ensure no existing terms reference the term to be obsoleted

If you are obsoleting GO:1234567, you can find usages:

obo-grep.pl GO:1234567 src/ontology/go-edit.obo

You must remove these usages. Do not just delete edges without thinking. You must think hard about replacement terms. If you deem the impact of obsoletion to be too high or you need feedback on how to handle cascading effects, you should stop short of obsoleting the term, and instead provide an impact analysis and open questions in your gh issue summary.

Analyzing impact of obsoletion on other ontologies

Many of the core biological ontologies that use GO are in Ubergraph:

runoak -i ubergraph: usages GO:1234567

For example, if we use this with GO:0051321 (meiotic cell cycle), we see something like:

used_id	used_by_id	predicate	source	dataset	context	axiom	description
GO:0051321	GO:0019953	BFO:0000050	UbergraphImplementation	None	UsageContext.RELATIONSHIP_SUBJECT	None	None
GO:0051321	NCBITaxon:2759	RO:0002162	UbergraphImplementation	None	UsageContext.RELATIONSHIP_SUBJECT	None	None
GO:0051321	FYPO:0000052	UPHENO:0000001	UbergraphImplementation	None	UsageContext.RELATIONSHIP_OBJECT	None	None
GO:0051321	CL:0000657	RO:0002216	UbergraphImplementation	None	UsageContext.RELATIONSHIP_OBJECT	None	None
GO:0051321	Wikipedia:Meiosis	oio:hasDbXref	UbergraphImplementation	None	UsageContext.MAPPING_SUBJECT	None	None
...

The first row is a GO-internal axiom (a part_of relationship between two GO terms). The second row arises from GO axioms we add for taxon constraints: it is still a GO-internal axiom, but it references an external identifier from NCBITaxon rather than indicating that NCBITaxon depends on GO. The FYPO and CL rows are important because they show that these two ontologies have axioms that directly reference GO terms; for these kinds of external ontologies, sufficient warning should be given to the ontology maintainers when making impactful changes. The final row shows a GO dbxref mapping to an external resource (Wikipedia) that is maintained within GO and does not, by itself, imply an external ontology that needs to be notified.

Analyzing impact of obsoletion on GO annotations

For all obsoletions, analyze the impact on gene annotations. You will want to maintain a specific TODO list here, and report back your analysis when you report back on the issue

Step 1: Find All Annotations to the obsoleted term

Use OAK (Ontology Access Kit) to find all direct usages of the term in gene product annotations:

runoak -i amigo: associations GO:nnnnnnn

Important notes:

• Use amigo: as the adapter (connects to GO annotation database)
• This finds DIRECT annotations only (not inferred). This is what we want
• Output includes: gene product ID, taxon, evidence code, and PMID reference

Parse the results to identify:

• Total number of annotations
• Unique PMIDs referenced
• Evidence codes used (IDA, IMP, IPI, etc.)
• Taxonomic distribution
• Gene products annotated

Update the todo list with one item per unique PMID for detailed analysis.

Step 2: Analyze Each Publication (One PMID at a Time)

Use the /research skill to explore publications. This should give you a clue for potential replacement terms.

2a. Analyze Annotation Validity

For each annotation from this PMID, determine:

Question 1: Is the annotation still valid?

• Does the paper actually support annotating to the obsolete term?
• Was the annotation accurate when made?
• Is this a case of over-annotation (too specific when a broader term would be better)?

Question 2: What action should be taken?

Option A: Replace with specific term

• If the issue proposes a replacement term, verify it matches the experimental evidence
• If no replacement proposed, identify the most appropriate term based on the paper
• Use obo-grep.pl to verify proposed replacement terms exist

Option B: Remove annotation

• If the term is obsolete due to being erroneous or out of scope
• If the experimental evidence doesn't actually support any specific annotation
• If this is a clear case of over-annotation

Option C: Migrate to parent/broader term

• If the obsolete term is too specific but a valid parent exists
• Check the term hierarchy using obo-grep.pl -r 'id: GO:nnnnnnn' src/ontology/go-edit.obo

2b. Document Findings

For each PMID analyzed, provide:

1. PMID and paper title
2. Number of annotations from this paper
3. Relevant experimental context (quote key sentences from the paper)
4. Recommendation (replace/remove/migrate)
5. Proposed term (if recommending replacement)
6. Justification (why this action is appropriate)

Example format:

"<Title of the paper>"
SUPPORT: <PMID:localId> "<Exact excerpt from the paper>
- finding 1
- finding 2
- ...

Recommendations:

* Replace <GO:nnnnnnn> with <GO:nnnnnn> "<term label>" ## Justification

2c. Flag Over-Annotation

Watch for cases where:

• Annotation is more specific than experimental evidence supports
• High-throughput studies have been over-interpreted
• Indirect evidence (IEA, ISS) is used for very specific terms
• Multiple highly specific terms when a broader term would be more appropriate

Mark the corresponding todo as completed after analyzing each PMID.

Step 3: Repoort back findings

After analyzing all PMIDs (or after analyzing significant subsets), update the GitHub issue:

Include a detailed analysis in the issue comments.

Include in updates:

• Summary of annotations analyzed
• Breakdown by recommendation type (replace/remove/migrate)
• Specific findings for each PMID (can be grouped if many have same recommendation)
• Any over-annotation concerns flagged
• Questions or uncertainties requiring curator input

Statistics:

• Total annotations examined: N
• Annotations to replace: N (with term GO:nnnnnnn)
• Annotations to remove: N
• Annotations to migrate to parent: N
• Over-annotations flagged: N

Action items for curators:

• List specific gene products requiring annotation updates
• Provide replacement terms with supporting evidence
• Note any patterns or systematic issues discovered

Best Practices

Reading Publications Efficiently

• Look for direct evidence of the specific molecular function/process/component
• Quote exact sentences that support or refute the annotation
• Note figures/tables that show the key evidence
• In some cases, full text is not available. Always note this in your report

Maintaining Context

• Keep the GitHub issue number visible in your analysis
• Reference the obsolete term ID consistently
• Link findings back to specific gene products when relevant

Handling Ambiguity

If uncertain about the correct replacement term:

1. Check the term hierarchy and definitions using obo-grep.pl
2. Look for similar annotations in the paper
3. Note the uncertainty in your update and ask for curator guidance
4. Don't guess - it's better to flag for manual review

Managing Large Annotation Sets

For terms with 50+ annotations:

• Sample representative PMIDs first (different taxa, evidence codes, time periods)
• Look for patterns
• Report interim findings before analyzing all
• Consider grouping PMIDs with similar contexts

Tool Reference

Find annotations:

runoak -i amigo: associations GO:nnnnnnn

Fetch publication full text:

Use WebTools

Search ontology for terms:

obo-grep.pl -r 'id: GO:nnnnnnn' src/ontology/go-edit.obo

Update GitHub issue:

gh issue comment ISSUE_NUMBER --body "Your comment here"
gh issue view ISSUE_NUMBER  # To read the issue

Common Patterns

Pattern 1: Direct Replacement

Obsolete term has exact replacement - verify all annotations can migrate cleanly.

Pattern 2: Split Terms

Obsolete term was too broad, split into multiple specific terms - each annotation needs individual assessment.

Pattern 3: Erroneous Term

Term was incorrectly defined - annotations may need removal or migration to very different terms.

Pattern 4: Out of Scope

Term removed from GO scope - determine if annotations should move to related ontology or be removed.

Notes

• This is detailed, evidence-based work - thoroughness is more important than speed
• Provide enough context that curators can make informed decisions
• Direct quotes from papers are highly valuable
• Flag uncertainties rather than making unsupported recommendations