Merge pull request #622 from geneontology/pgaudet-patch-48

Update ontology-documentation.md

_docs/ontology-documentation.md

@@ -18,24 +18,69 @@ The Gene Ontology (GO) is a structured, standardized representation of biologica
 # GO aspects
 The GO is organized in three *aspects*, Molecular Function (MF), Cellular Component (CC) and Biological Process (BP). 
 ### Molecular Function
-Molecular-level activities performed by gene products, such as "catalysis" or "transcription regulator activity". GO MF terms represent *activities* and not the *entities* that perform the actions. MFs do not specify where, when, or in what context the action takes place. MFs correspond to activities that can be performed by individual gene products (*i.e.* a protein or RNA), but some activities are performed by molecular complexes composed of multiple gene products, when the activity cannot be ascribed to a single gene product of the complex. Examples of broad functional terms are *[catalytic activity](http://amigo.geneontology.org/amigo/term/GO:0003824){:target="blank"}* and *[transporter activity](http://amigo.geneontology.org/amigo/term/GO:0005215){:target="blank"}*; examples of narrower functional terms are *[adenylate cyclase activity](http://amigo.geneontology.org/amigo/term/GO:0004016){:target="blank"}* or *[insulin receptor activity](http://amigo.geneontology.org/amigo/term/GO:0005009){:target="blank"}*. To avoid confusion between gene product names and their molecular activities, GO MFs are appended with the word "activity" (a *protein kinase* would have the GO MF *protein kinase activity*).
+MF represent molecular-level activities performed by gene products, such as "catalysis" or "transcription regulator activity". MFs correspond to activities that can be performed by individual gene products (*i.e.* a protein or RNA), but some activities are performed by molecular complexes composed of multiple gene products, when the activity cannot be ascribed to a single gene product of the complex. Examples of broad functional terms are *[catalytic activity](http://amigo.geneontology.org/amigo/term/GO:0003824){:target="blank"}* and *[transporter activity](http://amigo.geneontology.org/amigo/term/GO:0005215){:target="blank"}*; examples of narrower functional terms are *[adenylate cyclase activity](http://amigo.geneontology.org/amigo/term/GO:0004016){:target="blank"}* or *[insulin receptor activity](http://amigo.geneontology.org/amigo/term/GO:0005009){:target="blank"}*. 
+
+Note that GO MF terms represent *activities* and not the *entities* that perform the actions. To avoid confusion between gene product names and their molecular activities, GO MFs are appended with the word "activity" (a *protein kinase* would have the GO MF *protein kinase activity*). Finally, MFs do not specify where, when, or in what context the action takes place. 
+
 ### Cellular Component
-The location in the cell where a molecular function takes place. Includes: 
+CC serves to capture the cellular location where a molecular function takes place. It includes: 
 + *[cellular anatomical structures](http://amigo.geneontology.org/amigo/term/GO:0110165){:target="blank"}*, emcompassing cellular entities such as the *[plasma membrane](http://amigo.geneontology.org/amigo/term/GO:0005886){:target="blank"}* and the *[cytoskeleton](http://amigo.geneontology.org/amigo/term/GO:0005856){:target="blank"}*, as well as membrane-enclosed cellular compartments such as the *[mitochondrion](http://amigo.geneontology.org/amigo/term/GO:0005739){:target="blank"}*.  
 + stable *[protein-containing complexes](http://amigo.geneontology.org/amigo/term/GO:0032991){:target="blank"}* of which they are parts. 
 + *[virion components](http://amigo.geneontology.org/amigo/term/GO:0044423){:target="blank"}*, classified separately because viruses are not cellular organisms. Examples include *[viral capsid](http://amigo.geneontology.org/amigo/term/GO:0019028){:target="blank"}* and *[viral envelope](http://amigo.geneontology.org/amigo/term/GO:0019031){:target="blank"}*.
+
 ### Biological Process
-The larger processes, or ‘biological programs’ accomplished by multiple molecular activities. Examples of broad BP terms are *[DNA repair](http://amigo.geneontology.org/amigo/term/GO:0006281){:target="blank"}* or *[signal transduction](http://amigo.geneontology.org/amigo/term/GO:0007165){:target="blank"}*. Examples of more specific terms are *[cytosine biosynthetic process](http://amigo.geneontology.org/amigo/term/GO:0046089){:target="blank"}* or *[D-glucose transmembrane transport](http://amigo.geneontology.org/amigo/term/GO:1904659){:target="blank"}*. 
+BPs are the larger processes or ‘biological programs’ accomplished by the concerted action of multiple molecular activities. Examples of broad BP terms are *[DNA repair](http://amigo.geneontology.org/amigo/term/GO:0006281){:target="blank"}* or *[signal transduction](http://amigo.geneontology.org/amigo/term/GO:0007165){:target="blank"}*. Examples of more specific terms are *[cytosine biosynthetic process](http://amigo.geneontology.org/amigo/term/GO:0046089){:target="blank"}* or *[D-glucose transmembrane transport](http://amigo.geneontology.org/amigo/term/GO:1904659){:target="blank"}*. 
 
 Each of the three GO aspects is represented by a separate root ontology term. Moreover, the three GO aspects are *is a disjoint*, meaning that no *is a* relation exists between terms from the different ontology aspects. However, other relationships such as *part of* and *occurs in* can operate between terms from different GO aspects. For example, the MF term *[cyclin-dependent protein kinase activity](http://amigo.geneontology.org/amigo/term/GO:0051726)* is *part of* the BP *[regulation of cell cycle](http://amigo.geneontology.org/amigo/term/GO:0051726)*.
 
 # The GO hierarchy
-The GO is structured as a graph in which each GO term is a *node* and the relationships between the nodes are *edges*. GO is hierarchical, with *child* terms being more specialized than their *parent* terms, but unlike a strict hierarchy, a term may have more than one parent term (note that the parent/child model does not hold true for all types of relations, see the [relations documentation](/docs/ontology-relations/)). For example, the biological process term [hexose biosynthetic process](http://amigo.geneontology.org/amigo/term/GO:0019319){:target="blank"} has two parents, [hexose metabolic process](http://amigo.geneontology.org/amigo/term/GO:0019318){:target="blank"} and [monosaccharide biosynthetic process](http://amigo.geneontology.org/amigo/term/GO:0046364){:target="blank"}. This reflect the fact that *biosynthetic process* is a subtype of *metabolic process* and a *hexose* is a subtype of *monosaccharide*.
+The GO is structured as a graph in which each GO term is a *node* and the relationships between the nodes are *edges*. GO is hierarchical, with *child* terms being more specialized than their *parent* terms, but unlike a strict hierarchy, a term may have more than one parent term (note that the parent/child model does not hold true for all types of relations, see the [relations documentation](/docs/ontology-relations/)). For example, the biological process term [hexose biosynthetic process](http://amigo.geneontology.org/amigo/term/GO:0019319){:target="blank"} has two parents, [hexose metabolic process](http://amigo.geneontology.org/amigo/term/GO:0019318){:target="blank"} and [monosaccharide biosynthetic process](http://amigo.geneontology.org/amigo/term/GO:0046364){:target="blank"}. This reflects the fact that *biosynthetic process* is a subtype of *metabolic process* and a *hexose* is a subtype of *monosaccharide*.
 
 [link description](/assets/hexose-biosynthetic-process.png){:width="450"}
 
+# GO term elements
+
+## Mandatory elements
+### Unique identifier and term name 
+Every term has a human-readable term name — e.g. [mitochondrion](http://amigo.geneontology.org/amigo/term/GO:0005739), [glucose transmembrane transport](http://amigo.geneontology.org/amigo/term/GO:1904659), or [amino acid binding](http://amigo.geneontology.org/amigo/term/GO:0016597) — and a GO ID, a unique seven digit identifier prefixed by GO:, e.g. [GO:0005739](http://amigo.geneontology.org/amigo/term/GO:0005739), [GO:1904659](http://amigo.geneontology.org/amigo/term/GO:1904659), or [GO:0016597](http://amigo.geneontology.org/amigo/term/GO:0016597). 
+
+### Aspect
+Denotes which of the three sub-ontologies (MF, CC or BP) the term belongs to. Written as *molecular_function*, *biological_process* and *cellular component*.
+
+### Definition
+A textual description of what the term represents, plus reference(s) to the source of the information. 
+
+### Relationships to other terms
+How the term relates to other terms in the ontology. All terms (other than the root terms representing each aspect, above) have an *is a* sub-class relationship to another term; for example, [glucose transmembrane transport (GO:1904659)](http://amigo.geneontology.org/amigo/term/GO:1904659){:target="blank"}{:target="blank"} is a [monosaccharide transport (GO:0015749)](http://amigo.geneontology.org/amigo/term/GO:0015749){:target="blank"}. The Gene Ontology employs a number of other relations; the [relations documentation page](/docs/ontology-relations/) describes the relations used in the ontology.
+
+## Optional elements
+### Secondary IDs (also known as Alternate ID)
+Secondary IDs come about when two or more terms are identical in meaning, and are merged into a single term. All terms IDs are preserved so that no information (for example, annotations to the merged IDs) is lost.
+
+### Synonyms
+Alternative words or phrases closely related in meaning to the term name, with indication of the relationship between the name and synonym given by the synonym scope. The scopes for GO synonyms are:
++ **Exact**: an exact equivalent; interchangeable with the term name; for e.g. ornithine cycle is an exact synonym of urea cycle 
++ **Broad**: the synonym is broader than the term name; for e.g. cell division is a broad synonym of cytokinesis 
++ **Narrow**: the synonym is narrower or more precise than the term name; for e.g. pyrimidine-dimer repair by photolyase is a narrow synonym of photoreactive repair
++ **Related**: the terms are related in some imprecise way; for e.g. cytochrome bc1 complex is a related synonym of ubiquinol-cytochrome-c reductase activity virulence is a related synonym of pathogenesis 
+
+Custom synonym types are also used in the ontology. For example, a number of synonyms are designated as systematic synonyms; synonyms of this type are exact synonyms of the term name.
+
+### Database cross-references
+Database cross-references, or dbxrefs, refer to identical or very similar objects in other databases. For instance, the molecular function term [retinal isomerase activity (GO:0004744)](http://amigo.geneontology.org/amigo/term/GO:0004744) is cross-referenced with [RHEA:24124](https://www.rhea-db.org/reaction.xhtml?id=24124); the biological process term [ulfate assimilation (GO:0000103)](http://amigo.geneontology.org/amigo/term/GO:0000103) has the [InterPro](https://www.ebi.ac.uk/interpro/) cross-reference [Sulphate adenylyltransferase (IPR002650)](https://www.ebi.ac.uk/interpro/entry/IPR002650).
+
+### Comment
+Any extra information about the term and its usage.
+
+### Subset
+Indicates that the term belongs to a designated subset of terms, e.g. one of the [GO subsets](/docs/go-subset-guide/).
+
+### Obsolete tag
+Indicates that the term has been deprecated and should not be used. A GO term is obsoleted when it is out of scope, misleadingly named or defined, or describes a concept that would be better represented in another way and needs to be removed from the published ontology. In these cases, the term and ID still persist in the ontology, but the term is tagged as obsolete, and all relationships to other terms are removed. A comment is added to the term detailing the reason for the obsoletion and   replacement terms are suggested, if possible. 
+
+
 # GO is a dynamic ontology
-GO aims to represent the current state of knowledge in biology, hence it is constantly revised and expanded as biological knowledge accumulates.  Revisions to the ontology are managed by a team of ontology editors with extensive experience in both biology and computational knowledge representation. These updates are made collaboratively between the GOC ontology team and scientists who request the updates. Most requests come from scientists making GO annotations (these typically impact only a few terms each), and from domain experts in particular areas of biology (these typically revise an entire ‘branch’ of the ontology comprising many terms and relations). Changes to the ontology can be visualized on the [GO statistics](/stats.html) page. We welcome researchers and computational scientists to [submit requests for either new terms, new relations, or any other improvements to the ontology](/docs/contributing-to-go-terms/).
+GO aims to represent the current state of knowledge in biology, hence it is constantly revised and expanded as biological knowledge accumulates.  Revisions to the ontology are managed by a team of editors with broad biological knowledge and expertise in computational knowledge representation. GO updates are made collaboratively between the GOC ontology team and scientists who request the updates. Most requests come from scientists making GO annotations (these typically impact only a few terms each), and from domain experts in particular areas of biology (these typically revise an entire ‘branch’ of the ontology comprising many terms and relations). Changes to the ontology can be visualized on the [GO statistics](/stats.html) page. We welcome researchers and computational scientists to [submit requests for either new terms, new relations, or any other improvements to the ontology](/docs/contributing-to-go-terms/).
 
 ## More information about the ontology
 * [GO term elements](/docs/ontology/): Description of the format of GO terms.