This guide is intended for new GO curators. It carries on from the GO Curation For Beginners , and leads you through the steps that must be taken to address a single Sourceforge request.

First you must claim a request on the SourceForge request page:

The GO SourceForge curator request tracker is a web page showing a list of the requests for changes to the ontologies that have been made. To claim a request you should log in and click on the summary hyperlink part of the request line. Then change the 'Group' menu to 'GO', and the 'assigned to' menu to your own initials. Press 'submit changes' to update the web page and then have a think about what you will do to fulfill the requirements of the request you have claimed e.g. add terms as requested. If you want to find out how to word a definition or term name then look at the Curators' Guide to GO Style

Editing the GO files using DAG-Edit

Before you start, you need to download the current version of the GO flatfiles. Make sure you are in the directory of your computer that contains the directory called 'go'. Log in to CVS using the command:

  cvs login

It'll ask you for your password (which you should have got from Mark Schroeder) Then to update the copies of the ontology and definitions files on your computer type the command:

 
  cvs update

If you are in a different directory you can type the same command followed by the pathname to produce the same effect. To update only a subset of the files you can type a more specific pathname, for example:

   cvs update go/ontology/

Next you should give the command

cpgo

to copy all three ontologies and the defs into the directories called 'old' that you have created in your 'doc' and 'ontology' directories. Once this is complete you can load the files into DAG-Edit.

DAG-Edit

To make the changes suggested in the SourceForge request you must open DAG_Edit and load the terms. In the 'file' menu, choose 'Load terms' and browse to find the correct files. Once you have filled in all the pathnames you can give the whole set a name so that it will be retained for use each time you need to load the updated set of terms. Wait while the updated files are opened in DAG-Edit. If the SourceForge request suggested a parent for the new term that is required then you can search for that parent by typing in the 'find' window in the top right of the DAG-Edit display. The parent term will be highlighted in the DAG Viewer on the right, and then if you hold 'Option' and click the term then it will also be highlighted in the window on the left. (Bear in mind that if you search both the terms and the synonyms with a particular word, then only the term will be displayed in the find results, even if the word was found in the synonym of that term.)

Term request checklist.

Once you've claimed a request from SourceForge:

Make sure it isn't there already as the same or a similar string.
Think about the wording - does it fit with that of similar terms?
Make sure it should be there (i.e. is the requested term really a process, a component or a molecular function? Is it already adequately described by something else?)
Decide which ontology it should be in (see the GO usage guide at GO.usage.html for more details).
Check that the requested position of the term is the best position for that term; look for similar terms and work out whether it would be better to include the requested term at a higher or lower level in the DAG.
When you've added a new term, does it need any other parents in addition to the ones requested?
If a definition is suggested, does it make sense and could it be more concise? If no definition is included in the request, write one. Never add a term without adding a definition.
If you're making an old term obsolete, add a comment that explains why the term has been made obsolete and suggest alternative terms that could be used for annotation (see Syntax for comments).

If you would like to discuss your plans with the others on the mailing list then it is useful to lay out your suggested structure in a way that is clear to everyone. On possible way is as below:

  %term name ; GO:nnnnnn 
    %term name ; GO:nnnnnn 
      <term name ; GO:nnnnnn 
      <term name ; GO:new

In this system the '%': character indicates an is_a relationship, whilst the < character indicates a part_of relationship.

Add and commit terms

If you are happy with the suggested new terms in the SourceForge request then you can add them. To do this, click the parent term, to which the new terms will be added and then choose 'Edit->Add Term'. In the ID box you can type the name of the new term, then add the definition in the 'Definition' box and 'GO:[your initials] in the adjacent 'Dbxrefs' box. Once you are happy that this has been done right, click commit.

Record your changes

At various stages you will have to write a log of the changes that you have made, so to save typing, this is a good time to cut and paste all your changes into a simple text programme like 'TextEdit'. Open a new text file, and write the names of the terms you have added, their GO ID numbers, and the name and ID of the parent to which you added the term. Keep this file handy.

Editing large chunks of an ontology

If your editing is going to take some time, beware that committing your work to the repository could be problematic because if you checked out a version of the files that is now several versions out of date, committing your changes can cause CVS conflicts that may be complicated and time consuming to resolve. It's therefore best to plan out what you're going to do first, and then make your changes. Finally, remember that editing GO is a team effort; if you're about to edit something that someone else might be working on or that might affect existing annotations, send e-mail around to GO.

Saving your edited files

