# Apollo User Guide

## Version 1.3.4
June 16, 2003

# Table of Contents

Introduction

- The Apollo community
- Reporting bugs
- Apollo mailing list

Installing Apollo
Starting up

- Unix
- Windows or Mac
- The first view of Apollo
- Text output from Apollo

Loading Data

- Reading Drosophila annotations
- Reading Ensembl GFF files
- Using the Ensembl CGI server
- Reading Ensembl schema databases
- Reading cross-species comparative data (synteny viewer)
- Styles

The display panels

- The main window
  - Annotations vs. results
  - Splitters
  - Zooming and scrolling
  - Using the Navigation bar
  - Moving using the mouse - centering the display
  - Zoom to selected
  - The guide line
  - Showing reverse complement
  - Forward and reverse strands
  - Feature detail panels
- The types panel
- Selection
  - Selecting a single feature
  - Selecting multiple features
  - Adding to a selection
  - Deselecting
- Finding out more about annotations
  - Get gene report
  - Annotation info
  - The annotation tree
  - Annotation menu
  - Bookmarks
  Linking out to web pages

Search functions

- Finding a specific base
- Finding a feature
- Finding a subsequence

Specifying which features to display

- Collapsed view
- Expanded view
- Hiding features
- Showing features
- Resizing features
- Changing feature style
- Showing sequencing gaps in ESTs
- Showing feature labels
- Using the Types panel to control display of features
- Background colors
- Changing orientation of evidence panel

Sequence level features

- Showing the genomic sequence
- Translating and saving sequence
- Start and stop codons
- Edge matches
- Analyses: GC content and restriction sites
- Viewing alignments

Editing preferences
Printing to file - Postscript output
Apollo help
Checking for Apollo software updates
Summary of mouse functions

Using Apollo to edit annotations

- Saving your annotations
- Autosaving
- Transcript coloring
- Creating a gene model
- Modifying gene models
- Changing the strand of a result
- Editing annotation text
- Exon detail editor

Configuring Apollo

- apollo.cfg
- Style files
- Tiers files

# Introduction

Apollo is a genomic annotation viewer and editor. It was developed as a collaboration between the Berkeley Drosophila Genome Project (part of the FlyBase consortium) and The Sanger Institute in Cambridge, UK. Apollo allows researchers to explore genomic annotations at many levels of detail, and to perform expert annotation curation, all in a graphical environment. Work is still being done on the project to make the editing capabilities even more useful.

Apollo is designed to be used as a graphical front end to a database that stores annotations on genomic sequence. The version you are running has been optimized for use with Release 3 of the Drosophila melanogaster genome; it can also be used to view the current Ensembl releases of human and mouse genome annotation.

The people involved in the development of Apollo include:

- Steve Searle
- Michele Clamp
- Suzanna Lewis
- Nomi Harris
- Mark Gibson
- John Richter
- Vivek Iyer
- Craig Melsopp

with help from

- Sima Misra
- Chris Mungall
- Colin Wiel
- and all the FlyBase curators

### The Apollo community

An increasing number of research groups are using Apollo as a starting point for customizing their own annotation visualization tool. Because Apollo was developed from the beginning to serve the needs of two groups working on different organisms (fruitfly and human) with different types of data, it was specifically designed to be flexible and extensible. The Generic Model Organism Database (GMOD) project, which aims to provide a complete ready-to-use toolkit for analyzing whole genomes, has adopted Apollo as its annotation workbench. Apollo is Open Source; the Apollo source code is all available at SourceForge as part of the GMOD project.

### Reporting bugs

Apollo is still under active development, and there are still many bugs--some we know about, and some we don't. The bugs we know about are listed in a text file in the doc directory called todo. If you encounter a problem that is not listed in that file, please report it via the SourceForge Apollo bug tracker or by emailing us at apollo@fruitfly.org. Please be as specific as possible when you report bugs--tell us what dataset you were looking at, what operating system you're on (e.g. Mac OS X), and what you did that caused the bug. Also send us the output from the Java console (see the section on Text output from Apollo).

When you report a bug, be sure to include your email address. We may need to ask you questions in order to identify the bug, and you'll probably want to know when we've fixed it. You will not be added to any mailing lists or sent any other correspondence.

### Apollo mailing list

If you are interested in discussing Apollo with other users, you can join the Apollo mailing list. Traffic is low, and your email address will not be used for any other purpose. To unsubscribe, use the same Web form.

# Installing Apollo

Apollo is a Java application that you can download and run on your computer (Windows, Linux, or Mac OS X--earlier Mac versions are not supported). You can get Apollo here. When you install Apollo, a JVM is bundled with it, unless you are on Mac OS X.

On most platforms, Apollo runs best with JDK1.3. The exception is recent versions of Mac OS X. If you are on Mac OS X version 10.2.3 or higher, you should install JDK1.4, if you don't already have it. Please see Apple's instructions on how to do this, using Software Updates. If you are running OS 10.2.3 or higher and you only have the older JDK (1.3.1), running Apollo may crash your Mac!. (This is a Mac Java issue, not an Apollo bug.) If you are running Mac OS X version 10.0, 10.1, or 10.2, Apollo will run fine with JDK1.3.1.

Unfortunately, a bug in JDK1.4 on all platforms other than Mac OS X 10.2.3 or higher makes the Exon Detail Editor unusable. For that reason, the Apollo releases for Windows, Linux, and Solaris are bundled with JDK1.3.1.

### Memory use

Apollo uses a lot of memory, largely due to the sheer size of the annotation data. In order to use Apollo, your computer will need to have at least 164Mb of RAM. Moreover, even if you have that much memory, you will probably find that if you try to run more than one instance of Apollo at the same time, performance will suffer. Also note that if you load a very large region, Apollo will use up more memory.

Keep in mind that other applications running on your computer also use memory, so you will get better performance if you shut down other applications (Photoshop, Word, etc.) before you launch Apollo.

Apollo checks twice a minute to make sure you still have enough free memory. If the free memory is getting very low (less than 5% of the the value defined as "Memory" in apollo.cfg), you will get a warning. If you have done or are planning to do any editing, you should save your work and then quit and restart Apollo.

If you load many large regions into Apollo (such as cytological bands), it is possible that it will run out of memory despite the memory checks. Usually the behavior you'll see if this happens is that it will freeze up during loading, but sometimes other things will start to go wrong. If you then look at the Java console, you may see "java.lang.OutOfMemoryError". If this happens, you should exit Apollo and restart.

# Starting up

## Unix

From the directory where Apollo is installed, type

    ./Apollo

You should also be able to run Apollo from other directories by specifying the full path.

## Windows or Mac

Select the Apollo icon from your desktop or dock.

## The first view of Apollo

When Apollo starts up you should see the Apollo splashscreen, which will stay up for a few seconds while the Apollo software loads.

You should then see a window offering various ways to find the region you are interested in. These will be discussed shortly.

## Text output from Apollo

Sometimes it's important to see the text output from Apollo--the messages it prints to inform the user about what it's doing. This is particularly true if something's not working right and you want to report a bug. Your bug report will be much more helpful if you include the text printed to the Java console.

On Mac OS X, you can start a Java console by running the "Console" application, which is usually in the Applications/Utilities folder. On Windows, go to the Control Panel, select "Internet Options", select "Advanced", scroll down to "Microsoft VM", and check off "Java console enabled". You will then need to restart Windows in order to see the Java console. The console should come up when you start Apollo. On Unix, the text output will go to the shell window from which you invoked Apollo.

# Loading Data

### Reading Drosophila annotations

The annotations on the Drosophila genome are stored in a format called GAME XML. GAME XML can be read from a file or pulled transparently across the network from the GadFly database.

Apollo provides several ways to search for the region you are interested in:

- Gene name (e.g., cact)--finds the region surrounding the gene
- Cytological band (e.g., 40B). Warning: these are big and use up a lot of memory.
- Scaffold accession (e.g., AE003490)--gets a ~350Kb chunk of the genome.
- Filename (e.g., data/example.xml)--filenames can use absolute or relative paths (relative paths are taken to refer to files inside the Apollo directory). Please note that if you use the Browse button to select a file, you still need to hit the "Ok" button to begin loading the file. (You can also enter an URL as a filename.)
- Chromosome arm, start and end position (e.g., 3R 100000 300000)
- Sequence (by BLAST homology)--finds the scaffold that includes the best match to your sequence. Please use sequences of less than 10,000 bases, and be prepared to wait a few minutes for the results!

By clicking on the tabs labeled "Gene", "Cytology", etc., you can decide how you want to look for the region of interest. The "File" search also gives you the option of clicking the "Browse" button to search your local file system for the GAME XML file you want to read in.

Note that except for the "File" search, all the searches go over the network to get the Drosophila annotations from the GadFly database, so you must be connected to the internet to use them. Sometimes it takes a while to fetch the data across the internet. Sometimes, GadFly is so overloaded that you will get a message that the data you requested is not found. If you use a proxy, be sure to set the proxy by clicking the "Proxy settings" button before trying to load data from GadFly.

If you'd like to download all the Drosophila annotation data to your computer so you can then access it locally via the File tab, please visit http://www.fruitfly.org/sequence/release3download.shtml.

### Reading Ensembl GFF files

GFF format is a simple format for transferring genomic annotations. A version of GFF (Ensembl GFF) is used at the Sanger Institute for storing the human annotations.

To read in an Ensembl GFF file, choose the "Ensembl GFF" option from the data adapter menu. You can type your GFF file name in the text box or press the Browse button to bring up a file chooser. You can also enter a FASTA-format sequence file name to go with the GFF data. When you're ready, press the OK button and the GFF file (and sequence file, if you specified one) will be read in and the features displayed.

If any of the features in the GFF file have types that are not recognized by Apollo they will be given a default pale gray color. This can be changed by right-clicking over the appropriate feature box in the Types panel (see the types panel section for details).

Please note that there is more than one flavor of GFF, and Apollo only supports the Ensembl flavor (as described here). Apollo does not understand the Artemis flavor of GFF.

