Noctua: Difference between revisions

From GO Wiki
Jump to navigation Jump to search
(31 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''Note: If you cannot find what you are looking for and need immediate assistance, please contact the [https://github.com/geneontology/helpdesk/issues/ go-helpdesk].'''
= GO-CAMs and Noctua =
= GO-CAMs and Noctua =
*This documentation is presented in two parts:
*This documentation is presented in two parts:
Line 91: Line 89:




To provide appropriate biological context to a model, additional ontologies may be used.
* To provide appropriate biological context to an annotation or an activity unit, additional ontologies may be used either in GO-CAM or in annotation extensions [link].


==== Cell and Anatomy Ontologies ====
==Cell and Anatomy Ontologies==
* Can be used to describe the location where processes and functions occur.
* Describes the location where processes and functions occur.
* Can be used to describe the location of a GO cellular component.
* Describes the location of a GO cellular component.
 
* Add list
==== Biological Phase and Life Stage Ontologies ====
==Biological Phase and Life Stage Ontologies==
* Can be used to describe the temporal period during which processes and functions occur.
* Describes the temporal period during which processes and functions occur.
* Can be used to describe the temporal period during which a cellular component or anatomical entity exists.
* Describes the temporal period during which a cellular component or anatomical entity exists.
 
* Add list
==== Chemical Ontology ====
==Chemical Ontology (ChEBI) [link]==
* Can be used to capture inputs and outputs of processes and functions.
* Can be used to capture inputs and outputs of processes and functions.
* GO-CAM uses the Chemical Entities of Biological Interest (ChEBI)
* GO-CAM uses the Chemical Entities of Biological Interest (ChEBI)
 
* Sequence Ontology [link]
==== Sequence Ontology ====


Requests to add ontologies to Noctua should be sent to help@geneontology.org
Requests to add ontologies to Noctua should be sent to help@geneontology.org
Line 131: Line 128:


[[File:NLP_home.png|thumb|center|upright=3.00|Noctua Landing Page]]
[[File:NLP_home.png|thumb|center|upright=3.00|Noctua Landing Page]]


==== Filtering Models ====
==== Filtering Models ====
Line 139: Line 137:


[[File:Filtering options.png|thumb|center|upright=3.00|Filtering Options]]
[[File:Filtering options.png|thumb|center|upright=3.00|Filtering Options]]


===== Filtering with the Magnifying Glass =====
===== Filtering with the Magnifying Glass =====


Clicking on the magnifying glass opens up a menu of filter options:
Clicking on the magnifying glass opens up the menu of available filter options:


#'''Ontology term''' (autocomplete)
#'''Ontology term''' (autocomplete)
#'''Gene product''' (autocomplete)
#'''Gene product''' (autocomplete)
#'''Reference''' (enter/return or PMID lookup, enter/return)
#'''Reference'''  
## If entered as free-text, must be the full reference id, e.g. PMID:31884020 or doi:10.1016/j.ydbio.2019.12.010
## Can also use the drop-down prefix menu (and PMID look-up feature) by clicking on the =+ icon.
## Must press return after entering search string.
#'''Organism''' (drop-down list)
#'''Organism''' (drop-down list)
#'''Contributor''' (autocomplete and drop-down list)
#'''Contributor''' (autocomplete and drop-down list)
Line 156: Line 158:


[[File:Filter options menu.png|thumb|center|upright=3.00|Filtering Options]]
[[File:Filter options menu.png|thumb|center|upright=3.00|Filtering Options]]
=== Noctua Form and Graph Editors ===
Noctua has three curation interfaces: 1) the [https://docs.google.com/document/d/1RNbr-2T6CSZfaYKDrom7259IK6ck82vZLThgymyNZ28 Noctua Visual Editor], 2) the Noctua Form and 3) the Noctua Graph Editor.
* The [https://docs.google.com/document/d/1RNbr-2T6CSZfaYKDrom7259IK6ck82vZLThgymyNZ28 Noctua Visual Editor] (VPE) is designed for curating GO-CAM models, i.e. models that include at least two activities/MFs linked by causal relations.
* The Noctua Form is a structured annotation form that is recommended for creating 'standard' GO annotations.
* The Noctua Graph Editor is best suited for linking standard annotations together to create a causal model (GO-CAM).






{| class="wikitable"
{| class="wikitable"
!colspan="3" | Noctua Users Manual
!colspan="2" | Noctua Users Manual
|-
|-
!rowspan="2" | Getting started: the Noctua landing page
!rowspan="2" | Getting started
|[[Browsing and searching annotations and models]]
|[[Browsing and searching annotations and models]]
|-
|-
|[[Login]]
|[[Login]]
|-
|-
!colspan="3" |Creating standard GO annotations
!colspan="2" |Creating standard GO annotations
|-
|-
!rowspan = "3" | Form Editor
!rowspan = "3" | Form Editor
Line 219: Line 228:
!colspan = "2" | Model metadata
!colspan = "2" | Model metadata
|-
|-
!rowspan = "2" | Naming models
!rowspan = "3" | Model titles
|[http://wiki.geneontology.org/index.php/Noctua_Manual:_General_Guidelines_for_Model_Titles General Guidelines]
|-
|[http://wiki.geneontology.org/index.php/Noctua_Manual:_Naming_Models_in_Form Form Editor]
|[http://wiki.geneontology.org/index.php/Noctua_Manual:_Naming_Models_in_Form Form Editor]
|-
|-
Line 246: Line 257:
|}
|}


=== Noctua Annotation Review ===
Documentation on how to use the Noctua Annotation Review workbench is [https://docs.google.com/document/d/1Yo2O7LWj1wdRGbbOlaxX_AFDl99T-P59JOf5YoebX0Q here].


=== Model Copy ===
* Noctua has a model copy functionality that allows users to copy an entire model, minus the evidence.
* Model copy can help curators make efficient use of existing models to create new content.
* More details on model copy and how to use it can be found [https://docs.google.com/document/d/17qlOwSOov-hTKt1wxcyhF1M0XzfQG-r2N6RmhaNj2-E here].


'''CONTENT BELOW THIS POINT MAY BE MODIFIED, MOVED, OR DELETED as of JUNE 2020'''
== Noctua Maintenance ==
 
* The Noctua curation tool undergoes routine maintenance on the second and fourth Thursdays of each month from ~4pm - 7pm PDT.
==Navigating between editors==
* During these maintenance outages the following tasks are typically performed:
*While working on a GO-CAM model, curators may wish to go back and forth between the Form editor and the Graph editor; this can easily be accomplished through the respective form menus.
** Ontology updates:
*From the Form editor, select View > Graph editor to enter the Graph editor (Figure 2).  The graph editor will open in a new browser window.
*** incorporate the latest versions of all ontologies used in Noctua, including NEO (Noctua Entity Ontology)
*From the Graph Editor, select Workbench > Noctua form (Figure 3).  The Form editor will open in a new browser window.
** Model updates:
[[File:Form to graph.png|thumb|left|'''Figure 2. Navigating from the Form to the Graph Editor'''|500px]]
*** replace obsolete ontology terms if there is a 'replaced by' value
[[File:Launch_noctua_activity_form.png|thumb|center|'''Figure 3. Navigating from the Graph Editor to the Form'''|400px]]
*** replace ontology terms if usage has changed
 
*** delete any models marked with state 'delete'
==Editing an existing model==
** Software updates:
'''Note: This section will need updating as the new Form for annotation review and editing comes on board.'''
*** Incorporate bug fixes
*From the Noctua homepage, click on the blue "Edit" button in the rightmost column of the model table (Figure 1).
*** Add new features
*This will take you to the Graph Editor view of the model, where you may make changes to your annotations.
* Noctua maintenance outage reminders are sent out on the go-consortium mailing list ~24 hrs. prior to the outage.
*More information about how to edit an existing model can be found in the section on [http://wiki.geneontology.org/index.php/Noctua#Editing_a_model Editing a model] below.
* For each outage, a list of specific tasks is enumerated in a ticket on the noctua github repo.
  Curation note: Wherever possible, curators should try to build on an existing GO-CAM model, rather than create separate models for each paper curated.  This will allow the set of GO-CAM models to provide the most accurate, up-to-date view of a given Biological Process.
 
==Creating a model using the Noctua form==
*To start a new model using the Noctua form, click on the 'Create new model in Form' link found on the Noctua homepage.
*This will take you to the annotation Form where you can add model metadata and create GO annotations (Figure 4).
[[File:Initial_form_landing.png|thumb|Fig. 4 Noctua form.|700px]]
 
===Step 1. Adding model metadata===
*In addition to the GO annotations that you'll make, each GO-CAM model has specific metadata associated with it, e.g. a title, production state, and curator group.
*Model metadata is added at the top of the form.  From left to right, add the following metadata to your model:
====1.a Enter a '''title''' for your model====
Curation note: Currently, curators can add any text to create a meaningful title to their model, e.g. species, biological process, PMID, etc.  In the future, however, we may converge upon minimal standards for model naming.
====1.b Select a model state====
*By default, all models begin in a "Development" state.
*When ready, models may be moved to a "Production" state for publication by clicking on the grey downward-facing arrowhead, and selecting "Production" from the dropdown list.
*Development models will not be published on geneontology.org and resulting "conventional" annotations derived from development models are NOT included in the derived [http://wiki.geneontology.org/index.php/Noctua#GPAD GPAD] file.
 
====1.c If needed, change your annotation group====
*Some GO curators perform annotation for more than one group, e.g. if they are funded by more than one project.
*Annotation groups are associated with curators in the users metadata file described above.
*By default, the first group associated with your entry in the metadata file is the group listed in the form.
*If you belong to multiple groups, you can select the appropriate group for your current work by clicking on the grey downward-facing arrowhead, and selecting the appropriate group from the dropdown list..
 
===Step 2. Selecting a curation template===
*Currently, there are three different curation templates available in the Form: Default, BP only, and CC only.
*The Default template is used to create annotations when the curator is confident that the molecular activity (Molecular Function, MF) of the gene product is an integral part of a Biological Process (BP) and that the Cellular Component (CC) is the location in which the activity occurs.
*The Default template can also be used to annotate combinations of MF, BP, and CC, but the curator must always enter an MF annotation and understand that they are making explicit statements about the relationship between that activity and the BP and/or CC, i.e. the MF is an integral 'part of' the BP or the MF 'occurs in' the CC.  If you're not sure that this is the statement you want to make, you can use the BP only or CC only forms to make your annotations.
*To help guide curators in understanding the statement that they're making, relations between ontology terms are shown in the field where that term is added.
*The CC only template is used to make cellular component annotations for a gene product specifically when you do NOT want to make a statement about the gene product's activity in those locations.
*The BP only template is used to make biological process annotations when you wish to relate a gene product to a biological process but its activity is not an integral 'part of' that process, e.g. the gene product affects a biological process but the underlying mechanism for its action is not known. 
Curation note: When making annotations in the form, try to fill in as many fields as possible, by typing in the field, and then selecting from the autocomplete suggestions by moving the mouse over your selection and clicking on it.
Tip: In the autocomplete, enter a space after a complete word, to narrow down the choices.
 
===Step 3. Creating annotations using the Default template===
====3.a. Enter gene product or macromolecular complex to be annotated====
* By default, the form allows you to enter a single gene or gene product.
* To select the desired entity, start typing and then select the desired entity from the relevant matches returned.
Tip:
You can type in the gene symbol, e.g. Wnt3a or the unique identifier or accession, e.g. UniProtKB:P56704.  If necessary to narrow down the choices, type a space after the symbol, and enter the three letter code for the species (first letter from genus and two from species name, e.g. mmu for Mus musculus).  Each entry in the autocomplete will also show the associated unique database identifier or accession, so curators can confirm that they are selecting the appropriate entity for annotation.
 
====3.b. Enter the molecular function, evidence, and reference====
*For the default version of the form, these three fields are required. 
*If the Molecular Function is known, enter the appropriate GO term, evidence code, and reference (you can add multiple pieces of evidence by clicking on the "..." button to the right of the fields, and selecting "More evidence").
** Alternatively, you can select an existing annotation+evidence from the GO annotation database, by clicking on the "..." button to the right of the fields and choosing "Search database". With this option, you can select multiple annotations to the same term, which will add evidence from all selected annotations.
  Curation note: Wherever possible, curators should use a PMID as a reference, e.g. PMID:29802214.  If a PMID is not available, curators may use, in order of preference, a doi or an internal database paper identifier.  Curators may also use a reference from the [http://www.geneontology.org/cgi-bin/references.cgi GO Reference Collection].
 
====3.c. Enter other fields (optional)====
* For Molecular Function, the following "extensions" can optionally be added:
** has_input(molecule): fill in the "has input" field, evidence, and reference.
** happens_during(biological phase): fill in the "happens during" field, evidence, and reference.
* In addition, curators can add annotations to:
** Biological Process (the form assumes a part_of relation between the Molecular Function and Biological Process)
*** Existing annotations+evidence can be imported as described in 3.b. above for Molecular Function
*** Additional BP part_of "extensions" can be made to provide contextual information to the BP term.
** Cellular Component (the form assumes an occurs_in relation between the Molecular Function and Cellular Component)
*** Existing annotations+evidence can be imported as described in 3.b. above for Molecular Funct
*** Additional part_of "extensions" can be made to provide contextual information about cell and/or tissue type.
 
We recommend that you fill in as many fields as possible before creating the activity, as after it is created, you will need to edit it from the graph canvas, which requires more steps to do.
 
===Step 3. Add the new activity to a model===
*Press the SAVE button.  A new activity will appear on the graph canvas (the main window). 
Tips:
1. Each new activity will appear on the same part of the canvas, so if you add more than one activity you will need to move them around on the canvas (by clicking and dragging) to see the ones underneath.
2. If the SAVE button is grayed-out, there is some information missing from the form that you still need to fill in.  You can press the "why is the save button disabled?" for a list of missing fields.
 
== Continuing a model using the Noctua form ==
[[File:Clone evidence.png|thumb|Fig. 5 Cloning evidence.|500px]]
[[File:Select evidence.png|thumb|Fig. 6 Selecting existing evidence to clone.|500px]]
[[File:Add more new evidence.png|thumb|Fig. 7 Adding more new evidence.|500px]]
* Once you have added an activity to a model, you can continue to add information to that ''same'' model using the Noctua form.
* Just as for the first activity, add the new gene or gene product using the autocomplete menu.
* Add the corresponding Molecular Function for the entity you wish to annotate.
* At this point, it is helpful to know of some additional features of the Noctua form that can save time when adding to an existing model.
 
=== Adding more evidence ===
* Clicking on the circle icon at the far right of an annotation row will bring up a menu of options for adding information to your model (Figure 5).
* At the top of the list are the three options for adding more evidence.
** Clone evidence
*** To clone evidence, click on the 'Clone Evidence'  text.
*** A pop-up window will appear listing all of the evidence that is currently used for annotation in your model (Figure 6).
*** From the window, you may check one or more specific pieces of evidence to add to the new annotation you're making.
*** You may also use the box at the top of the list to add all of the existing evidence to the new annotation (although as models grow in size, it is unlikely that you'll want to do that).
*** Note that the Clone evidence functionality can be used to also add evidence from an existing annotation in the GO database if an annotation to the term selected already exists.
*** In this case, click on the 'ADD FROM EXTERNAL'  text and select one or more lines of existing evidence to add to the new annotation in your model.
** Add more evidence
*** To add more ''new'' evidence to an annotation, click on the circle icon at the far right of the annotation row and select 'More Evidence'.
*** A pop-up window will appear where you can click on the blue 'ADD' text and a new evidence row will appear where you can add additional pieces of new evidence for your assertion (Figure 7).
** Add ND reference
*** To add 'ND' evidence to a root node annotation, click on the circle icon at the far right of the annotation row and select 'Add ND Reference'.
*** The 'ND' evidence code and correct GO reference (GO_REF:0000015) will be added as evidence to your annotation.
*** Note that using the 'ND' evidence code in a GO-CAM model makes the same statement as for 'conventional' annotation: the curator has thoroughly reviewed the literature and there is no information known about the given aspect of GO for that gene or gene product.
  Tip:
  Although the form only shows the first piece of evidence added to a given annotation, if there are multiple pieces of evidence on an assertion, the total lines of evidence, and a link to all evidence, will be displayed above the evidence code box (Figure 8).
[[File:Multiple evidences.png|thumb|Fig. 8 Display of multiple evidences.|600px]]
 
== Starting a new model from ''within'' the Noctua form ==
[[File:Model options menu.png|thumb|Fig.  Starting a new model from within the Noctua form|600px]]
* If you are annotating using the Noctua form and wish to begin a new model, you can do so using the 'Model Options' dropdown menu.
  Tip:
  When you start a new model, the model ID in the URL in your browser will change. 
  This is a good way to check that you have definitely started a new model.
 
==Specifying the causal ordering of the activities==
Once you have created at least two activities, you can specify the causal relations between them.  This is done on the graph canvas, by dragging from the blue circle of the upstream activity box, onto the downstream activity box (Fig. 3).  You can then select the relation.  Relations that are “direct” mean that there is a physical interaction mediating the effect on the downstream activity.
[[File:Noctua_linking_activities.png|thumb|Fig.  Making causal relations between activities.|400px]]
===Choosing the right causal relation between activities (MFs)===
====Direct Relations====
*If the upstream activity regulates the downstream activity through direct binding or by covalent modification, use the [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002629 '''directly positively regulates'''] or [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002630 '''directly negatively regulates'''] relation. Examples:
**Receptor ligand activity [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002333 '''enabled by'''] Wnt1 [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002629 '''directly positively regulates'''] receptor activity [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002333 '''enabled by'''] Fzd1 (''Wnt1 binds to the Fzd1 receptor and activates it'').
**Protein kinase activity enabled by MAP3K1 [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002629 '''directly positively regulates'''] protein kinase activity [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002333 '''enabled by'''] MAP2K1 (''MAP3K1 phosphorylates MAP2K1 and activates it'')
*If an upstream activity creates a molecule that is acted upon by the downstream activity, use [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002413 '''directly provides input for'''] relation. Examples:
**Glucose-6-phosphate dehydrogenase activity of GAPDH [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002413 '''directly provides input for'''] for phosphofructokinase activity of PFK2 (''the small molecule output from the GAPDH activity is acted upon by PFK2 as the next step in the metabolism of glucose'').
**(X phosphorylates Y, creating a molecule that is then acted upon by Z)
 
====Activities mediated by small molecule concentration====
Small molecules can be substrates ('''inputs''') of activities, created by activities ('''outputs''') or modulators of activities ('''regulatory''').  In these cases, GO-CAM models make explicit nodes representing small molecule concentrations.  To add a small molecule to a model, use the "Add Individual" item on the left of the graph canvas.  These should have CHEBI identifiers.
* '''a small molecule in a metabolic pathway''':  in this case, connect the upstream activity (e.g. hexokinase activity) to its output (glucose-6-phosphate) using the [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002234 '''has_output'''] relation.  Then connect the small molecule to the downstream activity (e.g. phosphoglucose isomerase activity) using the [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002233 '''has_input'''] relation.
* '''regulation via a small molecule intermediate''': in this case the downstream activity must be a compound function, i.e. you will need to create '''TWO DISTINCT''' activities for the same gene product.  The first activity must be X binding, where X is the small molecule.  The second activity is the regulated activity.  Connect the upstream activity to the small molecule using [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002234 '''has_output'''], and the small molecule to the X binding activity using [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002233 '''has_input'''].  Then connect the first activity of the compound activity to the second one using a [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002629 '''directly positively regulates'''] or [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002630 '''directly negatively regulates'''] relation.
**ADCYA1 creates cAMP, which is an input to the cAMP binding function of PKCR1.  The cAMP binding function of PKCR1 then [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002630 '''directly negatively regulates'''] the protein kinase inhibitor activity of PKCR1.
**ADCHE1 breaks down acetylcholine, which directly binds to ACHR1 (acetylcholine binding) and activates its GPCR activity.
 
==== Activities mediated by an intervening biological process ====
*Similarly to mediation by small molecule concentration, the effects of some molecular activities on other activities are not strictly direct, but are mediated by a biological process.  Key examples are transcriptional regulation, regulation by ubiquitination and degradation, and regulation via membrane depolarization.
===== Transcription =====
*Where there is evidence that the transcription factor '''directly''' positively regulates transcription of the downstream gene, link its activity (e.g. DNA-binding transcription factor activity, RNA polymerase II-specific, (GO:0000981)) to the mediating process (e.g. positive regulation of transcription by RNA polymerase II (GO:0045944)) with [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FBFO_0000050 '''part of'''], and the mediating process (e.g. positive regulation of transcription by RNA polymerase II (GO:00045944)) to the downstream activity (the activity of the transcribed gene product) with [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002304 '''causally upstream of, positive effect'''].
*The equivalent model would be made if the transcription factor activity negatively regulates transcription by using the appropriate GO Biological Process term (e.g. negative regulation of transcription by RNA polymerase II (GO:0000122)) and the [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002305 "casually upstream of, negative effect"] relation between the transcription BP term and the activity of the downstream target.
*For direct transcriptional regulation, the target is added as a separate node and linked to both the activity (MF) and the transcriptional process (BP) using the [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002233 '''has input'''] relation.
*If it is not known if the transcriptional regulation is direct, the information may still be captured, but the target is not specified in the transcription factor MF nor in the regulation of transcription BP terms.
 
====Indirect and unknown causal mechanisms====
*If the mechanism of the causal relation is not known, use the more general [https://www.ebi.ac.uk/ols/ontologies/ro/properties?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_0002411 '''causally upstream of'''] relations (these can include a positive/negative effect, if known).
 
==Subfunctions: specifying more detail about molecular activities==
Sometimes, molecular activities are composed of distinct subfunctions, and those subfunctions may even be carried out in distinct locations, or by distinct subunits of a complex.  For example you may want to specify “hormone binding” in the “cytosol” as a subfunction of a nuclear receptor, that then activates (directly positively regulates) “transcription factor activity” in the “nucleus”.  To specify subfunctions, you will create new activities and link them to an activity that you have previously created that describes the overall function of the gene product (e.g. “nuclear receptor activity”).  Subfunctions (e.g. “hormone binding”) can be created using the Noctua form, but do not fill in the biological process field as it is the same as for the overall function.  Once the new activity is created, link it to the overall molecular function you created earlier, by dragging (on the graph canvas) from the subfunction activity (blue circle) to the overall activity, and selecting the “part of” relation.  You will then need to add evidence by clicking on the "part of" edge; a box will pop up; fill in the evidence fields and press the "Add" button.
 
==Editing a model==
Editing can currently be performed only on the graph canvas (the simple annoton editor form does not pick up any operations you have performed on the graph canvas).
Note that only one edit operation can be done at a time.  To change something on the canvas, you will need to first ADD the correct part, and then DELETE the incorrect part, as separate operations.  We recommend that you add first, so that you can transfer evidence from the incorrect part if necessary, by using the “clone other” operation.
===Editing relations===
Relations can be removed by dragging the end of the relation arrow away from the box it connects to, into an empty part of the canvas.  Relations can be added by clicking on the blue circle inside the upstream box, and dragging to the downstream box.  Evidence for a relation can be edited by clicking on the relation arrow.
===Editing the type/label on a graph node===
To edit a simple box on the graph (no colored bars indicating that it has multiple parts folded together for easy viewing), just click on the green square.  To change it, first add the new term by filling in the field under “add type”, and clicking add.  Then reopen the box again and delete the old term by clicking on the red “x” next to it.
===Editing types/labels that are inside a graph node===
* To edit properties of an activity that are “folded” into the molecular activity box on the canvas, click on the green box in the corner of a box.  Note that only one edit operation can be done at a time, so do not make more than one edit before pressing a button to save the edit.  To change part of the annoton, you will need to first ADD the corrected part, and then DELETE the incorrect part, as separate operations.
* To remove a property of the annoton, click the “x” next to it.
* To edit the evidence, click on the “E” next to the part for which you want to edit evidence (e.g., the “E” next to enabled by is the evidence that the molecular function is enabled by the gene product).
 
==Making "traditional" (single aspect) GO annotations using Noctua==
===Molecular function annotation===
* Use the "default" form
* Fill in the gene product field
* Fill in the molecular function field, including evidence
* Optionally, the following "extensions" can be added:
** has_input(molecule): fill in the "has input" field and evidence
** happens_during(biological phase): fill in the "happens during" field and evidence
** occurs_in(cellular component): fill in the "cellular component" field and evidence
** part_of(biological_process): fill in the "biological process" field and evidence
 
===Cellular component annotation===
This is for annotations of where a gene product has been observed (but is not known to be active). Note that these annotations have a different meaning than using the default form: the gene product has been observed in the CC, but may or may not be active there.
* Use the "CC only" version of the form (select by clicking on the drop-down on the right that says "DEFAULT").
* Fill in the gene product field.
* Fill in the cellular component field with the desired GO term, and evidence.
* * Optionally, one or both of the following "extensions" can be added:
** part_of (a larger cellular component)
** part_of (cell type)
** part_of (anatomy)
 
===Biological process annotation===
This is for annotations that assert a relationship to a BP other than part_of, e.g. for regulates or causally upstream of relations.
* Use the "BP only" version of the form (select by clicking on the drop-down on the right that says "DEFAULT").
* Fill in the gene product field.
* Choose the relation between the gene product and the BP.
* Fill in the biological process field with the desired GO term, and evidence.
* Optionally, one or both of the following "extensions" can be added:
** part_of (cell type)
** part_of (anatomy)
---------
 
==Naming your Model and Saving your Work Using the Graphical Editor==
 
While you create or edit your model, you will see an asterisk appear around the "Untitled" text in your browser tab. The asterisk indicates that your work is not yet saved, and the "Untitled" indicates that you have not yet named your model. To name your model and save your work, click on the drop-down menu under the Model heading and select the "Edit Annotations" option. In the "Title" section, add a title for your model. The beginning of the title will now appear in the browser tab. To save your work, click on the Model heading again and select the "Save" option. Your work is now saved and the asterisk in the tab will disappear. Save your work often while editing!
Tip:
If your model already has a name, you will need to delete the name first, before you can rename it.  Follow the same instructions above, but press the Delete button next to the name instead
---------
 
==How to Make a Model Public (Production)==
*By default, new models are considered under "development" meaning that curators may work on the model, but the model, and any GO annotations derived from it, are not available for public consumption
*This allows curators to work on a model over a period of time, perhaps review them with colleagues or experts in the field, and then publish them to the GO or other web sites.
*When ready, curators have the ability to explicitly change the production status of their model.
*To do this in the Noctua form, click on the 'Development' link at the top of the form.
**In the resulting Model Details window, click on the drop down arrow to the right of Development and select 'Production' from the list.
**Click 'Save' and close the Model Details window.
*To do this, in the graphical editor, click on the Model drop down menu and select "Edit annotations" from the list.
**Under the "Annotation state" section, delete the "Development" status.
**Return to the Model drop-down, select "Edit annotations" from the list and under "Annotation state" select "Production" from the drop-down list.
**Production - model will be available for viewing on the GO web site and annotation files available for consumption
 
==Noctua Output Files==
===GPAD===
===OWL===
 
== FAQs ==
=== [[GO-CAM and Noctua FAQs]] ===


==Providing Feedback==
*Bug reports and requests for new features should be entered on the [https://github.com/geneontology/noctua/issues GO's Noctua issue tracker on GitHub].
*Before entering a new ticket, please be sure to search the tracker to see if the bug or feature request has not already been reported!


[[Category: Annotation]]
[[Category: Annotation]]

Revision as of 08:22, 5 October 2022

GO-CAMs and Noctua

  • This documentation is presented in two parts:
    • GO-CAM Principles
    • Noctua Curation Tool

GO-CAM Principles

Standard GO Annotations and GO-CAM Models

Standard GO Annotations

GO annotations have been a key component of GO since its inception. Standard annotations are defined as an association between a gene and a biological concept from one of the three GO aspects: Molecular Function (MF), Biological Process (BP), and Cellular Component (CC). Standard annotations always contain a reference (either a published, peer-reviewed paper or internal GO reference) and an evidence code that indicates the type of experiment or method used to make the assertion. Standard GO annotations may further be qualified using annotation extensions that provide additional biological context to a GO term using a relation from the Relations Ontology (RO) and a term from GO or an external ontology, e.g. UBERON.

GO-CAM Models

While standard GO annotations are very useful for discerning basic information about genes, they provide only a partial view of each gene's role in a larger biological context. To provide more comprehensive annotation of genes and link their activities in a causal framework, the GO developed GO-CAMs. Using RO relations, GO-CAMs link GO annotations together with biological entities and external ontology terms to model how a gene functions in the broader context of a biological process or pathway. GO-CAMS thus provide structured descriptions of biological systems and allow for interrogation of causal events in biology through use of clearly defined, and consistently applied, semantics.

A summary of the GO-CAM model specifications is presented in Figure 1.

Figure 1. GO-CAM Model Specifications

The basic unit of a GO-CAM model is the Activity Unit, outlined on the left, which represents a set of standard GO annotations with select annotation extensions, e.g. the inputs and outputs of a molecular function. GO-CAM models are constructed by filling in as many pieces of relevant information in an Activity Unit as possible and then linking different Activity Units in a causal chain to model a biological process. Thus, GO-CAM models use standard GO annotations as the foundation on which to build more comprehensive representations of biology.

Use of GO in GO-CAMs

Molecular Activities in GO-CAMs

  • Wherever possible, curators should strive to select the single most granular GO Molecular Function (MF) term that best describes the overall activity of the gene, gene product, or protein-containing complex being annotated.
  • If desired, individual "sub-functions" may be captured by using the 'part of' relation between the main MF and its sub-functions.

Biological Processes in GO-CAMs

  • The ultimate aim of GO-CAMs is to create a suite of Biological Process (BP)-centric models that can be used to interrogate causal effects of molecular activities on one another as part of the execution of a larger BP.
  • When annotating, curators should always think about the BP they are modeling and what MFs are 'part of' that BP.
  • Additional relations between MFs and BPs, e.g. 'causally upstream of or within', can be used to capture experimental information that, in the future, will be incorporated into a more complete model of that process.

Cellular Components in GO-CAMs

  • Cellular component annotations are intended to capture where the MF enabled by a gene, gene product, or protein-containing complex occurs.
  • Cellular component annotations may be further qualified with cell, tissue, and organismal context if that information is germane to the process being modeled.

Noctua: the Gene Ontology's GO-CAM Annotation Tool

Noctua is a web-based, collaborative Gene Ontology (GO) annotation tool developed by the GO Consortium. Noctua can be used to create standard GO annotations as well as more expressive models of biological processes, known as GO-CAMs (Gene Ontology Causal Activity Models). There are two types of user interface available in Noctua: 1) a form interface and 2) a graph interface.

System Requirements

Noctua is a web-based annotation tool and thus requires only a web browser to access and use.

We have tested Noctua primarily with Chrome on a Mac operating system.

Issues that arise using other browsers and operating systems may be reported on go-helpdesk

User Account Setup

GO-CAMs can be browsed using Noctua, but no annotations can be created or edited unless a user has a registered account.

To create a new account, please email help@geneontology.org or enter a ticket on the helpdesk repo in github.

Note that to create a Noctua account, you will need an ORCID and a github account.

Please allow 24 hours for your account to be created.

If you have any questions about user accounts, please contact help@geneontology.org

Entities and Ontologies for Annotation

Entities for Annotation

Genes and Gene Products

  • The primary nodes in a GO-CAM model are the ACTIVITIES (Molecular Functions (MFs)) of genes, gene products, or protein-containing complexes.
  • Every gene, gene product, and protein-containing complex annotated in GO-CAMs must be associated with a stable database identifier and represented either in a GPI (Gene Production Information) file (preferred), in an existing annotation file, e.g. a GAF (Gene Association File), or in the GO Cellular Component aspect.
  • Curators should strive to annotate activities (MFs) to individual genes or gene products wherever possible.

Protein-Containing Complexes

  • In GO-CAMs, curators should always try to assign each member of a protein-containing complex its specific activity (e.g. regulatory activity vs catalytic activity).
  • However, if the main activity of the protein-containing complex cannot be ascribed to a single subunit of the complex (e.g. RNA polymerase II activity), then the activity should be enabled by an appropriate protein-containing complex (e.g. a GO protein-containing complex), with each gene or gene product associated with that protein-containing complex with a 'part of' relation.
  • Requests to add new entity identifiers to Noctua should be directed to help@geneontology.org

Ontologies for Annotation

Gene Ontology

  • The GO is used to annotate:
    • Molecular Activities (MF)
    • Biological Processes (BP)
    • Cellular Component (CC)


  • To provide appropriate biological context to an annotation or an activity unit, additional ontologies may be used either in GO-CAM or in annotation extensions [link].

Cell and Anatomy Ontologies

  • Describes the location where processes and functions occur.
  • Describes the location of a GO cellular component.
  • Add list

Biological Phase and Life Stage Ontologies

  • Describes the temporal period during which processes and functions occur.
  • Describes the temporal period during which a cellular component or anatomical entity exists.
  • Add list

Chemical Ontology (ChEBI) [link]

  • Can be used to capture inputs and outputs of processes and functions.
  • GO-CAM uses the Chemical Entities of Biological Interest (ChEBI)
  • Sequence Ontology [link]

Requests to add ontologies to Noctua should be sent to help@geneontology.org

GO-CAM Workflow

  • The ultimate goal for GO-CAMs is to create a knowledge graph whereby users can use the GO to traverse a causal representation of a biological system.
  • To that end, curators should try, as much as possible, to make individual annotations in the context of the overall process being modeled.
  • It can be very helpful to refer to a summary figure from a recent research article or review to help visualize a potential GO-CAM.
  • When making a GO-CAM model, we suggesting these steps:
    • What are the main activities (MFs) of each of the gene products in a model?
    • How do those activities relate, in a causal chain, to each other?
    • What processes are those activities involved in?
    • Where do the activities occur?
  • Even when annotating a single paper, try to incorporate as much of this workflow as possible. This will make it easier, in the future, to build on existing models with new curation.

Noctua Users Manual

Noctua Landing Page

  • The Noctua landing page is the portal by which curators can browse or search and filter models.
  • It is also the starting point for curation (when logged in) and where individual GPAD and OWL files for a model can be downloaded.
  • By default, the Noctua landing page displays models by date, descending order, i.e. the most recently edited models are shown at the top of the list.


Noctua Landing Page


Filtering Models

  • There are two ways to filter GO-CAMs on the landing page:
  1. Click on the magnifying glass icon in the upper left
  2. Click on the metadata icons to the right of the model title in the table.


Filtering Options


Filtering with the Magnifying Glass

Clicking on the magnifying glass opens up the menu of available filter options:

  1. Ontology term (autocomplete)
  2. Gene product (autocomplete)
  3. Reference
    1. If entered as free-text, must be the full reference id, e.g. PMID:31884020 or doi:10.1016/j.ydbio.2019.12.010
    2. Can also use the drop-down prefix menu (and PMID look-up feature) by clicking on the =+ icon.
    3. Must press return after entering search string.
  4. Organism (drop-down list)
  5. Contributor (autocomplete and drop-down list)
  6. Groups (autocomplete and drop-down list)
  7. Exact date (enter YYYY-MM-DD/return or calendar, select/return)
  8. Date range (enter YYYY-MM-DD/return or calendar, select/return)
  9. Title (enter/return)
  10. State (drop-down list)
Filtering Options

Noctua Form and Graph Editors

Noctua has three curation interfaces: 1) the Noctua Visual Editor, 2) the Noctua Form and 3) the Noctua Graph Editor.

  • The Noctua Visual Editor (VPE) is designed for curating GO-CAM models, i.e. models that include at least two activities/MFs linked by causal relations.
  • The Noctua Form is a structured annotation form that is recommended for creating 'standard' GO annotations.
  • The Noctua Graph Editor is best suited for linking standard annotations together to create a causal model (GO-CAM).


Noctua Users Manual
Getting started Browsing and searching annotations and models
Login
Creating standard GO annotations
Form Editor Molecular Function
Biological Process
Cellular Component
Graph Editor Molecular Function
Biological Process
Cellular Component
Adding contextual information (annotation extensions)
Form Editor Molecular Function
Biological Process
Cellular Component
Graph Editor Molecular Function
Biological Process
Cellular Component
Editing annotations
Form Editor
Graph Editor
Creating GO-CAMs
Creating an activity unit Form Editor
Graph Editor
Linking Activities Form Editor
Graph Editor
Model metadata
Model titles General Guidelines
Form Editor
Graph Editor
Releasing models to production Form Editor Form Editor]
Graph Editor
Other tips and tricks Adding a NOT qualifier to an annotation
Importing existing annotations
Changing annotation group
Model validation
Running the reasoner
Viewing GPAD export]
Using templates

Noctua Annotation Review

Documentation on how to use the Noctua Annotation Review workbench is here.

Model Copy

  • Noctua has a model copy functionality that allows users to copy an entire model, minus the evidence.
  • Model copy can help curators make efficient use of existing models to create new content.
  • More details on model copy and how to use it can be found here.

Noctua Maintenance

  • The Noctua curation tool undergoes routine maintenance on the second and fourth Thursdays of each month from ~4pm - 7pm PDT.
  • During these maintenance outages the following tasks are typically performed:
    • Ontology updates:
      • incorporate the latest versions of all ontologies used in Noctua, including NEO (Noctua Entity Ontology)
    • Model updates:
      • replace obsolete ontology terms if there is a 'replaced by' value
      • replace ontology terms if usage has changed
      • delete any models marked with state 'delete'
    • Software updates:
      • Incorporate bug fixes
      • Add new features
  • Noctua maintenance outage reminders are sent out on the go-consortium mailing list ~24 hrs. prior to the outage.
  • For each outage, a list of specific tasks is enumerated in a ticket on the noctua github repo.