Guidelines for GO textual definitions: Difference between revisions

From GO Wiki
Jump to navigation Jump to search
mNo edit summary
(31 intermediate revisions by the same user not shown)
Line 1: Line 1:
   BEING REVIEWED
   BEING REVIEWED
  See https://douroucouli.wordpress.com/2019/07/08/ontotip-write-simple-concise-clear-operational-textual-definitions/


==General points about definitions of GO terms==
==General points about definitions of GO terms==
Line 6: Line 8:
* They should be concise, full sentences (they should begin with an upper-case letter and end with a period).  
* They should be concise, full sentences (they should begin with an upper-case letter and end with a period).  
* As with term names, avoid using abbreviations that may be ambiguous (e.g. "ER" can mean "endoplasmic reticulum" or "estrogen receptor").
* As with term names, avoid using abbreviations that may be ambiguous (e.g. "ER" can mean "endoplasmic reticulum" or "estrogen receptor").
* See Chris' post [https://douroucouli.wordpress.com/2019/07/08/ontotip-write-simple-concise-clear-operational-textual-definitions/ OntoTip: Write simple, concise, clear, operational textual definitions]


 
==Use genus-differentia patterns for definitions==
==Use Aristotelian definitions==
Ideally, definitions should follow the genus-differentia ("Aristotelian") pattern: they should take the form of a genus (generic term, an is_a parent) and differentia (discriminating characteristics which mark instances of the specific term as being different from is_a sibling terms). Hence, the general form should be: <code>An A that B</code>, where A is the parent (genus), and B is what differentiates it from the parent (differentia).
Ideally, definitions should follow the genus-differentia ("Aristotelian") pattern: they should take the form of a genus (generic term, an is_a parent) and differentia (discriminating characteristics which mark instances of the specific term as being different from is_a sibling terms).  


For example, a spindle microtubule is defined as "Any microtubule that is part of a mitotic or meiotic spindle; anchored at one spindle pole."
For example, a spindle microtubule is defined as "Any microtubule that is part of a mitotic or meiotic spindle; anchored at one spindle pole."
Line 17: Line 19:
The genus and differentia should make the definition necessary and sufficient such that all terms that are subclasses of that term satisfy the definition of the term, and any term that is not a subclass of the term does not satisfy the definition.  
The genus and differentia should make the definition necessary and sufficient such that all terms that are subclasses of that term satisfy the definition of the term, and any term that is not a subclass of the term does not satisfy the definition.  


In some cases, it is appropriate to add to the core definition to improve the comprehensibility. This can include further explanations of the genus and/or differentia or examples of the term usage.  
In some cases, it is appropriate to add to the core definition to improve the comprehensibility. This can include further explanations of the genus and/or differentia or examples of the term usage.


===Use of standard definitions===
==Define Beginning and End for processes==
==Use of standard definitions==


  NOT YET REVIEWED
  CURRENT PROPOSAL is to use the DOS design patterns.
  https://github.com/geneontology/go-ontology/tree/master/src/design_patterns
 