Also note that Ensembl GFF format is not rich enough to support curated annotation, so even if you turn on editing, you will not be able to create and save curated annotations on GFF-format data.

Finally, note that although theoretically Apollo can be used to convert between data formats (e.g. GFF <-> GAME), in practice this doesn't work very well. We are working on improving this interconversion.

### Using the Ensembl CGI server

The Ensembl CGI server lets you view the latest annotations on the human genome. Select a region by chromosome number, start, and end position. (Remember that numbering along a chromosome starts at 1, not 0.)

If you use a proxy, be sure to set the proxy by clicking the "Proxy settings" button before loading.

### Reading Ensembl schema databases

The Ensembl project has created databases of annotated genomes for many species - at time of writing this list includes human, mouse, mosquito, rat, zebrafish, and fugu. Each species is stored in a separate, publicly accessible database. The human database can be accessed through the web (see the previous section on using the Ensembl CGI server), but they can all be directly accessed by Apollo - this direct method of access will also be faster.
To directly read Ensembl databases, use the File->Open menu as usual, and choose "Ensembl/Otter - direct database access" from the pulldown (note that it may freeze up briefly as it sets up its configuration). You will be presented with the following dialogue:
The "Region" menu allows you to choose a specific gene to view (by stable id - e.g. "ENSG000001234"), a region of the chromosome location (e.g. "Chromosome 1, from 500,000 to 1,000,000") to view, or a specific clone by identifier (e.g. "AL12345.123.242"). By default the adapter will be getting data from the homo sapiens database. If you are at a loss as to what to type in, try selecting the "Chromosome" button, and typing Chr: "1", Start:"1", End:"500000".
Ensembl features are categorised into various tracks. In order to see any of these tracks in the region you loaded, you must expand the "Tracks" panel by pushing the "Show Tracks" button. You will see the following:
Select the types of features you want to see ("genes" is a good starting point). You must select something from this panel. At this point you should be ready to read data with the default data source configuration (human data at the public servers on kaka). You can hit the "OK" button on the dialog, and Apollo will bring up the selected annotations in your chosen region.

#### Data Source Configurations

The Data Source panel specifies where the ensembl database lives, and how to access it. We have set it up with some defaults, which should allow you to read human data "out of the box", but things will change: you might want to read ensembl data from some other species, or set up your own ensembl databases. Here is the panel, with the defaults at time of writing:
At this time, ensembl data for a particular species is organised into clusters of databases - a "core" database (containing the essential analyses and annotations), supported by a "sequence" database (which might well just be the core), as well as "variation" and "mapping" databases, which contain SNPs and markers, respectively.
Reflecting the need to configure database options for each member of this cluster, the "Data Source" dropdown is either "default", "variation", "mapping" or "sequence". Each of these data sources has all the subsequent database parameters specified for it. Here are what the parameters mean:

- Host. The name of the host on which the ensembl databases live. The publicly accessible site (kaka.sanger.ac.uk) is defaulted in this field. If you set up your own ensembl database, or can see another ensembl database nearby, then you will change this field.
- Port. The port on which the database is "listening" for requests. For MySQL, this port is 3306 by default.
- User. Who Apollo should log-in as. The databases on kaka all have "anonymous" as the user.
- Password. The public ensembl databases on kaka have no password for the user "anonymous".
- Ensembl Database Name. This dropdown is only populated when you hit the "Find" button. It shows all the ensembl databases available on the selected host. You, the user, must make an choice in this field appropriate to the value of the "Data Source" dropdown. We have defaulted the database to the usual human core database ("homo_sapiens_core_9_30" at time of writing). Select "variation" from the "Data Source" dropdown. Notices that the selected Ensembl Database Name is now "homo_sapiens_snp_9_30". This reflects our default "appropriate" choice for a SNP database.
- "Find" Button. If you change any of the Host, Port or User/Password fields, the list of databases will be cleared out, and you will have to repopulate it by pressing the "Find" button. This will make Apollo query the database at by the Host for a new list. You need only "Find" when you change the first four fields.

#### An example of data source configuration: Browsing anopheles data on kaka.

To demonstrate a simple change of these configurations, imagine you wanted to browse the anopheles data on kaka instead of the human data. In this case, you need to change the relevant Ensembl Database Name's to point at the databases containing the mosquito data. The "default" data source at time of writing was "anopheles_gambiae_core_9_1". To make this change, select "default" from the Data Source dropdown, and "anopheles_gambiae_core_9_1" from the list of Ensembl Database Name's:
Note that you must also ensure that the sequence, markers and variations are being correctly retrieved for your anopheles data. This means that the "Ensembl Database Name" must be correctly specified for the "sequence", "marker" and "variation" selections in the database dropdown. In fact, this panel will make a guess as to what those Ensembl Database Name's should be, and will try to set those names up when you make the choice of core database. Have a look! -- Choose the "variation" datasource. The selected Ensembl Database Name should be "anopheles_gambiae_snp_9_1". If this panel does not (or cannot) make the right choice, then it will warn you. At this point you must make the choice for it.

#### Loading and saving manual annotations - otter format

Apollo allows you to create and load manually created annotations in a simple file format designed for storing and transfer of the finished human genome. These files can be created by you the user in apollo or they can be obtained externally (currently for finished human chromosomes) from the otter web site http://www.ensembl.org/otter. To read or create annotations apollo must be configured to enable editing of data. This is done by setting ShowAnnotations and EnableEditing to true in the ensj.style file in the configuration directory. If these parameters are set then an extra button is displayed below the data source configuration panel in the ensj adapter. To load and save otter annotations enter filenames in the "Input file" and "Output file" boxes. When you click save in the main apollo panel any annotations that you have created will be stored in the output file.

An extra way to save annotations is by using an otter server. This can read and write to an annotation database based around ensembl that has been extended to store manual annotation. It enables the user to store annotations centrally, retains a complete history and stores authorship and timestamps of the annotations. For more information on setting up a server or accessing the publically available one please refer to the otter web site.

Please note: Some users have reported trouble writing to otter servers. If you try to save and get a message about sax.parser not being found, and you're on a Mac, you can try editing the Info.plist file to split up the long line that says:

      <string>-Xmx250M -Dorg.xml.sax.driver=org.apache.xerces.parsers.SAXParser -Dswing.defaultlaf=javax.swing.plaf.metal.MetalLookAndFeel]</string>

into separate lines for each argument:

    <string>-Xmx250M</string>
    <string>-Dorg.xml.sax.driver=org.apache.xerces.parsers.SAXParser</string>
    <string>-Dswing.defaultlaf=javax.swing.plaf.metal.MetalLookAndFeel</string>

If you're not on a Mac and you want to write to an otter server and experience difficulty, please contact Vivek Iyer for help.

### Reading cross-species comparative data

The still-under-development Synteny viewer in Apollo lets you view comparative analyses between two genomes. Please see the Synteny user guide for more information.

### Styles

Apollo has a configuration file for each known data source. This file is known as a "style" file. When you choose a data source, Apollo automatically selects the right style file to help it display the data appropriately. If you want to change some of the display parameters (e.g. the background color, names of data types, etc.) be sure to change the appropriate style file--e.g. the style file for GAME XML is called game.style. By default, the style files all live in the conf directory. See the section on configuration files for more about what's in style files and how you can change it.

### Writing your own data adapter

If you are a software developer and would like to write a new data adapter for Apollo so it can read and/or write a different data format, please see the Data Adapter Cookbook. Writing a new data adapter is nontrivial but doable.

# The display panels

## The main window

When Apollo has loaded the data for the region you selected, the main window will appear. Below, for example, the main window is displaying the scaffold called AE003603, which is a 350Kb portion of Drosophila chromosome arm 3R. The top panel graphically displays the results and annotations. The scale (in base pairs) goes across the middle of this panel. All forward strand features are shown above the axis and reverse strand features are below the axis. Each feature type can have a different color. For instance, with the default setup transposons are bright pink and Drosophila ESTs are light green.

### Annotations vs. results

Each of the colored boxes in the main panel is a genomic feature. At the most basic level a feature consists of start and end coordinates on a piece of genomic sequence. Much of the data we deal with can be organized into groups of features that we call feature sets. For instance, a gene is made up of a set of exons which are represented as a group of features. The exons belonging to a particular gene are joined by lines.

When you display Drosophila data, the main panel has a light blue region and a black region both above and below the central axis. The black panels show the raw computational results that were obtained by running various analysis tools (GENSCAN, BLAST, etc.) on the Drosophila genome. The light blue panels closer to the axis show the annotations that were assigned by the biologists who studied all the results and decided where the genes and other important genetic features (e.g. transposons) are located. The Ensembl human annotation data is different--it has not been hand-curated, so there is no distinction between "results" and "annotations".

### Splitters

The little red triangles on the left side of the main window are called splitters. They allow you to control the amount of real estate devoted to the annotation and result panels on each strand. Drag the triangles up or down to adjust the panels.

To reset the panels to their original sizes, use the "Reset views" menu item in the View menu.

### Zooming and scrolling

To zoom in for a closer view, use the x2 and x10 buttons. To zoom out, use the x.1 and x.5 buttons. When you've zoomed in as far as you can go, the x10 and x2 buttons will become disabled. (You wouldn't want to zoom in any further than that, anyway; you can already see the individual bases at that zoom level.) You can reset to the original zoom level with the "Reset" button.

To scroll horizontally, use the scrollbar just above the zoom buttons. The main panel also has vertical scrollbars--if there are many different results or annotations stacked up, you may need to scroll vertically to see all of them.

### Using the navigation bar

The navigation bar lets you view regions from the currently selected genome (Drosophila or human). You can select a chromosome arm, start, and end positions. When you hit "Load", the new region will be fetched from the appropriate database over the internet. This can take a while, especially if you've requested a large region or have a slow network connection.

You can also request the region immediately upstream or downstream from the current region by using the "<" and ">" buttons. The "Expand" button lets you extend the current region by 50%. These buttons change the requested range; you then need to hit the "Load" button to tell Apollo to fetch the new data across the network. The Load button is disabled until you've done something to change the requested region.

