Guidelines for GO textual definitions: Difference between revisions

From GO Wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
(25 intermediate revisions by the same user not shown)
Line 1: Line 1:
   REVIEW and change to 'Writing a good textual definition'
   BEING REVIEWED


; membrane fusion
  See https://douroucouli.wordpress.com/2019/07/08/ontotip-write-simple-concise-clear-operational-textual-definitions/
: The joining of the lipid bilayer membrane around X to the lipid bilayer membrane around Y.  


; ''cellular component'' organization
==General points about definitions of GO terms==
: A process that is carried out at the cellular level which results in the assembly, arrangement of constituent parts, or disassembly of ''cellular component''.  
* 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 [https://douroucouli.wordpress.com/2019/07/08/ontotip-write-simple-concise-clear-operational-textual-definitions/ OntoTip: Write simple, concise, clear, operational textual definitions]


; ''cellular component'' biogenesis
==Use Aristotelian definitions==
: The process by which a ''cellular component'' is synthesized, aggregates, and bonds together.  
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).


; ''macromolecular complex'' assembly
For example, a spindle microtubule is defined as "Any microtubule that is part of a mitotic or meiotic spindle; anchored at one spindle pole."
: The aggregation, arrangement and bonding together of a set of components to form a ''macromolecular complex''.
* Genus: Any microtubule
* Differentia: part of a mitotic or meiotic spindle; anchored at one spindle pole


; ''xxx'' distribution
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.  
: Any process that establishes the spatial arrangement of ''xxx''.


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.


[[Category:Curator_Guides]][[Category:Ontology]]
==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===
 
BEING REVIEWED
 
There are two types of cross-references: those that attribute the term to the contributing group(s) or individual(s) (optional), and scientific references supporting the creation of the term and its meaning (minimum one reference). For the former type of cross-reference, use the database abbreviation 'GOC'. For the latter type of cross-reference, use the appropriate source such as PMID:, Wikipedia:, etc.
 
 
HOW: Database cross-references have two parts, separated by a colon: an abbreviation for the database being cross-referenced (see the list of database cross-references used in GO [https://github.com/geneontology/go-site/blob/master/metadata/users.yaml]) and the ID of the item in that database.
 
The guidelines for creating new dbxrefs are as follows: GO to https://github.com/geneontology/go-site/blob/master/metadata/users.yaml
Add cross-ref
Commit
Create pull request
Merge (ask someone to approve if appropriate)
 
 
 
*If the definition comes from an individual curator's head, use the GOC and your initials in lower case as the ID; e.g. a definition written by Michael Ashburner has the dbxref GOC:ma.
*For a definition created by a 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.
*If an expert from the community has contributed to a definition, 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.
*If the definition comes from a book, use the ISBN; e.g. a dbxref to the Oxford Dictionary of Molecular Biology would be ISBN:0198506732. Hyphens should be removed from the ISBN.
*If the definition comes from a paper, use the PubMed ID, e.g. PMID:11910864. If the paper doesn't have a PubMed ID, use another ID such as a DOI or model organism database ID.
 
[[Ontology_Development#Editing_the_Ontology |Back to: Editing the Ontology]]
 
[[Category:GO Editors]][[Category:Ontology]][[Category:Editor_Guide_2018]][[Category:To be reviewed]]

Revision as of 19:22, 28 February 2020

  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 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: 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

BEING REVIEWED 

There are two types of cross-references: those that attribute the term to the contributing group(s) or individual(s) (optional), and scientific references supporting the creation of the term and its meaning (minimum one reference). For the former type of cross-reference, use the database abbreviation 'GOC'. For the latter type of cross-reference, use the appropriate source such as PMID:, Wikipedia:, etc.


HOW: Database cross-references have two parts, separated by a colon: an abbreviation for the database being cross-referenced (see the list of database cross-references used in GO [1]) and the ID of the item in that database.

The guidelines for creating new dbxrefs are as follows: GO to https://github.com/geneontology/go-site/blob/master/metadata/users.yaml Add cross-ref Commit Create pull request Merge (ask someone to approve if appropriate)


  • If the definition comes from an individual curator's head, use the GOC and your initials in lower case as the ID; e.g. a definition written by Michael Ashburner has the dbxref GOC:ma.
  • For a definition created by a 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.
  • If an expert from the community has contributed to a definition, 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.
  • If the definition comes from a book, use the ISBN; e.g. a dbxref to the Oxford Dictionary of Molecular Biology would be ISBN:0198506732. Hyphens should be removed from the ISBN.
  • If the definition comes from a paper, use the PubMed ID, e.g. PMID:11910864. If the paper doesn't have a PubMed ID, use another ID such as a DOI or model organism database ID.

Back to: Editing the Ontology