Similar terms may be defined in a standard way. In some cases, design patterns exist for those terms and the term definition is specified in the yaml (https://github.com/geneontology/go-ontology/tree/master/src/design_patterns).


Wherever a 'standard' definition exists for a group of related terms, it should be used; please see the ontology guides for standard definitions used in each ontology. If you find yourself repeatedly using the same text string in a series of definitions, please add to the standard definitions:  
Wherever a 'standard' definition exists for a group of related terms, it should be used; please see the ontology guides for standard definitions used in each ontology. If you find yourself repeatedly using the same text string in a series of definitions, please add to the standard definitions:  
   
   
   Link to http://geneontology.org/page/ontology-documentation
   Link to http://geneontology.org/page/ontology-documentation
  Link to https://github.com/geneontology/go-ontology/tree/master/src/design_patterns
   Look for any other pages in the wiki such as http://wiki.geneontology.org/index.php/Transporter_terms_standard_definitions
   Look for any other pages in the wiki such as http://wiki.geneontology.org/index.php/Transporter_terms_standard_definitions


==Redefining terms==
NOT YET REVIEWED


A GO ID is really associated with a definition rather than with the term name. If we change the wording but not the meaning of a term, the GO ID stays the same; a new meaning requires a new GO ID, even if the text string doesn't change. Here's a trivial example that illustrates when we do and don't change GO IDs:


; membrane fusion
Assume that we have a term mouse, GO ID GO:0000123, in an ontology; it is defined as a small furry mammal.
: The joining of the lipid bilayer membrane around X to the lipid bilayer membrane around Y.  


; ''cellular component'' organization
We decide to change the term wording to Mus musculus, keeping the definition the same. In this case we merely update the text; the GO ID stays the same because the meaning stays the same. We may choose to keep "mouse" as a synonym, but there would still only be one ID associated with the term.
: A process that is carried out at the cellular level which results in the assembly, arrangement of constituent parts, or disassembly of ''cellular component''.  


; ''cellular component'' biogenesis
We decide that the term "mouse" should instead mean a piece of computer equipment. In this case, the old term and ID are moved to the obsolete category, and "mouse", as newly defined, gets a new GO ID, GO:0000456. The old GO ID and definitions are saved for posterity in case we ever need to know what happened to them.
: The process by which a ''cellular component'' is synthesized, aggregates, and bonds together.  


; ''macromolecular complex'' assembly
: The aggregation, arrangement and bonding together of a set of components to form a ''macromolecular complex''.


; ''xxx'' distribution
==Database cross-references for definitions==
: Any process that establishes the spatial arrangement of ''xxx''.


There are two types of definition cross-references: (a) those that attribute the term to the contributing group(s) or individual(s) (optional), and (b) scientific references supporting the creation of the term and its meaning (ideally, minimum one reference). For the former type of cross-reference, use the database abbreviation 'GOC' and the initials of the user or the group as described in the [https://github.com/geneontology/go-site/blob/master/metadata/users.yaml GO users.yaml file]. For the latter type of cross-reference, use the appropriate source such as PMID:, ISBN:, Wikipedia:, RHEA:, EC:, etc.
* Preferred: an open-access PMID, and/or a RHEA for catalytic activities.
* GOC:curators should be used as a last resort, for example for grouping terms (like NAD(P)-containing terms) for which there is no direct evidence because the activity doesn't exist. We can link to internal documentation in the wiki, or design patterns.


===Format===
See [[Identifiers]]


===Redefining terms===
===Creating new users to the users.yaml file===
# GO to https://github.com/geneontology/go-site/blob/master/metadata/users.yaml
# Add the cross-ref
# Commit
# Create pull request
# Merge (ask someone to approve if appropriate)


NOT YET REVIEWED
===Guidelines for individuals and groups dbxref abbreviations===
 
A GO ID is really associated with a definition rather than with the term name. If we change the wording but not the meaning of a term, the GO ID stays the same; a new meaning requires a new GO ID, even if the text string doesn't change. Here's a trivial example that illustrates when we do and don't change GO IDs:
 
Assume that we have a term mouse, GO ID GO:0000123, in an ontology; it is defined as a small furry mammal.
 
We decide to change the term wording to Mus musculus, keeping the definition the same. In this case we merely update the text; the GO ID stays the same because the meaning stays the same. We may choose to keep "mouse" as a synonym, but there would still only be one ID associated with the term.


We decide that the term "mouse" should instead mean a piece of computer equipment. In this case, the old term and ID are moved to the obsolete category, and "mouse", as newly defined, gets a new GO ID, GO:0000456. The old GO ID and definitions are saved for posterity in case we ever need to know what happened to them.
* Curators: use the GOC and the initials in lower case as the ID; e.g. a definition written by Michael Ashburner has the dbxref GOC:ma.
* Group of curators: use the database abbreviation with '_curators' appended; e.g. a definition written by several curators at TAIR has the dbxref GOC:TAIR_curators.
* Experts from the community: use the expert's initials following 'GOC:expert_'; e.g. a definition from John Pringle has the dbxref GOC:expert_jrp.
* For definitions created at meetings, the dbxref has 'mtg_' followed by the meeting start date; e.g. definitions written at the June 2006 content meeting on CNS development have the dbxref GOC:mtg_15jun06.)




[[Ontology_Development#Editing_the_Ontology |Back to: Editing the Ontology]]


[[Category:Curator_Guides]][[Category:Ontology]]
[[Category:GO Editors]][[Category:Ontology]][[Category:Editor_Guide_2018]][[Category:To be reviewed]]

Revision as of 12:42, 23 May 2022

  BEING REVIEWED
 See https://douroucouli.wordpress.com/2019/07/08/ontotip-write-simple-concise-clear-operational-textual-definitions/

General points about definitions of GO terms

  • All terms require a definition and a definition cross-reference.
  • Definitions should explain clearly to the reader what is meant by a particular term.
  • They should be concise, full sentences (they should begin with an upper-case letter and end with a period).
  • As with term names, avoid using abbreviations that may be ambiguous (e.g. "ER" can mean "endoplasmic reticulum" or "estrogen receptor").
  • See Chris' post OntoTip: Write simple, concise, clear, operational textual definitions

Use genus-differentia patterns for definitions

Ideally, definitions should follow the genus-differentia ("Aristotelian") pattern: they should take the form of a genus (generic term, an is_a parent) and differentia (discriminating characteristics which mark instances of the specific term as being different from is_a sibling terms). Hence, the general form should be: An A that B, where A is the parent (genus), and B is what differentiates it from the parent (differentia).

For example, a spindle microtubule is defined as "Any microtubule that is part of a mitotic or meiotic spindle; anchored at one spindle pole."

  • Genus: Any microtubule
  • Differentia: part of a mitotic or meiotic spindle; anchored at one spindle pole

The genus and differentia should make the definition necessary and sufficient such that all terms that are subclasses of that term satisfy the definition of the term, and any term that is not a subclass of the term does not satisfy the definition.

In some cases, it is appropriate to add to the core definition to improve the comprehensibility. This can include further explanations of the genus and/or differentia or examples of the term usage.

Define Beginning and End for processes

Use of standard definitions

CURRENT PROPOSAL is to use the DOS design patterns. 
 https://github.com/geneontology/go-ontology/tree/master/src/design_patterns

Similar terms may be defined in a standard way. In some cases, design patterns exist for those terms and the term definition is specified in the yaml (https://github.com/geneontology/go-ontology/tree/master/src/design_patterns).

Wherever a 'standard' definition exists for a group of related terms, it should be used; please see the ontology guides for standard definitions used in each ontology. If you find yourself repeatedly using the same text string in a series of definitions, please add to the standard definitions:

 Link to http://geneontology.org/page/ontology-documentation
 Look for any other pages in the wiki such as http://wiki.geneontology.org/index.php/Transporter_terms_standard_definitions

Redefining terms

NOT YET REVIEWED 

A GO ID is really associated with a definition rather than with the term name. If we change the wording but not the meaning of a term, the GO ID stays the same; a new meaning requires a new GO ID, even if the text string doesn't change. Here's a trivial example that illustrates when we do and don't change GO IDs:

Assume that we have a term mouse, GO ID GO:0000123, in an ontology; it is defined as a small furry mammal.

We decide to change the term wording to Mus musculus, keeping the definition the same. In this case we merely update the text; the GO ID stays the same because the meaning stays the same. We may choose to keep "mouse" as a synonym, but there would still only be one ID associated with the term.

We decide that the term "mouse" should instead mean a piece of computer equipment. In this case, the old term and ID are moved to the obsolete category, and "mouse", as newly defined, gets a new GO ID, GO:0000456. The old GO ID and definitions are saved for posterity in case we ever need to know what happened to them.


Database cross-references for definitions

There are two types of definition cross-references: (a) those that attribute the term to the contributing group(s) or individual(s) (optional), and (b) scientific references supporting the creation of the term and its meaning (ideally, minimum one reference). For the former type of cross-reference, use the database abbreviation 'GOC' and the initials of the user or the group as described in the GO users.yaml file. For the latter type of cross-reference, use the appropriate source such as PMID:, ISBN:, Wikipedia:, RHEA:, EC:, etc.

  • Preferred: an open-access PMID, and/or a RHEA for catalytic activities.
  • GOC:curators should be used as a last resort, for example for grouping terms (like NAD(P)-containing terms) for which there is no direct evidence because the activity doesn't exist. We can link to internal documentation in the wiki, or design patterns.

Format

See Identifiers

Creating new users to the users.yaml file

  1. GO to https://github.com/geneontology/go-site/blob/master/metadata/users.yaml
  2. Add the cross-ref
  3. Commit
  4. Create pull request
  5. Merge (ask someone to approve if appropriate)

Guidelines for individuals and groups dbxref abbreviations

  • Curators: use the GOC and the initials in lower case as the ID; e.g. a definition written by Michael Ashburner has the dbxref GOC:ma.
  • Group of curators: use the database abbreviation with '_curators' appended; e.g. a definition written by several curators at TAIR has the dbxref GOC:TAIR_curators.
  • Experts from the community: use the expert's initials following 'GOC:expert_'; e.g. a definition from John Pringle has the dbxref GOC:expert_jrp.
  • For definitions created at meetings, the dbxref has 'mtg_' followed by the meeting start date; e.g. definitions written at the June 2006 content meeting on CNS development have the dbxref GOC:mtg_15jun06.)


Back to: Editing the Ontology