Content Meeting Documentation
If a content meeting is being held and you are responsible for the ontology file there are a number of things you can do to ensure safe and successful editing. They are described in detail below.
Make a New Wiki Page
1) Make a new planning page on the GO wiki that will hold information about only this content meeting.
This page can be made ready to hold information about:
Meeting locations and dates, attendees, topics lists of review papers to be used
But what that you really need for your job is a place for:
Meeting Minutes sub-headings: • General Goals • Rules, rationales, clever ideas • Potential top level term changes • General notes from the discussions • Proposed Ontology changes (some implemented in the working draft) including new terms merged terms redefined terms obsoleted terms (These details can be determined using the obodiff script in OBO-Edit.) • Open Questions • Overview • Post-meeting to-do list with deadlines. • Milestones Reached (to be filled in after the meeting) File editor's notes sub-headings: • Name of responsible editor • GO-id ranges used1 • Details of file handling Initial live file checkout version and date (initial branch)2 Name of checked in working file in go/scratch3 Versions and dates of any subsequent merges between branch and live file.4 Method of merge + notes of any issues.5
The different topics can be linked from the main page for the meeting so that it doesn't get cluttered.
The usual system for a content meeting is that several people will take a handful of reviews each and develop terms from them. In the meeting the terms will be shown to experts for discussion and edited further before commit.
This means that several people may be editing for some time in advance of the meeting and you need to ensure there is good file versioning control and that new term GO-ids are properly controlled.
Follow these steps:
Find out the names and contact details (Preferable VoIP) of the editors and find out how much experience they have of editing and whether they have GO cvs write access.
1) Make them each a number range, and make one for your own editing at the content meeting. Immediately note these on the file editor's notes page of the wiki that you made earlier *and* in the go/numbers/go_numbers file. Put each person's initials at the beginning of the ids, so if you are giving someone the range GO:0080000 to GO:0080200 then give it as JIC:0080000 to JIC:0080200 or whatever. This will allow you to keep track and to easily render their terms in a different colour in OBO-Edit.
Get the file ready to start editing.
2) Check out a copy of the the live file (gene_ontology_edit.obo) Carefully note the version number and date on the file editor's notes page.
3) Check the file into the go/scratch directory under a new and meaningful name e.g. IsaComplete.obo.
4) Later as the work progresses you will want to merge the working file with the live file. Note the version numbers and dates of the two pre-merge files and the one post-merge file each time you do this.
5) Keep a careful note of the details of the merge method and any issues you encounter.
6) Make sure all files committed to GO CVS, including those in the go/scratch/ directory, have unix line endings.
Pre- and Post- Meeting Editing practice
If you have several editors editing the same file in parallel then you must control the versioning very closely.
If any of your editors doesn't have cvs write access then you must impress on them the importance of checking in often. Ask them to send their file to you at the end of every day in which they carry out any editing. Explain to them that if they do not do this their work may be lost. As soon as they send you a file, quickly merge by cvs, check in and then check out and send them the new file so that they do not lose time.
Editing During the Meeting.
During the meeting you will be reviewing the terms that the editors have made and adjusting them in response to the expert's comments. Make sure that you have a good understanding with the chair of the meeting on what is going to happen as you cannot chair and edit at the same time.
Set up your computer so that your copy of OBO-Edit shows on the overhead projector screen. Make sure that you have loaded the most recent copy of the file.
Set up a global render so that the new terms will show in different colours. Make sure that these colours able to be distinguished by colour-blind people, and that the OBO-Edit text is large enough to be read from the back of the room.
Practise touch-typing in advance as this will help a lot on the day.
Ask the meeting organiser to get someone good to take minutes and give them the list of headings from the minutes wiki page above. It is not necessary to get the whole discussion verbatim. It is more useful if the chairperson can summarise as they go along and make sure that the minute-taker understands. Periodically check to see that the minute taker is still remembering to take minutes and rotate the task if they are flagging. Be especially sure to check that they are getting all action items and ask the chairperson to repeat any difficult terminology until they are happy that they have it correct.
Save the OBO-Edit file regularly and open the file in a text editor to check that that the save worked before you close the application. At the end, reload the file into a copy of OBO-Edit on another computer before you close your copy, to be sure that you can do it.
Commit to cvs regularly as a backup, and to ensure good version control.
During the meeting everyone will point to terms on the screen and talk at once. You will need a good chairperson to follow what they are saying and relay the information to you as it is impossible to follow it all and type at the same time.
Make the File Live
Once you have finished the most important action items from the meeting, post the gocvsweb address of the file to the GO list and to the expert list so everyone can look at it. Include the complete list of changes extracted from the obodiff script and the list of general intentions and changes edited from the minutes.
Include information on how to render the terms so they are higlighted in different colours. Some of your experts will be novice OBO-Edit users.
Make any changes that are agreed.
Next change the GO:ids from JIC:0004637 or whatever back to GO:0004637 by a search and replace and recommit to scratch.
Write to the list to announce the time of the commit, and ask for a brief freeze. Just before the commit write with a reminder. Commit carefully and if you see any problems call it off and try another time. When the commit is done write to say the freeze is over.
After you have committed the terms start on the is_a completeness of the graph. Give a tab-delimited file of non-is_a complete terms to the editors and ask them to fill in the is_a parent terms. Have a conference call to discuss any problems. Send the file to Amelia so she can use her script to fill in the relationships. She will commit the improved file.