Phenote User Guide

This guide covers the use of Phenote specifically for the Phenoscape configuration. Some more general documentation can also be found at the Phenote website.

System requirements

Phenote runs on most modern platforms, but requires Java 1.5 (aka Java 5) or later. An appropriate Java is included with Mac OS X 10.4 or newer (Phenote cannot run on Mac OS X 10.3). For Windows, you can download the latest Java from http://www.java.com/. If you're running Linux, please consult your system documentation for how to get Java.

Installation

Download

Phenote can be downloaded from the OBO Sourceforge project site. There are separate downloads available for Mac and Windows, as well as a download of the application source code. Download the appropriate zip file for your platform.

• Mac: Double-click the downloaded file to unzip it. You should see the application, "Phenote.app". Drag it anywhere you like to install. Double-click the application to launch Phenote.
• Windows: Double-click the downloaded file. Click on "Extract all files" in the resulting window. Use the Extraction Wizard to put the Phenote folder wherever you want. Launch Phenote by double-clicking "Phenote.bat" inside the Phenote folder. It will take several seconds for the Phenote window to appear. Do not attempt to run Phenote from "inside" the zip file - it will not work properly without first extracting the files to another folder.
• Linux/Unix: forthcoming

First run

The first time you launch Phenote you will be presented with a window from which you can choose a configuration. Select "phenoscape" and press OK. This window can be accessed any time via the Settings > Set Configuration... menu item. You will also likely be presented with the ontology update window. Choose "Update All" and continue. Once Phenote has finished starting up, choose the Phenoscape interface layout via the View > Layouts > Phenoscape menu item.

Using the docking interface

Docking components

Phenote's interface consists of "docking" components which can be arranged into any layout the user prefers. A default layout for Phenoscape can be accessed via the menu item View > Layouts > Phenoscape. Each component can be minimized or closed using the window-like controls in its title tab. Pressing the arrow in a title tab will pop out a component into its own floating window. Pressing the arrow in the floating component's title tab will return it to the main window. Components can be grouped together in tab groups, where only one of the tabbed components is shown at a time. Click on a title tab to bring a component to the front. If there is not enough space, all tabs in a tab group may not be visible. In this case, left and right arrows will appear in the control tab for that group, which can be used to cycle through the components. Alternatively the downward pointing arrow can be used to display a selectable menu of the tabbed components.

Locking the interface layout

The docking layout can be "locked" so that you don't accidentally rearrange your components (annoyingly easy to do). Choose the Settings > Lock Docking Components menu item.

Displaying specific components

Components that are not currently displayed can be accessed through the View > Show menu. Components are grouped into functional collection submenus. Some components can be opened repeatedly to display multiple instances (e.g. Complete Ontology Tree View), while others will only display a single instance (e.g. Annotation Editor).

Working with files

File names

Phenote can work with only one "project" (set of phenotype annotations) at a time. You can choose a place to save the current annotations via the File > Save menu item, or the Save toolbar button. In the Save dialog, choose the Format "Tab Delimited", and append the extension ".tab" to the end of the filename you enter. Right now this is the responsibility of the user; in the future Phenote should take care of appending this for you. The Phenoscape configuration saves data for a project in 3 files; for this reason it is a good idea to create a separate folder in which to save each project's files. Your phenotype annotations are saved with the filename you provide. Phenote will also save a file containing Taxon List entries in the same folder, with "-taxon-list" appended to the name you gave the main file. When opening or saving a project in Phenote, just choose the main phenotype annotations file - the taxon list file will automatically be opened and saved at the same time. The third file in your project folder is an optional NEXUS file containing a tree relating your taxa. More information on this file can be found in the Phylogeny Chooser section.

If you give your annotations file the name "fish_phenotypes.tab", the following files may be present in your project folder:

• fish_phenotypes.tab - this is the main annotations file you choose for opening and saving
• fish_phenotypes-taxon-list.tab - this file will be automatically found by Phenote when you choose your main annotations file
• fish_phenotypes.tre - this file can contain a phylogeny of your taxa in NEXUS format

Saving changes

If you have made edits to your current document, but have not yet saved, you will see an unsaved changes marker in your window titlebar. On the Mac, this will be a black dot inside the red window close button. On Windows and other platforms, there will be a bullet character in front of the window titlebar text. When you save, using the File > Save menu item, the unsaved changes marker will disappear. If you quit Phenote without saving, you will be warned that there are unsaved changes and given the opportunity to save.

Using Phenote components

Annotation Editor

The editor component displays a detailed data entry interface for the currently selected row in one of the table components. It edits the most recently focused table component. Sometimes when Phenote is first launched, no table has yet been focused and the editor displays a blank canvas - just click on a table to see an editing interface. The displayed entry fields correspond to the columns of the focused annotation table. Fields are either free text or autocomplete. Free text fields accept any input, while autocomplete fields will display a drop-down menu when you begin typing. Autocomplete fields help you to find, and force you to choose, a valid ontology term. The Term Info component will update with detailed information for each ontology term as you move through the autocomplete menu.

Some autocomplete fields are configured to choose terms from more than one ontology. In this case a popup menu in front of the field will allow you to search within either ALL or just one of the configured ontologies.

Some autocomplete fields are followed by a "Comp" button. Press this button to open the post-composition dialog, in which you can create a more specific ontology term by creating relationships to existing terms using the genus-differentia method.

Term Info Browser

The term info component displays detailed information about ontology terms as they are selected elsewhere in the interface. You can view the term's definition, synonyms, relationships to parent and child terms, and several other properties. Parent and child terms are displayed as hyperlinks which can be clicked to display information about those terms in the info component.

Annotation Table

This is the data table containing the phenotype annotations stored in your main data file. Add, delete, and duplicate rows (phenotype annotations) using the toolbar buttons above the table. Select a row to edit its values in the #Annotation Editor component. You may need to click the title tab of the Annotation Table for the Annotation Editor to display the appropriate entry fields. You can select multiple rows in order to enter the same value in a field for them all simultaneously (bulk editing). Individual values can also be edited directly in the table by double-clicking the cell. However, fields containing lists of values cannot be edited within the table.