### Moving using the mouse - centering the display

Often you want to center the panel on a feature and zoom into that feature. Clicking the middle mouse button anywhere in the main panel will center the panel around that point. If you now press the zoom buttons, you will stay centered around the selected position as you zoom in or out.

To move using the middle mouse button you can middle-click at the left or right sides of the main panel which will recenter the panel at that position and move the display by half a window.

If you are on a PC or Mac, please see the summary of mouse functions for a discussion about how to simulate right- and middle-mouse clicks.

### Zoom to selected

The "Zoom to selected" function zooms and centers so that the currently selected item(s) fill the entire view. This function is in the View menu; its keyboard shortcut is ctrl-z.

### The guide line

To turn on the "guide line", check the "Show guide line" checkbox in the View menu. A black vertical line will appear at your current location. If you scroll, the line will move with you, helping you to remember where you were. If you Zoom to selected, the guide line will reset to the selected location.

### Forward and reverse strands

Sometimes having both the forward and reverse strands visible takes up too much space, making it harder to see all the features. To toggle strands on and off, use 'Show forward strand' and 'Show reverse strand' in the View menu. The keyboard shortcut for Show/Hide Forward Strand is ctrl-f; the keyboard shortcut for Show/Hide reverse strand is ctrl-r.

### Showing reverse complement

To avoid thinking backwards when looking at features on the reverse strand, the whole display (including the sequence) can be reverse complemented. To do this select the 'Reverse complement' option in the View menu. When the display is reverse complemented, the axis numbers turn red as a reminder. There is also a shortcut for performing a reverse complement: simply type the letter 'r' with your cursor over the main window.

"Flip strands" does a reverse complement if both strands are currently displayed. If you were showing only one strand, "Flip strands" will show you the other strand, reverse complemented. This allows you to look at the reverse strand above the axis, so you don't have to turn your computer upside-down.

### Changing y orientation

If you type "o" with your cursor over the main window, each panel will invert from top to bottom. This is not the same as flipping--the reverse strand stays on the bottom and the forward strand stays on the top; only the vertical position of the features in each panel is flipped.

### Feature detail panels

If you click on a feature or features, it is selected (boxed in red) and more information about it will be displayed in the detail panel at the bottom of the main window. The left side of the detail panel shows the type of feature and its name, sequence range, and score. The bottom right panel displays the coordinates of the selected features and possibly other information as well, depending on the feature type.

Each feature set only appears once in the lefthand panel so selecting a feature name in that panel may display a number of features in the right hand display. For instance if our genomic sequence has hit protein P33674 ten times we will only have one entry in the lefthand panel but selecting it will display then rows in the righthand panel.

## The types panel

| The Types panel shows the names of the different types of data and the colors that were assigned to them. To bring up the Types panel, select "Show types panel" in the Tiers menu. The Types panel shows each different data type, organized by tier. A tier is a conceptual grouping of one or more related types--for example, the "Non-coding RNA" tier includes tRNAs, snRNAs, and pseudogenes. To view the types that belong to each tier, you can click the right mouse button while your mouse is over that tier type in the Types panel. (If you are on a Mac, with a single-button mouse, use ctrl-mouse to simulate the right mouse button.) A smaller panel will pop up, showing all the types that belong to the selected tier. For example, in this screenshot, the user has right-moused over "Non-coding RNA", and the popup shows the names and colors of the types of non-coding RNA. When you select a feature in the main panel and the Types panel is open, it will automatically scroll so that the selected feature type is visible, and the box for that type will flash. The Types panel can be used to control how many features are displayed and the way they are displayed. See the section on using the Types panel to control display of features for more information.

### Apollo windows

The "Window" menu in Apollo helps you keep track of the various Apollo windows that are open (such as the Types window). You can bring an Apollo window to the top by choosing it from the Window menu.

## Selection

### Selecting a single feature

Selecting one feature is as simple as clicking on that feature. You will know it's selected as it will have a red outline around it. Selected features are described in the detail panels at the bottom of the main window.

### Selecting multiple features

You can select more than one feature using the the mouse by pressing the middle button and dragging the mouse around the features you want to select ("rubberbanding"). (If you are on a PC or Mac, please see the summary of mouse functions for a discussion about how to simulate middle-mouse.)

When you release the mouse, there may be a brief pause; then all the selected features will be outlined in red and they will all be listed in the detail panel. You can also add features to the currently selected set by shift-clicking with the left mouse button (to add single features) or shift-middle-mouse-dragging (to add multiple features).
Mac users please note: If you are running an older version of Mac OS X, with JDK1.3.1, you may notice a rubberbanding bug where you may see the black rubberband rectangle drawn as you move the mouse, instead of just at the end when you release it, so you will see a concentric set of black rectangles. This is a JDK1.3.1 bug--if you're running Mac OS X version 10.2.3 or later, and have JDK1.4.1, you shouldn't see this problem.

By default, the selected features are sorted by start position (Range) in the detail panel on the lower left. You can change the sort by clicking (for forward sort) or shift-clicking (for reverse sort) on a column header. For example, clicking on "Name" sorts the selected features in alphabetical order by name, and shift-clicking on "Score" sorts them in descending order by score.

If you click on an intron, the whole transcript is selected. Double-clicking an exon also selects the whole transcript (all exons connected to the one you double-clicked). Double-clicking an intron belonging to a gene selects all transcripts belonging to the associated gene. Double-clicking an intron belonging to a result selects all results of that particular type.

### Adding to a selection

If the features you want to select are in multiple places, holding down the shift key before selecting them will add to the previous selection. If you don't hold down the shift key when selecting new features, any previous selected features will be automatically deselected. You can use the shift key with left mouse (to add individual features to the selected group) or with middle mouse (to rubberband more features).

### Deselecting

If you click on the background of the main panel, any features selected in red will be deselected. However they will still be shown in the feature detail panels.

## Finding out more about annotations and features

Note that many of the functions described in this section are accessed via the right-mouse popup menus. Please see the section on mouse functions for a discussion of how to simulate right-mouse on various platforms. Also note that it matters where your cursor is when you hit the right mouse button; in particular, you must have your cursor in the same strand as the selected features in order to perform functions on those features.

### Get gene report

If you select a transcript and click the right mouse button, a popup menu will appear. From this menu, you can request a gene report for the selected annotation. (If you have selected more than one annotation, it will bring up the gene report for the gene closest to where you clicked the right mouse button.) The gene report will appear in your Web browser window (after a brief pause). If your Web browser window was iconified, you may have to bring it back up to see the new gene report.

### Annotation info

The "Annotation info" popup menu item brings up a window that has text information about the annotation. (If you have editing enabled, it will also allow you to add or change the text for an annotation.) The transcripts belonging to the annotation may have individual comments; select a transcript name to see information pertaining to that specific transcript.

Near the middle of the annotation info panel is a table listing database ID(s) for this annotation. If you select an ID, more information about that database entry (if available) will appear in your web browser.

The "Follow external selection" checkbox on the lower left side of the window is used to follow selections from other parts of Apollo. If it is checked, then when you select another gene in the main Apollo window, the annotation info window will load that gene.

You can have multiple annotation info editors open at once. If you commit your changes in one editor, the annotation info for that annotation will automatically get updated in all other open editor windows.

### The annotation tree

| The Annotation Tree panel provides an alternate way to explore the annotations. You can bring up the Annotation Tree from the View menu. If you right-mouse click over a gene name in the annotation tree, a menu item lets you bring up the text information window for that gene.
| The Annotation Tree lists all the annotated genes. If you click on the + icon to the left of a gene name, that item will expand to show all the transcripts for that gene. Clicking the + to the left of a transcript will show you the coordinates of the exons for that transcript. Mac users please note: On a Mac, you will see horizontal and vertical arrowheads instead of + and -. To open or close a node, you must click on the base of the arrowhead, not the pointy end.

### Annotation menu

You can also select a gene or other annotation of interest from the Annotation menu, which is sorted alphabetically by name. (If the annotation name is in bold italics, it means that the annotation is unfinished.) When you select an annotation name, Apollo will zoom to show that annotation plus a window on each side.

### Bookmarks

Apollo allows you to bookmark genes of interest so you can easily come back to them. Select a gene transcript and use Bookmarks -> Add bookmark. To revisit a gene, select its name from the Bookmarks menu. The resulting view is as if you had selected the gene from the Annotation menu, as above.

### Linking out to web pages

Many features originate from other databases (e.g. SwissProt, EMBL, Ensembl, GenBank) and we can learn extra information by looking up those features in their parent databases. To load a web page with more information about a feature, select the feature in the main panel, right click on it, and use the right menu option 'Get info about this feature via Web'. If an URL for this feature type has been registered in the types file, a Web page showing information about this feature will be brought up. For instance, selecting an Ensembl gene will take you to the entry for that gene at the Ensembl web site. It can take a while for the new Web page to appear, as the information has to be sent over the network.

## Search functions

### Finding a specific base

If you know that your feature is at a specific base pair in the sequence you can use the find function to go straight to it. From the Edit menu choose Find and a window will be displayed.

Entering a base pair coordinate in the Position field and pressing Goto will center the main panel display on that base pair.

### Finding a feature

If you have loaded a genomic region and you know a gene or a protein exists in there somewhere but you're not sure where, you can enter an accession or gene name in the Name field. Pressing Find will search through all the features looking for one with that name. If one (or several) are found they will be selected and the main panel will be centered on them. Search is case-insensitive.

The search by name adds an implicit wildcard (*) to the end of your search string. It will first look for a feature with the exact name you specified (e.g. LD46133). If nothing with that name is found, it will look for features whose names begin with that string (e.g. it might find LD46133.5prime). We plan to add more flexible handling of wildcards soon; for now, your search string should contain only the actual characters you're looking for.

### Finding a subsequence