Once you've finished working on a section of an ontology, and someone has checked what you've done, save it straight to your working directory (i.e. ontology files to 'ontology' directory and GO.defs to 'doc' directory. You need to do this so that you can compare versions - a safety check to make sure that, while editing the files, you haven't unintentionally done something strange. You can set the path for your temporary files in DAG-Edit at the bottom of the screen. For example:

   Users/yourname/Documents/go/ontology

Also set the path for the definitions file:

   Users/yourname/Documents/go/doc

You'll only have to set these paths once. When set, save the files by ticking the 'Use legacy compatible types' box, and then clicking the 'Save GO flat files' button at the bottom of the DAG-Edit screen.

Committing files to the CVS repository

Once you've finished working, you can commit your revisions to the repository at Stanford. Before you do this, check that you've done what you think you've done by comparing the edited version with your previous version. Note that for the following commands you can use UNIX aliases, such as those suggested in the Beginners' Guide to Modifying the Ontologies. First you must compare your modified files with the unmodified files to check the changes that have been made are the ones you are expecting. If you've just edited the process ontology, for example, compare your tempfile with the previous version by typing

 
   diff go/ontology/process.ontology go/ontology/old/process.ontology (alias: dp)

If you have modified any of the other files then you should also check those individually by using the relevant command:

   diff go/ontology/function.ontology go/ontology/old/function.ontology (alias: df)
   diff go/ontology/component.ontology go/ontology/old/component.ontology (alias: dc)

If you've edited any definitions, you should also compare the GO.defs files:

   diff go/doc/GO.defs go/doc/old/GO.defs (alias: dd)

At this stage you can also open the modified files in emacs to check for extra spaces and newline characters. To search for newlines type:

   ctrl-s \n RET

Delete any newline characters and then repeat the search for extra spaces:

   ctrl-s [press space bar twice] RET

Once you're happy that the files have been changed in exactly the way that you expected them to have changed, (get someone to check the first few times) check them against the current versions in the cvs repository:

To do this you need to use the following aliases which give the commands shown in inverted commas after them:

To check the component ontology file against the current version in the cvs repository

 dcvsc 'cvs -d :pserver:jenclark@gocvs.geneontology.org:/share/go/cvs diff go/ontology/component.ontology | more'

To check the function ontology file against the current version in the cvs repository

alias dcvsf 'cvs -d :pserver:jenclark@gocvs.geneontology.org:/share/go/cvs diff go/ontology/function.ontology | more'

To check the process ontology file against the current version in the cvs repository

alias dcvsp 'cvs -d :pserver:jenclark@gocvs.geneontology.org:/share/go/cvs diff go/ontology/process.ontology | more'

To check the definition file against the current version in the cvs repository

alias dcvsd 'cvs -d :pserver:jenclark@gocvs.geneontology.org:/share/go/cvs diff go/doc/GO.defs | more'

When you do this you will probably see just the changes that you have made, but if someone else has also commited changes since you last updated then you will see those too. If you see changes that you did not make then you will have to carry out

cvs update

again to merge the current cvs version with your working files. You can also update the individual files separately:

   cvs update [pathname]

for example:

   cvs update go/ontology/process.ontology (alias: upp)
   cvs update go/ontology/component.ontology (alias: upc)
   cvs update go/ontology/function.ontology (alias: upf)
   cvs update go/doc/GO.defs (alias: upd)

   cvs update  [updates all files]

This will check your version of the file in your working directory against the version in CVS and tell you if someone else has changed the same parts as you have changed. If only two different parts have been changed then the files will be merged to include both sets of changes. Ask someone to watch for any error reports, e.g. spaces that you have left where they should not be. A capital 'M' will show if all is well, and a capital 'C' if there are problems. You can then commit your changes to the CVS repository in Stanford:

   cvs ci go/ontology/process.ontology  (alias: cvsp)
   cvs ci go/ontology/component.ontology  (alias: cvsc)
   cvs ci go/ontology/function.ontology (alias: cvsf)

If you've edited the definitions file, type

   cvs ci go/doc/GO.defs (alias: cvsd)

After you have committed a file, an emacs window will pop up prompting you to add a comment on how you've changed the files. Type what you've done (this can be pasted from the history plugin in DAG-Edit or from the Text Edit file you made earlier). You should also include the reasoning behind your decisions. Then type ctrl-x ctrl-s to save the CVS log file, and then ctrl-x ctrl-c to exit it.

After you have committed a file, check each of the relevant log files to make sure that the right number of lines has been edited (As before, only check the biological process, molecular function and cellular compnent ontology files if you have worked on them, and only check the definitions file if you have altered or added any definitions.)

   cvs log go/ontology/process.ontology | more  (alias: logp)
   cvs log go/ontology/function.ontology | more  (alias: logf)
   cvs log go/ontology/component.ontology | more (alias: logc)

'| more' sends the log's contents through the UNIX 'more' utility, which allows you to view it a page at a time. Press 'q' to quit.

----------

*This is a technical bit where it is better to ask for help*

Ask someone to check the log file, and look out for characteristics shown in this explanation of what is going on:

The top of the log file will say something like (on a single line):

    revision 2.480 date: 2002/07/15 21:51:02;  author: berardini;
     state: Exp;  lines: +1018 -262

The difference between +1018 and -262 is the number of lines that have been edited. If, for example, you had edited only a couple of terms and you got these numbers, you'd know that something had gone awry. If this is the case and you can't work out what has caused the differences, the safest thing to do is restore the previous version. If the current version is 2.480, the following command to checkout version 2.479:

   cvs co -p -r 2.479 go/ontology/process.ontology > old_process

The -p -r command checks out the file without sticky tags, which cause strange things to happen to the file. '>old_process' just saves version 2.479 as a file called old_process. Once you've checked out the old version, use it to overwrite your working version:

   cp old_process go/ontology/process.ontology

You can now commit the old version as usual.

--------------------

*Back to easy stuff again now*

The GO numbers file

Every time you add a new term to the ontology you also create a record of what it is in the GO numbers file. To open this file in emacs type

   emacs go/numbers/go_numbers (alias: en)

You can add each new GO term as you work or paste the final set of information from your TextEdit file.

You must also commit the numbers file to CVS by typing:

   cvs ci /go/numbers/go_numbers (alias: cvsn)

Synonyms

If you have added synonyms then you must also update the synonym file.

Logging out of CVS

Type:

   cvs logout

What to do when your files won't commit

If someone else has committed files in between your last CVS update and your attempt to commit your updated files, the following message will appear in your terminal window:

   CVS server: Up-to-date check failed for `go/ontology/process.ontology'
   CVS [server aborted]: correct above errors first!
   CVS commit: saving log message in /tmp/CVS000388

When this occurs, you need to merge the latest version in the repository with your working file. First, perform the CVS update command on the relevant file, to merge your working version with the current version in the repository. At this point you might get the following message:

   RCS file: /share/go/CVS/go/doc/GO.defs,v
   retrieving revision 2.646
   retrieving revision 2.650
   Merging differences between 2.646 and 2.650 into GO.defs 
   rcsmerge: warning: conflicts during merge
   cvs server: conflicts found in go/ontology/process.ontology
   C go/ontology/process.ontology

You need to correct the conflicts before committing your working version. Open the working version (not the temp version) of whichever file has failed to commit and use the ctrl-s command to search for the following text strings:

   >>> <<< ====

These characters appear when the same part of the file has been edited in both versions; <<< and >>> bracket the part that's been edited, and ==== underlines the part where there are conflicts. The most common type of conflict is in the header and in this case you need to decide which form of the header to keep, and then delete the other form and all of the conflict characters. If you find conflict characters within a new term then find its associated GO-ID and search for other instances of it (usually they're next to each other). Once you've found two or more terms with the same ID, you'll have to decide which one is correct and delete the other one (ctrl-k allows you to delete a line at a time). When you've deleted all the conflicts, save it, close it, and commit your edited working version.

After you have committed the file, check the log file, as described above, to make sure that the right number of lines has been edited. Occasionally, when you try to commit files you'll get the message

   Waiting to obtain lock.

This means that someone else is committing a file. You simply have to leave this running in the background until the other person has finished committing his/her file.

To close the request in SourceForge

Once you've completed a request, fill in the 'comment' field with text explaining how you've completed the request and the reasoning behind why you did it that way.
If you have added terms, you can paste their GO-Ids in from the GO_numbers file or your TextEdit file.
Change 'status' to closed in the pull-down menu.
Change 'resolution' to an appropriate term.
Click on the 'submit changes' button.

An e-mail will now be sent to the person who logged the request and to you, containing the contents of the comments field.

If you are learning to curate using this web page and you find out things that you think should be included then you can contribute to it by e-mailing the webmaster. Until all these helpful nuggets of advice have been put together in coherent form they will be stored in 'random accumulated helpful advice for curators'.



last modified October-2003	Report problems with this website to webmaster@geneontology.org


	For problems with Netscape 4, please upgrade to Netscape 7