Claiming a SourceForge item

The GO curator requests tracker is a web page showing a list of the requests for changes to the ontologies that have been made. To claim a request, 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 SourceForge ID. Click '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. To find out how to word a definition or term name, look at the GO Editorial Style Guide

Back to top

Checking the history of a term

There may be discussion of a given term in the GO e-mail archive and it can be useful to search the archive for pertinent e-mails. You can use the search facility on the website; see the GO mailing list information for more information or to perform a search.

Back to top

Editing the GO file using OBO-Edit

Before you start, you need to have downloaded the current version of the GO flat file as described in The Beginner's Guide to Modifying the Ontologies. Go to the go directory and make sure that your copy is fully up to date by typing

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 path name. For example, to update the ontology files, type:

Next you should give the command

to copy the ontology file into the directory called old that you have created in your ontology directory. Once this is complete you can load the file into OBO-Edit.

Back to top

OBO-Edit

OBO-Edit includes a very comprehensive user guide, and if you have any trouble using OBO-Edit, you can consult the guide. To open it, select 'User Guide' from the 'Help' menu.

Back to top

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:

In this system [i] indicates an is_a relationship and [p] indicates a part_of relationship.

Back to top

Adding Terms

If you are happy with the suggested new terms in the SourceForge request, you can add them to the ontology. The editorial style guide provides thorough documentation on all aspects of GO terms.

Back to top

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 (Mac) or NotePad (Windows). 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. You can also use the OBO-Edit History plugin to save a text file of all your changes. At the end you can edit this file to be succinct and clear, and use the contents as a log file.

Back to top

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.

Back to top

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 directory). You can set the path to the saved file in OBO-Edit at the bottom of the screen; an example might be Users/[yourname]/Documents/go/ontology.

Back to top

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 UNIX aliases shown are those suggested in the example .tcshrc file shown 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. Move to the Documents directory. Compare your unedited file with the edited version by typing

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

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

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:

When you do this you will probably see only the changes that you have made, but if someone else has also committed changes since you updated your files, they will also appear in the diff. If you see changes that you did not make, you will have to update again to merge the current cvs version with your working files. To update your copy of the ontology file, use the command

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:

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 edit or TextEdit 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 the log file to make sure that the right number of lines has been edited.

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

*Back to easy stuff again now*

Back to top

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

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:

Back to top

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:

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:

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. Conflicts appear between the markers <<<<<< and >>>>>>, with ====== separating the changes that you have made (above) from the version in the repository (below). The number next to the >>>>>>> refers to the version number of the file in the repository.

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 version and all of the conflict markers. If you find conflict markers within a term, you will need to decide which of the changes should be incorporated and which should be removed, and delete lines accordingly. If two new terms with the same ID have been added, more care is needed as all instances of the ID will need to be found and altered. In these situations, it may be better to remove the two terms and add them afresh in OBO-Edit.

Once you have removed all the conflicts and associated conflict markers, do a diff against the repository version to check that the edits that you intend to commit are in the file.

If all is well, commit your file as usual. 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

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.

Back to top

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.

Back to top

In the event of a catastrophe - Reverting files

Sometimes people make a mistake and commit a file to cvs that is badly messed up. It may be broken in such a way that it will not load into OBO-Edit, or into the web browsers. Or perhaps an entire ontology has been accidentally deleted or replaced with a copy of the phone book. It's best to avoid doing this in the first place, and generally that involves being careful to the point of paranoia, and asking billions of questions. However, if it's already too late for that, here's what to do.

Find out the revision number (e.g. 'revision 3.258' below) of the file prior to that in which the error was made by typing:

The file will look like this:

In the case above perhaps revision 3.259 contained a serious flaw, but revision 3.258 was fine. In this case you should do the following:

Check out the version of the file before the one that is messed up (in this case version 3.258).

Save it into a different directory from that in which the working copy would normally reside (e.g. the desktop)
Check out the most recent version of the file, using the same construction of command with a different revision number and new filename (in this case version 3.259).
Overwrite this most up to date file with the non-broken file and then commit this file.

You may use the command

to get the files from a whole directory from a particular date (where 2004-09-08 is an example of a date.)

If you are not sure which revision caused the problem it is also possible to work your way back one at a time until you find the last revision of the file that worked. It is important to notify any people whose changes you may have wiped out during this process, and it is also useful to mail the list if you have found a problem so people are not committing new versions while you are trying to revert.

Back to top

Avoiding redundant parentage

When you are adding new terms to the ontology you will have to add all the relevant parentages as well. However some parentages that might seem sensible are actually redundant because the term already indirectly has that parentage. Some examples are shown in the figure below.

If you are learning to curate using this web page and you find out things that you think should be included, you can contribute to it by e-mailing jclark@ebi.ac.uk (Jennifer Clark).

Back to top