To search for occurrences of a DNA sequence in the current genomic region, enter it in the Sequence field on the Search window. All occurrences of that sequence within the current region will be displayed in a table. (Only the current forward strand will be searched, which means the reverse strand if you're revcomped.) Selecting an entry from this table will zoom to show you the matching subsequence next to the axis.

Please note that you must enter an exact subsequence--wildcards (e.g. *) are not yet handled.

## Specifying which features to display

There can be many features on a piece of genomic sequence and the user may not want to see all of them all at once or maybe not in the maximum amount of detail. Apollo allows the user to control the level of detail that is used.

### Collapsed view

In this view all the features are displayed but all the features belonging to a single tier are placed on the same line. Therefore at any one point there may be several overlapping features piled on top of one another. This can be useful in a zoomed-out view so the user can see at a glance the rough areas of genomic sequence that have features associated with them. Since all the features are displayed in one row, screen space is conserved and more feature types can be seen at once.

Collapsing a specific feature type can be done in two ways. The user can select one of the features and right-click on it. A popup menu will come up and selecting the 'Collapse tier' option will force all features of that type to be drawn on one line. The other way to collapse features is to bring up the Types panel and uncheck the 'Expand' checkbox next to the desired feature type. To collapse all tiers, use the "Collapse all tiers" option from the Tiers menu.

### Expanded view

When zoomed into a region, features often need to be seen in more detail. The expanded view arranges all the features so none of them overlap. This is essential when looking in more detail at the possible exon/intron structure implied by BLAST hits and for possible alternative splicing structures. To expand the view of a feature type, select a feature of the type you want to expand and right click. Select the 'Expand tier' option and all features of that type will be drawn non-overlapping. To expand all tiers, use the "Expand all tiers" option from the Tiers menu.

The image below shows the same set of features as above but now the red and orange BLAST hits are expanded.

### Hiding features

There are often features that you're not interested in that take up valuable screen space. These can be hidden from view until you need them. Select a feature of the type you wish to hide and right click. Select the 'Hide tier' option from the popup menu and the features of that type will not be drawn. This can also be done via the Types panel--just uncheck the 'Show' checkbox for the relevant feature type.

If you want every feature to disappear, select "Hide all tiers" from the Tiers menu.

### Showing features

If you want to reshow hidden features either use the Types panel and click the "Show" checkbox, or right click in the main panel background. Select the 'Show tier' option from the popup menu and select the tier you want to show again. To turn on all tiers, select "Show all tiers" from the Tiers menu.

### Resizing features

The height of all the features can be increased or decreased with the "Increase tier height" and "Decrease tier height" options in the Tiers menu. The keyboard shortcuts for these commands are "+" and "-" (don't use the control key--just + or - by itself).

### Showing sequencing gaps in ESTs

By default, sequencing gaps in EST results are shown as dashed lines. This is controlled by the DashSets option in the appropriate style file. The color of the dashed lines is set by the SequenceGapColor setting in the style file.

### Showing feature labels

By default, annotations are labeled with their names, and other features are not labeled. To turn on labels for a particular feature type, bring up the Types panel (Tiers->Show types panel) and check the 'Label' box next to the feature type of interest. At low zoom levels the labels may overlap so they are hard to read. At high magnifications the labels are organized so they don't overlap each other. (You can turn off this behavior by unchecking the "Avoid text overlaps" box in the View menu.)

### Using the Types panel to control display of features

When you bring up the Types panel, the panel for each tier has checkboxes that can be used to change the view in the main panel. You can switch a tier on and off with the "Show" checkbox. The "Expand" box determines whether all features of a given type are displayed on the same row (possibly on top of each other) or on different rows so that no two features overlap. The "Sort" box determines whether the features are sorted, so that the highest-scoring features are closest to the center of the display. If you check the "Label" box for a given type, the features of that type will be labeled with their names (above or below the feature rectangles). (By default, the Annotations are labeled with their names; you can turn off the labels by unchecking the "Label" box for Annotation in the Types panel.)

You can also limit the number of rows displayed for a particular type by left-clicking on the box for the type (this only works if the Sort check box is ticked). This brings up a window with a slider that lets you change the maximum number of rows displayed for this type. The box next to the slider can also be used to specify the maximum number of rows (enter a number and press return).

Another way to limit the number of features displayed is to set a score threshold--only features with scores above the threshold will be displayed. To set a threshold, middle click the type box. A menu of subtypes is displayed. Select a subtype. This brings up a slider window which can be used to specify the threshold. A mouse click inside the slider bar changes the threshold by one.

If you want to change the order of the tiers, you can drag a tier by selecting a feature in the tier you want to move, holding down shift-right mouse, and dragging the tier to the location where you want it. You should see a solid bar moving around as you drag the mouse; when you let go, the tier will pop into its new location. Note that it's easier to drag tiers if you first collapse all the tiers (ctrl-c), because otherwise you might not notice that you're dragging a feature into an area that's still part of the same tier. Also, be sure to press the shift key before you press the right mouse button, and continue holding the shift until you release the mouse button to leave the tier in its new position. (This can be tricky to coordinate on a Mac, because right-mouse is simulated by holding down the control key, so you'll have to hold down the control and shift keys as you drag the tier.)

You can change the color used to display a feature type by right-clicking in the Types panel over the feature box you want to change. A menu of subtypes will pop up and if you select one of the options you will be presented with a color chooser box.

Once you are happy with your new color set (and tier order) you can save your preferences to a new tiers file. The name of the tiers file needs to appear in the appropriate style file (see the section on configuration files for more details).

### Background colors

The startup background colors for both portions of the main panel (Results and Annotations) can be set in the style file--see the Configuring Apollo section. Once you have launched Apollo, the background color of the result panel can be inverted by choosing "Invert result background color" from the View menu. You can change other colors with the Preferences editor.

### Changing orientation of evidence panel

The evidence panel that shows details about the currently selected features comes up by default in a horizontal orientation at the bottom of the main window. If you prefer this panel to be oriented vertically, select the "Make evidence panel vertical" option from the View menu. You can also set this option in the apollo.cfg file (the option is called FrameOrientation).

## Sequence level features

By sequence level features, we mean features that only need to be displayed at the base pair level--start and stop codons and of course the sequence itself. This section describes ways to look at features at this level of detail.

### Showing the genomic sequence

If you're fed up with colored boxes and want to go right down to the genomic sequence, you need to zoom in far enough so there is room for the individual bases to appear near the axis. The forward strand bases appear above the axis, and the reverse strand bases appear below the axis. If the sequence is currently reverse-complemented, the axis and base numbers are shown in red.

If you select a feature, the region of sequence corresponding to that feature will be highlighted in the feature's color. If you click your right mouse button near the axis, you will be offered another option: "Color bases by splice site potential". This uses a four-color system for indicating splice site potential: GT is colored red, AG is green, CT is blue, and AC is yellow. Note that when you are in splice site coloring mode, selecting features won't highlight them in color on the sequence. To get that behavior back, right-mouse near the axis and select "Color by selected feature".

The features that have sequence associated with them will also show their sequence when you have zoomed in enough. Protein features (such as annotations) show their translated amino acid sequence, while other features show their DNA sequence.

If the sequence letters are too tall to fit in the features, you can type '+' while over the main panel in order to increase the height of the feature rectangles. Sometimes if a feature is partially covered up, its sequence doesn't show up--you can get the sequence to show up (if the feature indeed has sequence associated with it) by clicking on the feature of interest to bring it to the foreground.

### Viewing, translating and saving sequence for selected features

If you want to see the sequence of one or more features, select the features and then use the "Sequence..." option on the right-mouse popup menu. (If "Sequence..." is grayed out, it means you haven't selected any features that have sequence associated with them.) You can also use "Open new sequence window" from the View menu.

The sequence window lets you translate the sequence to amino acids or view the virtual cDNA sequence (just the exons) or the coding sequence (from start of translation to stop). The default display is amino acid sequence for gene annotations and result sequence for results that have sequence. Click the "Save as..." button to save the currently displayed sequence(s) as a multiple-FASTA file.

By default, the sequence window does not follow selections made in the main panel. To change this, you can check the "Follow external selection" checkbox. Then if you select new features in the main panel, their sequences will show up in the Sequence window. You can launch a new sequence window directly from an existing one by clicking the "New sequence window..." button.

Please note that annotations at the very edges of the region you are looking at may be mostly outside the region (they are included in the region if they have even one base inside the region), in which case you won't see their translations as you zoom in and the Sequence menu item will be disabled.

### Start and stop codons

If Apollo has sequence loaded and you zoom in far enough, start and stop codons will be displayed in all six frames. The start codons are shown in green and the stop codons in red. If you are viewing a region downloaded from the Ensembl CGI server, Apollo will fetch the sequence from the CGI server as well.

When you select a transcript in the annotation panel and the start and stop codons are visible, the codons that correspond to the start and stop of translation for that transcript will be highlighted (boxed in red).

### Edge matches

To help you to compare different features in detail, all features that have the same 5' or 3' boundary as the currently selected feature are highlighted with white lines at the edges of the feature boxes. For example, in the screenshot below, the user has selected several purple exons; the edges in other features that match the edges in the purple exons are colored white.

Edge match highlighting is enabled by default. You can turn it off by unclicking "Show edge matches" in the View menu. The color and width of the edge match highlighting can be controlled by options in the style file.

### Analyses: GC content and restriction sites

If the region you are looking at has sequence associated with it, you can show a graph of GC content or find restriction sites. Note that GFF files generally don't include sequence.

#### Showing a GC graph

Selecting "Show GC plot" from the Analysis menu will cause a graph of GC content to be displayed below the axis in the main panel. As with the start and stop codons, if you retrieved features using the Ensembl CGI server, Apollo will go back to the server to retrieve the sequence, since it needs the actual base pairs in order to calculate GC content.

The GC analysis control window allows you to adjust the window length and the color used for the plot.

#### Showing restriction sites

If you choose "Find restriction sites" from the Analysis menu, the analysis control window pops up with a list of restriction sites. When you choose one of the restriction sites, the matching subsequences will be shown in a table.

Selecting one of the matching restriction sites will zoom to and highlight the corresponding bases in the sequence.

### Viewing alignments

To let you examine the alignments between different features and the genomic sequence, Apollo has an interface to the Jalview alignment viewer. This interface is still under development, and is not included in the current release.

Jalview is invoked by choosing one or more features (results and/or annotations) and selecting "Align selected features" or "Align same type features in region" from the right-mouse popup menu. "Align selected features" will align just the features you have selected. "Align same type features in region" will align the selected features plus any features that are the same type as any of the selected features and are within the same range (between the lowest and highest base pair in the selected features).

The selected sequences that qualify will come up in Jalview along with four additional sequences: the genomic sequence plus its three-frame translation.
Known bug: the genomic translations for the reverse strand are wrong. This should be fixed in the next release.

Jalview can display both DNA and/or peptide sequences. Amino acids are shown as single-letter codes followed by two dashes.

Jalview only displays features from one strand, the strand from which you invoked the popup menu. If there are no features selected on that strand the menu item will be disabled. Features that do not have alignment sequence associated with them will not come up in Jalview.

In the Drosophila (GAME XML) data, some results have alignment sequence and some do not. Annotations come up with their genomic sequence (soon the translated annot from translation start to translation stop will also come up).

Ensembl data currently does not have alignment sequences that are accessible externally. This means that at present, Jalview can only be used on Drosophila (GAME XML) data. This will be fixed soon.

Features that are not entirely within the range of the entry currently loaded (overhangers) also will not be displayed in Jalview, as there is no genomic sequence to align them to.

Sequences in Jalview can be selected by clicking on the sequence label on the left and deselected by clicking them again. Selected sequences can be removed from the alignment display by selecting "Delete selected sequences" from the Edit menu. Invert sequence selection will deselect all currently selected sequences and vice versa.

When you select a transcript of features, or two or more features that do not overlap, Jalview displays them with gaps (dashes) between them. It does not display all of the genomic sequence of introns or gaps between features. It does show 9 or 10 bases of genomic sequence on both sides of the intron. This is so the user can see sequence relevant for splice sites.

"Edit->Removed gapped columns" will remove the gapped columns (all dashes). So this will remove the gaps of the intron, but the genomic sequence of the intron remains. On our todo list is adding a menu item to remove the whole intron, gaps and genomic.

Alignments in GAME XML are currently not quite correct. If there are insertions in the result sequence, the genomic sequence does not get gaps inserted it should, throwing off the whole alignment. This should be fixed soon.

Columns can be selected/deselected by clicking above the sequences. A red square will appear in the selected column. Apollo's main window will center to the genomic position of the column selected. Edit->deselect all columns will deselect all columns. "Edit->Remove sequence left/right of selected columns" will truncate all sequences to the left or right of the selected column.

Font type,size and style can be changed with the Font menu. Jalview is optimized for fixed width fonts, so Courier is the recommended font to use for speed. The non-fixed-width fonts (Helvetica and Times-Roman) can get a bit slow when displaying many sequences.

View->Boxes toggles showing the colored boxes.

View->Wrap alignment toggles wrapping of the alignment rather than showing it all on one line. Wrapped alignment is buggy. Sequence labels get blacked out and exceptions get thrown. Will be fixed soon.

View->Black text makes the seq text black (default). View->Colour test makes the sequence text colored. You can only see this if "View->Boxes" is toggled off.

The Colour menu allows you to choose between three colour schemes. Zappo is the default (though because of a bug the checkbox is not checked). The Percent Identity Colour scheme colors for match/mismatch.

Calc menu: Sort by group is the default sorting. Peptides are one group, DNA features are another. Most of the things in this menu don't work yet.

Please see the Jalview manual for more information about Jalview. Please note that not all of the functionality in the standalone version of Jalview described in that manual is available from within Apollo.

Also be aware that Jalview uses a lot of memory, and that if you launch multiple Jalview windows, Apollo may run out of memory.

Known Jalview bugs are listed in the todo file. If you encounter a problem that is not listed in that file, please report it via the SourceForge Apollo bug tracker or by emailing us at apollo@fruitfly.org.

## Editing preferences

The preferences editor lets you edit the style file for the current style. For example, if you are looking at Drosophila data using the GAME XML data adapter, "Edit Preferences" will show you the game.style preferences file.

Editing preferences is a bit tricky, as there is a particular syntax that is used in the file, and it's easy to mess it up. The burden is on you to edit the file in an informed and careful manner, although Apollo tries to check for errors, and refuses to save your changes if they can't be parsed. You can use the "Restore original" button to restore the original style file that came with the Apollo distribution.

Please note that changes to some preferences (e.g. FeatureBackgroundColor) will be immediately reflected in the display, but for others (e.g. ShowAnnotations), you won't see the new setting until you quit and restart Apollo. Also keep in mind that preferences are set separately for each data adapter, so if, for example, you set DrawOutline to true for game.style, and then you load a GFF file, it will use the GFF preferences, which don't include DrawOutline=true unless you set it that way in gff.style.

The game.style preferences file includes all of the preference variables, even though most are just set to their default values. If you are interested in changing the preferences for a different data adapter (e.g. Ensembl CGI) you may find it useful to refer to game.style to see all of the variables, as the other style files are more stripped down.

The way features are displayed (their color, position, etc.) are controlled by tiers files, not directly by the style file. The style file just specifies the name of the tiers file associated with that style. You can change the tiers file by choosing "Show types panel" from the Tiers menu. See the section on tiers files for more information.

## Saving the Apollo screen as a file

Apollo can output a postscript file of the current display by selecting 'Print to File' from the File menu. A dialog box will appear, letting you select the filename and the paper size.

To be honest, though, you're probably better off using a program that lets you "grab" windows to make screenshots.

## Apollo help

This user manual is available from Apollo by selecting "Help..." from the Help menu. If you are reading this, you probably already knew that. Just keep in mind that when you request Help, it may take a while for your web browser to bring up the user manual.

## Checking for Apollo software updates

For your convenience, one of the menu items in the Help menu directs your web browser to the page where you can download Apollo, so you can check whether there's a newer version that you might want to download. You can check which version you currently have by using the "About" menu item.

## Summary of mouse functions

Mouse buttons perform many functions in Apollo. This table summarizes the functions performed by the three mouse buttons, with and without holding down the shift key. If you are on a Mac and have a single-button mouse, you can simulate right mouse by holding down the control or alt key while using the mouse, and you can simulate middle mouse by holding down the apple key. Mac users with five-button mice will find somewhat unexpected behavior: both the left button and the middle (wheel) button are treated as the left button. The two buttons on the far left side of the mouse are treated as the middle button. Also note that Mac users with older Macs and three-button mice may find that the behavior of the right and middle buttons is switched.

On my PC laptop, I found that the middle mouse button just popped up a little scrollbar. To simulate middle mouse, I had to use the Alt key with the left mouse button.

Mouse key | Action
--- | ---
Left | Select feature (or deselect if you're not over any features)
Shift-Left | Add feature to current selection
Left drag | If you drag a feature into the annotation tier, it will be added as a new transcript (if editing is enabled)
Shift-Left drag | If you shift-drag a feature onto an annotation, it will be added as a new exon (if editing is enabled)
Middle click | Center display on clicked location
Middle drag | Rubberband multiple features
Shift-Middle drag | Rubberband multiple features, adding to current selection
Right | Popup menu
Shift-Right drag | Tier drag--move currently selected tier

# Using Apollo to edit annotations

The previous sections have dealt with using Apollo as a browser. If you are annotating a genome, you may be interested in using Apollo as a curation tool. This section explains how to use Apollo's annotation curation and editing capabilities. Please note that we are still debugging the editing functionality of this version of Apollo.

At the moment, you can only edit data that is in GAME XML format. EBI GFF format (which is also used by the Ensembl server) is not a rich enough data format to use for curating annotations. If you turn on editing in gff.style, you will find that it doesn't work right.

## Saving data

After you create or edit annotations, you will probably want to save your work. To save your annotations, select 'Save as...' from the File menu. Apollo supports several output formats, including Ensembl GFF format and GAME XML. The GFF format is simpler (though less rich) and more compact. It is a good format for representing simple computational results, but is not the best choice for saving annotations.

Note that although theoretically Apollo can be used to convert between data formats (e.g. GFF <-> GAME), in practice this doesn't work very well. We are working on improving this interconversion.

### Autosaving

In order to protect against losing changes that you've made to the annotations, Apollo automatically saves your data in a backup file every 20 minutes (that interval can be changed in apollo.cfg). Be aware that if you leave Apollo running for a long time, the autosave file (apollo.backup) will get bigger and bigger.

### General notes on editing

Throughout the instructions on editing, a single left mouse click will select an exon, a double left mouse click or clicking on an intron selects a transcript. Use the shift key to select multiple features. A right mouse click brings up the option menu. In some cases one can rubberband desired features by dragging with the middle mouse button held down.

A center click on a feature will bring that feature to the center of the view.

For many operations selecting an exon or the whole transcript achieves the same result.

If you have selected more than one transcript and you click the right mouse to bring up the popup menu, in most cases the command will apply to the transcript closest to where you clicked.

#### Transcript coloring

If UserTranscriptColoring is set to "true" in apollo.cfg, then each transcript is colored according to its creator. By default, UserTranscriptColoring is off and all annotations are shown in the annotation color defined in the tiers file. The user colors (and which project the users belong to) are defined in the style file (e.g. conf/game.style); you can add your own colors for the users who are annotating genes at your site. The format of the user color lines is

    UserInfo "user=nomi:project=FlyBase:color=255,255,92"

### Creating a gene model

To create a new gene model or transcript, you can simply select results on which to base the gene annotation and drag them into the blue annotation zone. For example, in this screenshot, the user has chosen a purple Genie prediction from the reverse strand and dragged it up into the annotation area. You can see the magenta "ghost" of the dragged Genie model in the blue annotation area.

As you drag the selected result(s), you will see a ghost image. When you drop them, a gene model will be created. If there is already a gene transcript whose ORF overlaps the ORF covered by the new transcript, your new gene model will be added to the existing gene as a new transcript. (If instead you want to add your new transcript as a separate gene, then instead of dragging, you should use the right mouse popup menu option "Create gene transcript".) If your new transcript overlaps two or more existing genes, you will be asked whether you want to create a new overlapping gene, merge the two existing genes that overlap with each other, or add as a new transcript to one of the existing genes.

You can add exons to an existing transcript by holding down the shift key as you left-click and drag one or more result exons onto a transcript.

### Modifying gene models

First of all, your new annotation may not represent a protein-coding gene--it may be some other sort of biological feature such as a transposable element. You can use the Annotation Info editor to change the annotation type, as well as other information about the annotation, such as its name and synonyms.

#### Deleting exons

To delete exons (or whole transcripts), select the unwanted feature(s) (you can use shift-click to select multiple features), click the right mouse to bring up the menu, and select "Delete feature". (Note that when you click the right mouse button, you must have your cursor over the same strand as the selected feature.)

#### Adding exons to an existing transcript

To add an exon to an existing transcript, hold the shift key while dragging the exon onto the desired transcript.

#### Merge exons - will remove the intron between two exons.

1. select exon
2. depress the shift key
3. select another exon in the same transcript
4. right click to bring up popup menu
5. select 'merge exons'
6. The two exons will merge into one exon. All introns between the two exons will disappear and exons that were between the two exons will be merged.

#### Split exon - will create a one base intron in the middle of an exon.

1. select an exon
2. put cursor on exon where you want the intron to be and right click
3. get popup menu
4. select 'split exon'
5. you may have to zoom in to see the intron (if you select on the exon again, only half should appear selected because of small intron). You can then drag the ends of the adjacent exons in the EDE to construct an intron of appropriate size.

#### Move exons to transcript - will move exons from one transcript to another.

1. select all of transcript A with a double left click (left mouse) (this option will only enable if the whole transcript is selected)
2. depress shift key
3. select exon(s) from transcript B
4. right click in annotation zone to get popup menu
5. select 'Move exons to transcript'
6. The exons from B are removed from B and added to A. If they overlap with A's exons they are merged.
Note: If all of A's and B's exons are selected it is equivalent to "merge transcripts".

#### Merge transcripts - merges all exons from two transcripts.

1. select exon or all of transcript A
2. depress shift key
3. select exon or all of transcript B
4. right click in annotation zone to get popup menu
5. select 'Merge transcripts'
6. The two transcripts will be merged into one. Overlapping exons will be merged.

#### Split transcript - will remove the intron connecting two exons and create two separate transcripts.

1. select exon at one end of split location
2. depress shift key
3. select exon at other end of intron where you want the split to occur.
4. right click and get popup menu
5. select 'split transcript'
6. intron will be removed and one transcript will be split into two separate transcripts.
7. note that one of the newly split transcripts may be in a different vertical position, so you won't see it unless you scroll.

#### Set as 5' end

1. select exon in annotation zone that you wish to modify
2. depress shift key
3. select exon in results panel whose boundaries you wish to adopt
4. right click in annotation or results panel to get popup menu
5. select 'set as 5' end'
6. exon boundaries will be extended

#### Set as 3' end

1. select exon in annotation zone that you wish to modify
2. depress shift key
3. select exon in results panel whose boundaries you wish to adopt
4. right click in annotation or results panel to get popup menu
5. select 'set as 3' end'
6. exon boundaries will be extended

#### Set both ends

1. select exon in annotation zone that you wish to extend
2. depress shift key
3. select exon in results panel whose boundaries you wish to adopt
4. right click in annotation or results panel to get popup menu
5. select 'set both ends'
6. exon boundaries will be extended

#### Duplicate transcript

1. select transcript
2. right click to bring up option menu
3. select 'Duplicate transcript'
4. transcript will be duplicated and labelled with a temp suffix. Note that you may have to scroll to see the new transcript.

#### Calculating longest open reading frame

If you add or delete exons from a transcript, the open reading frame should be automatically recalculated. You can also explicitly request it to be recalculated by using the "Calculate longest ORF" option from the right mouse popup menu.

### Changing the strand of a result

If a result feature has been assigned the wrong strand you can move it to the other strand. Select the result feature, right click to get toe popup menu, and select "Move to other strand". The result will then be moved to the opposite strand. (If you've selected more than one result, all of them will be moved.)

### Editing annotation text

To bring up the annotation text editor for a transcript, choose the "Annotation info editor" option in the right-mouse popup menu. An Annotation Information window will appear for the selected gene/transcript, which allows the curator to select a type of entity for the annotation, e.g. gene, tRNA, transposable_element, etc. (the default is 'gene'), add comments to the annotation, name the transcripts, or add comments to individual transcripts.

To add a new comment to the annotation or transcript, click the "New" button. This will put new text in the righthand window saying "edit new comment #1 or select a canned comment". If you want to use a canned comment, you can select one from the pulldown menu; otherwise you can edit the "edit new comment" text to compose your comment. When you do that, the comment should appear in the comment list to the left. (Note that you can't edit the comment in the bigger text window on the left--you can only edit it in the righthand text window.)

To edit an existing comment, select it from the list by author name and date. The comment text will appear in the righthand panel; edit it as desired.

The annotation information editor also lets you add or change synonyms for the annotation or transcript; indicate whether the annotation or transcript is problematic and/or dicistronic; or choose one of the possibilities for Evaluation of Peptide. Don't forget to hit "Commit" to save your changes before closing the Annotation Information window, or "Cancel" if you want to discard all the changes you just made.

Some changes to annotation properties are made via right-mouse popup menu options, rather than in the annotation info editor window. Please note: if you have the annotation info window open and you change that annotation in the main window (e.g. via the right-mouse popup menu), you will lose any uncommitted changes that you made to the annotation info. We are working to resolve this issue.

#### Set owner

To claim ownership of a transcript, select the transcript (or an exon belonging to the transcript), right click to bring up the popup menu, and select "Set owner to [yourname]". If you bring up the popup menu again on the same transcript, you will now see the option to disown the transcript. Note that if you make changes to a transcript, you will automatically be set as the owner of that transcript (unless you then select "Disown" from the menu).

#### Mark a transcript finished or unfinished

After selecting a transcript (or an exon belonging to it), right click to bring up the popup menu. If the transcript is marked finished, you will see a menu option "Set [transcriptname] unfinished". If it is already finished, you will see "Set [transcriptname] completed". You can also mark a transcript finished/unfinished in the Annotation Info Editor.

### Exon Detail Editor

The Exon Detail Editor can be invoked from the right-mouse popup menu. A separate window will appear that shows the reference nucleotide sequence centered around the selected feature. A separate line of sequence is displayed for each transcript that appears in the annotation zone in the region being viewed. The three-frame translation of the sequence is also displayed. The exons for each transcript are denoted on the sequence in blue with successive exons being shown in alternating light and dark blue shades (these colors are configurable--see configuring the Exon Detail Editor). The boundaries of these exons can be moved by left-clicking on the terminal nucleotide and dragging the mouse to either extend or shrink the exon.

The graphic at the bottom of the exon editor window shows the exon structure of the selected transcript and the translation start and stop. The numbers on the exons indicate the translation reading frame for that exon: 1 refers to the top reading frame in the viewer, 2 is middle, 3 is bottom. The orange outline indicates the region of sequence that is current visible in the exon detail view.

If there are multiple annotations, multiple lines of sequence will show up with successive exons highlighted in alternating medium and dark blue shades. To determine which line of sequence corresponds to which annotation, click on the nucleotide sequence and look at the transcript name displayed in the transcript pulldown menu in the lower left corner. Translation length is also provided. The number of lines of sequence displayed corresponds to the maximum number of sequences that are needed to show for the whole strand. For example, if there is a gene with six transcripts on the current strand and you are looking at a gene with one transcript, you will see one line with the transcript and five sequence lines with no features in the region you're looking at.

Clicking on the graphic of the transcript will center the sequence around the region of the transcript that you clicked on. This is the easiest way to navigate in the exon detail editor window. Scrolling with the side bar shifts the sequence by one complete view (no overlap with previous view). Clicking on the top and bottom arrows moves one line of sequence at a time (including all aligning sequences). You can also use the buttons near the bottom right of the window to move to the previous (5') or next (3') gene.

The transcript pulldown menu lists all the transcripts of the current gene. Selecting a transcript in the pulldown will switch the focus of the exon editor window to that transcript. This entails changing the selection of the transcript sequence, changing the glyph of the transcript, and showing the translation length of that transcript.

You can always tell in the main viewer what region of sequence you are looking at in the exon detail editor because the region is bracketed by thin vertical lines in the main viewer. The color of the lines matches the color of the colored thick horizontal bar at the top of the exon editor window. (Multiple exon editor windows can be opened simultaneously. Each one is marked by a horizontal line of a different color.) You can navigate by clicking on the vertical lines(or between them if you are zoomed in) in the main viewer and dragging them horizontally. You must have the mouse pointer in the white sequence coordinate zone to be able to drag the vertical bars. If the mouse is in the results panel or the annotation zone, it will not work.

The "Show search hits" checkbox denotes whether to show the results of a sequence search--see "Find sequence" below.

The "Show introns in translation viewer" checkbox denotes whether to show introns in the transcript graphic. Turning off this option will show a transcript graphic devoid of introns.

The "Follow external selection" checkbox is used to follow selections from other parts of apollo. If it is checked, the exon detail editor will move to show the transcript you clicked on in the main window, as long as the transcript is on the same strand that the exon detail editor is currently showing.

To access the menu in the exon detail editor, right click on the sequence view. A menu will appear and different options will be enabled depending on where you clicked in the sequence window. For example, different options are available if you click on exon sequences vs. intron sequences.

#### Configuration options for the Exon Detail Editor

There are several display options for the Exon Detail Editor that can be set in the appropriate style file. Please see the table of style parameters for more details. These configurable parameters include `ExonDetailEditorSequenceFont`; `ExonDetailEditorBackgroundColor1` and `ExonDetailEditorBackgroundColor2` (for setting the colors of the background stripes); and `ExonDetailEditorFeatureColor1` and `ExonDetailEditorFeatureColor2` (for setting the two alternating colors of the exons).

### Using the Exon Detail Editor

The following operations should be possible in the exon detail editor.

#### Split - makes one base break

1. Right click on a base in an exon.
2. Left click on 'Split'.
3. A one base break (intron) is made in the exon at the base that you clicked on.

#### Make intron - makes intron with conserved boundaries

1. Right click on a base in an exon.
2. Left click on 'Make intron'.
3. An intron is made within the exon. The program branches out from the base that you clicked on and looks for the first splice consensus sequence in each direction to create the intron.
[Currently splice consensus searching is not working and this just does a split.]

#### Create exon - creates exon with conserved boundaries

1. Right click on a base in an intron. (You cannot create an exon outside of the transcript in the exon detail editor. Use the main viewer.)
2. Left click on 'Create exon'.
3. An exon is made within the intron. The program branches out from the base that you clicked on and looks for the first splice consensus sequence in each direction to create the exon. 'Create exon' will not be highlighted as an option if no consensus sequences are available within the intron.
[Currently splice consensus searching is not working. Just creates a one base exon.]

#### Delete exon

1. Right click on a base in an exon.
2. Left click on 'Delete exon'.
3. The exon that you clicked on will be deleted and the remaining exons will be joined to reform the transcript.

#### Merge with 5' exon - Deletes intron and merges exon with adjacent 5' exon.

1. Right click on a base in an exon.
2. Left click on 'Merge with 5' exon'.
3. The exon that you clicked on will be merged with the next exon in the 5' direction by deletion of the intervening intron. If there is no exon in the 5' direction, this option will not be highlighted.

#### Merge with 3' exon

1. Right click on a base in an exon.
2. Left click on 'Merge with 3' exon'.
3. The exon that you clicked on will be merged with the next exon in the 3' direction by deletion of the intervening intron. If there is no exon in the 3' direction, this option will not be highlighted.

#### Set as 5' end

1. Right click on a base in an exon.
2. Left click on 'Set as 5' end'.
3. The base that you clicked on will now be the 5' end of the exon. Other aspects of transcript structure will remain unchanged. The exon edge will be set at the base you specify regardless of the presence or absence of an appropriate consensus splice site adjacent to it.

#### Set as 3' end

1. Right click on a base in an exon.
2. Left click on 'Set as 3' end'.
3. The base that you clicked on will now be the 3' end of the exon. Other aspects of transcript structure will remain unchanged. The exon edge will be set at the base you specify regardless of the presence or absence of an appropriate consensus splice site adjacent to it.

#### Set start of translation

1. Right click on a base in an exon.
2. Left click on 'Set start of translation'.
3. The base that you clicked on will now be the first base of the translation initiation codon. You can set the translation start at any codon. It doesn't have to be an ATG but the ATGs are nicely marked in green.

#### Find sequence

1. Right click in the exon detail editor window
2. Left click on 'Find sequence'
3. A window will pop up.
4. Enter the sequence in the 'Sequence' text area.
5. Select 'is amino acid sequence' or 'is genomic sequence' as appropriate.
6. Left click on 'Search'
7. If the sequence is found in one or more locations, the coordinates will appear in separate boxes. If you click on one these coordinates, the exon editor will scroll to that site. The sequence that you searched for will be in the top line of the window and will be outlined in yellow.
8. The "Show search hits" checkbox will now be checked. To turn off the yellow outlines, deselect this box.

#### Sequence...

1. Left click to select a transcript.
2. Right click on exon detail editor window.
3. Select 'Sequence...'
4. A Sequence window will come up with the sequence for the selected feature, as with the "Sequence..." option from the annotation and result menus.

# Configuring Apollo

### apollo.cfg

The main configuration file that Apollo reads when it starts up is called apollo.cfg. The default location for apollo.cfg is in the conf directory inside Apollo's home directory. If you create a .apollo directory in your home directory and place an apollo.cfg there, Apollo will use that one instead of the one in APOLLO_ROOT/conf. (You can also put personal copies of the style and tiers file in your .apollo directory. This is useful on multi-user systems where many people are sharing the same Apollo installation.)

Note that if you make changes to your apollo.cfg file, you will need to shut down Apollo and restart it to see the changes.

### Style files

There is a configuration "style" file and a tiers file for each data source (called a Data Adapter) that Apollo knows about. These are in the conf directory as well (though, as above, you can put them in ~/.apollo). The style file for the Drosophila annotations, which are in GAME XML format, is called game.style; the style file for Ensembl is ensembl.style. The style file specifies the name of the tiers file, which is game.tiers for the Drosophila annotations and ensembl.tiers for human. This may all sound complicated, but most users shouldn't need to do anything to these files.

The first column of each line in a style file contains property names that are recognized by Apollo. The second column contains their values. // denotes the beginning of a comment, so any text after // up to the end of the line is ignored. Relative paths (those that start without a /) are relative to the directory where Apollo is installed (APOLLO_ROOT), except for paths that start with "~/".

Here are the contents of the default apollo.cfg:

    JavaPath                  "/usr/lib/java"
    Memory                    "250M"
    //AdapterHistoryFile      "apollo.history"
    //AutosaveFile            "apollo.backup"
    AutosaveInterval          "20"
    DataAdapterInstall        "apollo.dataadapter.GAMEAdapter" "game.style"
    DataAdapterInstall	  "apollo.dataadapter.GFFAdapter" "gff.style"
    DataAdapterInstall	  "apollo.dataadapter.EnsCGIAdapter" "ensembl.style"
    CGIHost                   "www.ensembl.org"
    DataAdapterInstall	  "apollo.dataadapter.ensj.AnnotationEnsJAdapter" "ensj.style"
    DataAdapterInstall	  "apollo.dataadapter.das.simple.SimpleDASAdapter" "simpledas.style"
    DataAdapterInstall	"apollo.dataadapter.synteny.SyntenyAdapter" "synteny.style.gff"

    //BrowserProgram          "mozilla"
    SiteShowLimit             "15"
    FastDrawLimit             "0.5"
    TextAvoidLimit            "1500"

    FrameOrientation          "horizontal"

    Karyotypes                "all.kary"

Other options are set (or overridden) in the style files. Here are the options in game.style, the style file for displaying Drosophila annotations:

    Types		          "game.tiers"
    NameAdapterInstall        "apollo.dataadapter.organism.FlyNameAdapter"
    GeneDefinition            "FLY"
    ShowAnnotations           "true"
    ShowResults               "true"
    EnableEditing             "true"
    EnableNavigationManager   "true"
    Chromosomes               "2L,2R,3L,3R,4,X,2h,3h,4h,Xh,Yh,U"
    AnnotationTypes           "gene, tRNA, transposable_element, misc. non-coding RNA, rRNA, snRNA, snoRNA, pseudogene, miscellaneous curator's observation"

    AnnotationBackgroundColor "176,224,230"  // aqua
    FeatureBackgroundColor    "black"
    EdgematchColor            "white"
    EdgematchWidth            "2"
    FeatureLabelColor         "white"
    AnnotationLabelColor      "black"
    CoordBackgroundColor      "white"
    CoordForegroundColor      "black"
    UserTranscriptColouring   "true"
    SelectionColor            "255,0,102"  // pinkish-red
    DashSets                  "true"
    SequenceGapColor          "231,255,51"
    Draw3D                    "false"
    DrawOutline               "false"

    ExternalRefURL "http://www.fruitfly.org/cgi-bin/annot/gene?"

    GeneURL "http://www.fruitfly.org/cgi-bin/annot/get_xml_url.pl?gene="
    BandURL "http://www.fruitfly.org/cgi-bin/annot/get_xml_url.pl?band="
    ScaffoldURL "http://www.fruitfly.org/cgi-bin/annot/get_xml_url.pl?accession="
    RangeURL "http://www.fruitfly.org/cgi-bin/annot/get_xml_url.pl?range="
    SequenceURL "http://www.fruitfly.org/cgi-bin/annot/get_xml_url.pl?sequence="

    // Canned comments for use by annotators
    CommentOption "Only one EST supports this alternative transcript"
    [etc.]

    UserInfo "user=suzi:project=FlyBase:color=25,25,112:full-name=Suzanna Lewis"
    UserInfo "user=sima:project=FlyBase:color=255,255,0:full-name=Sima Misra"
    [etc]

    PeptideStatus "2:Arial,0,9:true:curator examined, accepted"
    [etc]

    PeptideStatus "2:Dialog,0,10:true:curator examined, accepted"

    DefaultFont "Dialog,0,12"

    ExonDetailEditorSequenceFont "Dialog,0,12"
    ExonDetailEditorBackgroundColor1 "gray"
    ExonDetailEditorBackgroundColor2 "black"
    ExonDetailEditorFeatureColor1 "0,102,255"  // medium blue
    ExonDetailEditorFeatureColor2 "0,0,180" // dark blue

Parameter | Explanation
--- | ---
JavaPath | The path to the place where the bin/java executable lives (used by the bin/apollo script). For example, on Mac OSX, java is /usr/bin/java, thus JavaPath is /usr (because bin/java is in /usr). You shouldn't need to set this if you've used the installer to install Apollo.
Memory | How much memory the JVM can use (used by the bin/apollo script). NOTE: if you are using the installed version of apollo, you will not be able to alter this parameter--it is specified inside the installer.
AdapterHistoryFile | File containing a history of recently used commands and settings. By default, if AdapterHistoryFile is not specified, Apollo will check to see if you have a ~/.apollo directory. If so, it will save the history file there. If not, it will save it in APOLLO_ROOT/data. You can override these locations by setting AdapterHistoryFile to a different path.
AutosaveFile | The file to autosave to (when you have editing enabled). If AutosaveFile is not specified, Apollo will check to see if you have a ~/.apollo directory. If so, it will save the autosave file there. If not, it will save it in APOLLO_ROOT/data. You can override these locations by setting AutosaveFile to a different path.
AutosaveInterval | The number of minutes (e.g. "20") between autosaves of the current region in Apollo serial format. This can (theoretically) be used to retrieve your session if Apollo or your machine crashes. Set this to "none" to turn off autosaving.
DataAdapterInstall | These are the different file types and data sources that Apollo recognizes. This list should not need to be changed.
CGIHost | The web server host to use to fetch Ensembl data (gff format).
CGIPort | The web server port to use when fetching Ensembl data.
CGIScript | The name of the cgiscript to use when fetching Ensembl data.
BrowserProgram | The name of the program you use to look at Web pages. In general, you shouldn't need to change this. If you are on Windows or Mac, Apollo should figure out how to launch your Web browser. If you are on Linux, it assumes you have Mozilla; for other Unix systems, it assumes Netscape.
SiteShowLimit | How many bases per pixel have to be displayed before the start and stop codons are displayed. If this is set to zero, no start/stop codons will be shown.
FastDrawLimit | Maximum number of features per pixel before features are merged together on the display to speed up drawing. If you set this above one things get a little odd.
TextAvoidLimit | When labels are switched on, if there are greater than this number of bases per pixel some labels may overlap each other. If the bases per pixel is less than this value, then the features and their labels are rearranged so nothing overlaps and all the labels can be read. You may be able to set this value higher depending on the speed of your machine and the speed of your JVM.
FrameOrientation | The orientation (horizontal or vertical) used for the feature detail panel. Defaults to horizontal.
Types | The location of the tiers file (usually called stylename.tiers) describing how to display the different feature types, including their order and colors. Expected to be in either the user's ~/.apollo directory or in Apollo's conf directory, along with the style files and apollo.cfg.
NameAdapterInstall | Name of class that interprets names of features. Currently available options are apollo.dataadapter.organism.DefaultNameAdapter (the default) and apollo.dataadapter.organism.FlyNameAdapter (for Drosophila data).
GeneDefinition | The kind of genes you are annotating (e.g. FLY). This is used only in Editing mode.
ShowAnnotations | Whether to show the curated annotations. (Ensembl doesn't have these.)
ShowResults | Whether to show the raw computational results.
EnableEditing | If this option is turned on, it allows you to curate your own annotations. Please note that this works for GAME XML data, but GFF is not structured enough to permit annotation curation.
EnableNavigationManager | Whether to show the navigation bar across the top of the main window--lets you go directly to the chromosome region you want.
Chromosomes | A list of valid chromosomes (or chromosome arms) for this organism. If this is left out, the chromosome pulldown menu will simply be replaced by a text box.
AnnotationTypes | Types that an annotation can be--e.g. gene, tRNA, transposon, etc.
AnnotationBackgroundColor | Background color for the annotation panel. Colors can be a default Java color name (e.g. "white" or "red") or an RGB triplet (e.g. "127,255,0").
FeatureBackgroundColor | Background color for the results panel.
CoordBackgroundColor | Background color for the axis and the GC plot.
CoordForegroundColor | The foreground color for the axis.
UserTranscriptColouring | Whether to color annotations by creator (default is false--all annotations are shown in the same color, as set in tiers file).
EdgematchColor | When a feature is selected all other features that have the same boundaries are highlighted at their edges. This defines the color they are highlighted in.
EdgematchWidth | The width in pixels of the highlights that mark the matching edges. Default is 3.
AnnotationLabelColor | The color that is used to label annotations.
FeatureLabelColor | The color that is used to label features when you turn on labeling.
SelectionColor | When features are selected they are outlined to make them noticeable. This is the color used for the outline.
DashSets | Whether to use a dashed line to show sequence gaps in ESTs. (Color of dashed line is controlled by SequenceGapColor.) Default is false, but this is set to true in game.style.
SequenceGapColor | Color to use for showing dashed-line gaps in ESTs.
Draw3D | Whether to show feature rectangles in 3D. Generally, programmers think the 3D effect is cool and biologists find it annoying.
DrawOutline | Whether to outline feature rectangles in black.
ExternalRefURL | The URL used for gene reports
CommentOption | A canned comment that can be added to an annotation. You can have as many of these as you want, one to a line.
UserInfo | If UserTranscriptColoring is turned on, each user's annotations will be shown in their user color. Each line should include a username, project, and color, plus and optional full name.
PeptideStatus | This is complex because there is more than one thing that needs to be passed into the software. The first field is the precedence. The second field is the font which in turn is composed of 3 fields: fontname,fontstyle,fontsize (9 is the default). fontstyle can be 0,1,2,3 (plain, bold, italic, bolditalic). The third field indicates whether or not it is something that a curator may assert. The fourth field is the string for menus. Since part of this is coming from a program (SonOfSam), it needs to be coordinated with that as well and let us hope that the : (colon) is never used in the text because that would mess up the parsing.
DefaultFeatureLabelFont | Fonts are composed of 3 comma-delimited fields: fontname,fontstyle,fontsize (10 is the default). fontstyle can be 0,1,2,3 (plain, bold, italic, bolditalic) DefaultFeatureLabelFont is used for annotations with unknown PeptideStatus (e.g. pseudogenes) as well as feature labels. The PeptideStatus annotation fonts are used for the label of the annotation as well as the font in the the gene menu.
DefaultFont | Axis numbers use the default font, and it's also used for residues inside features when you zoom in.
ExonDetailEditorSequenceFont | Used to show sequence residues in the Exon Detail Editor.
ExonDetailEditorBackgroundColor1, 2 | Colors for the two alternating background stripes in the EDE
ExonDetailEditorFeatureColor1, 2 | Alternating colors for exons in the EDE
FeatureLoadSize | The maximum size of region that features can be fetched (default 1Mb). This is valid only for the Ensembl/Otter method of fetching to limit the amount of network traffic and reduce the load time. For regions greater than this size only genes and contigs are retrieved.

## Tiers file

This file contains details on what color and style to display each feature type with. The style file (e.g. game.style) contains the name of this configuration file (e.g. game.tiers).

Here's an example of what a tiers file looks like:

    tier "Prediction", true, true

    type "Prediction", "Genie", {"gff/genie" "gff:dummy" "genie"}, "72,61,139", true, 0, 100, "apollo.gui.drawable.DrawableResultSeqFeature", {score GENOMIC_RANGE query_frame}, score, false, SINGLE, http://some.web.org/

    type "Prediction", "Genscan", {"genscan:dummy" "genscan"}, "72,139,61", true, 0, 100, "apollo.gui.drawable.DrawableResultSeqFeature", {score GENOMIC_RANGE query_frame}, score, false

    type "Prediction", "tRNA", {"trnascan-se:dummy" "tRNAscan-se"}, "139,72,61", true, 0, 100, "apollo.gui.drawable.DrawableResultSeqFeature", {score GENOMIC_RANGE query_frame}, score, false

A tier line defines a set of feature types that will always be displayed together as a group. They will be displayed in the same row if possible when the features are expanded but as close together as possible if they overlap. The first field is always 'tier', the next is the feature set (tier) name, and the next two are whether it should be displayed or not and whether the features should be expanded.

Optional fifth, sixth, and seventh arguments on a tier line specify whether the results should be sorted (default false), the max row (default 0), and whether the results in that tier should be labeled (default false).

The lines following the tier line define the feature types that will be grouped together in that tier. Below is a table listing all the different fields for one of the lines and explaining what they mean.

type

| Always the same - tag saying we've got a type definition coming

"Prediction"

| Says that this type belongs to the "Prediction" tier (defined in the tier line)

"Genie"

| Name of the type

{"gff/genie" "gff:dummy" "genie"}

| A list of gff source_tags that will be put in this tier. (The gff source tag is the second column in a gff file)

"72,61,139"

| RGB values defining the color used to display this type

true

| Do we use the score of each feature to set the height of the colored boxes (high scores are tall and low scores are short)?

0

| If we are sizing feature heights by score, what is the minimum score, i.e., the score at which to draw the shortest box

100

| If we are sizing feature heights by score, what is the maximum score, i.e., the score at which to draw the tallest box

"apollo.gui.drawable.DrawableResultSeqFeature"

| The class to use for the feature type. Use DrawableResultSeqFeature for most things (blast hits, gene predictions) Use DrawableAnnotatedSeqFeature for genes (has nice tented introns). Another feature type is DrawableSiteCodon (which is used for the start and stop codons).

{score GENOMIC_RANGE query_frame}

These are the fields to display in the detail panel.
Possible values are

NAME
GENOMIC_RANGE
GENOMIC_LENGTH
MATCH_RANGE
MATCH_LENGTH
score
expect (expectation value from blast, genscan, etc.)
query_frame

Any number and combination of these values can be specified.

score

Which of the above values is used to sort the list of features in the detail panel

true

Whether to sort in reverse order

SINGLE

This field can have one of three values: SINGLE, HOMOLOGY, or GENE. SINGLE is used for feature types that aren't grouped together (e.g. CPG islands). HOMOLOGY is used for feature pairs that need to be grouped together by hit ID. Features that are identified as HOMOLOGY (e.g. any blast hit or similarity search result) have a start and end coordinate on the hit sequence as well as on the genomic GENE is used for genes that need to be grouped together by ID.

"http://www.ebi.ac.uk/cgi-bin/emblfetch?"
"http://www.ensembl.org/perl/geneview?gene=ID."

This final field defines how to link out to an external web site when any feature is right clicked.

Only one web site can be specified. The first example on the left is the simplest way to link out. If the name of the feature is AC005663 then your browser will be directed to http://www.ebi.ac.uk/cgi-bin/emblfetch?AC005663--i.e., the name of the feature is tagged on the end of the URL.

More complicated URLs can be constructed. In the second example we only want the feature name up to the first "." For example, the gene name is QZ9839.1 and our web site only wants QA9839. The string ID. tells Apollo to truncate the name at the first ".".

#### Saving your type preferences

If you do File->Save type preferences... and save a new version of the tiers, make sure the style file contains the new tiers file name. For example, if you saved a new Drosophila types file as "my.tiers", then you'd need to change the Types line in game.style to say

    Types		        "my.tiers"

If you edit the tiers file, please note that each tier line and each type line must be a single line--if these lines contain newlines, they will not be parsed properly.

Last modified: Tue Jun 17 10:34:36 PDT 2003