Selecting Regions | Overview Panel | Detail Panel | Adding Annotations | Quick Uploads
--- | --- | --- | --- | ---

# Generic Genome Browser: General Help

These are general instructions for using the Generic Genome Browser software. The colors, tracks and other features of the server you are accessing these help pages from may be different, depending on any site-specific customization the local administrators may have applied.

## Selecting a Region of the Genome

To select a region of the genome to view, enter its name in the text field labeled "Landmark or Region". Recognized types of names are under the control of the administrator, but usually the following names are accepted:

a chromosome name
  For genomes that have been assembled into chromosome-length segments, you can enter the name of the chromosome. The chromosome name follows the conventional nomenclature for the species. For example, C. elegans chromosomes are indicated using roman numerals, such as III, D. melanogaster uses chromosome arms such as 2L and 2R, while H. sapiens uses arabic numbers such as 9.

a chromosome band
  For genomes that have named banding patterns, you can use the standard nomenclature such as 1q13.

a gene name
  You can enter the name of a gene using the standard nomenclature for that species.

a contig or clone name
  You can enter the name of a structural landmark such as a cosmid, BAC or contig.

an accession number
  You can enter a GenBank or EMBL accession number.

protein names, primer names, ORF IDs, author names...
  At the discretion of the administrator of the database, other identifiers can be entered. See the examples listed at the top of the browser page for hints.

You may use the wildcard character "*" if you are unsure of the landmark name. If the requested landmark is not found, the browser will display a message to this effect.

### The Overview and Detail Panels

If the landmark is found in the database, the browser will display the region of the genome it occupies. The region is displayed in three graphical panels:

overview panel
  This panel displays the genomic context, typically an entire assembled chromosome or a large portion of the sequence assembly such as a scaffold or contig. At the administrators' discretion, certain important landmarks, such as a well-known genetic markers or cytogenetic bands can be placed in this view. A highlighted rectangle indicates the region of the genome that is displayed in the detail panel and corresponds to the region found when you search for a gene or other feature. This rectangle may appear as a single line if the detailed region is relatively small.

region panel
  This panel displays a portion of the genome surrounding the region of interest. It gives the context for the search region. At the administrator's discretion, there may be tracks of information in the region panel.
detail panel
  This panel displays a zoomed-in view of the genome corresponding to the overview's selection rectangle. The detail panel consists of one or more tracks showing annotations and other features that have been placed on the genome. The detail panel is described at length later.

### Specifying the Landmark Class

At the administrator's option, some kinds of landmarks may have to be qualified using the format prefix:landmark. For example, a clone named "c23" might need to be searched for using "clone:c23".

### Viewing a Precise Region around a Landmark

You can view a precise region around a landmark using the notation landmark:start..stop, where start and stop are the start and stop positions of the sequence relative to the landmark. The beginning of the feature is position 1. In the case of complex features, such as genes, the "beginning" is defined by the database administrator. For example, in the C. elegans data set, position 1 of a predicted gene is the AUG at the beginning of the CDS, so to view the region that begins 100 base pairs upstream of the AUG ends 500 bases downstream of it, you would search for mek-1:-99..500.

This offset notation will work correctly for negative strand features as well as positive strand features. The coordinates are always relative to the feature itself.

To offset relative to a qualified feature name, just include the type name, as in PCR_Product:sjj_K08A8.1:-500..500 (note that this particular example only works with the C. elegans database).

### Searching for Keywords and Multiple Hits

Anything that you type into the "Landmark or Region" textbox that isn't recognized as the name of a landmark will be treated as a full text search across the feature database. This will find comments or other feature notations that match the typed text. Depending on how the database is set up, you may find gene names, gene functions, author names, or bibliographic references.

If more than one landmark or keyword search is found, then the browser will display a graphical representation of the whole genome and summarize the various hits in a table. You can click on one of the landmarks in either the graphical display or the table in order to view it in the detail view:

### Autocompletion

At the discretion of the administrator, searching autocompletion may be active. In this case, a menu of possible choices will pop up as you type in landmark names and other search terms. Because autocomplete is limited to exact name matches, you may still find hits via keyword search even if no autocomplete matches are recommended.

## Navigation

Once a region is displayed, you can navigate through it in a number of ways:

Click and drag on any of the rulers
  Any of the rulers that show base position, including those in the overview, region and detail panels, are clickable. Click once to recenter the view at the desired position, or click and drag to select a region.

Scroll left or right with the <<, <, > and >> buttons
  These buttons, which appear in the "Scroll/Zoom" section of the screen, and at the top right and left corners of the detail panel, will scroll the detail panel to the left or right. The << and >> buttons scroll an entire screen's worth, while < and >> scroll a half screen.

Zoom in or out using the "Show XXX Kbp" menu.
  Use menu that appears in the center of the "Scroll/Zoom" section to change the zoom level. The menu item name indicates the number of base pairs to show in the detail panel. For example, selecting the item "100 Kbp" will zoom the detail panel so as to show a region 100 Kbp wide.

Make fine adjustments on the zoom level using the "-" and "+" buttons.
  Press the - and + buttons to change the zoom level by small increments (usually 10-20%, depending on how the browser is configured).

Flip the orientation by selecting the "flip" checkbox
  To flip the browser display so that the minus strand points to the right, select the "flip" checkbox. This is sometimes useful for looking at minus strand genes.

Recenter the detail panel by clicking on its scale
  The scale at the top of the detail panel is live. Clicking on it will recenter the detail panel around the location you clicked. This is a fast and easy way to make fine adjustments in the displayed region.

Mouse over a feature to get more information about it
  Mousing over a feature will usually bring up a text bubble that contains more identifying information about the feature.

Click on a feature to see its details
  Clicking on a feature in the detail view will link to a page that displays detailed information on it. This could be a page on the browser's web site, or a page on another resource somewhere on the web.

## The Detail Panel

The detailed view is composed of a number of distinct tracks which stretch horizontally from one end of the display to another. Each track corresponds to a different type of genomic feature, and is distinguished by a distinctive graphical shape and color.

Each track has a descriptive name printed above it, and a series of small control icons to the left of the name.

- To reorder a track, click on its name and drag it up or down to the desired position.
- To minimize a track, click on its "-" icon. The track will minimize down to the name only and the icon will change to a "+". Click on the icon again to maximize the track.
- To turn off a track, click on its "x" icon. The track will disappear entirely, but can be reenabled by selecting its name in the track table described below.
- To share a track such that the track data can be imported into another instance of the browser, click on the icon that looks like a set of radio waves (. This will pop up a window containing a link that you can cut and paste into another instance of the Generic Genome Browser. Please see Importing Tracks for more details.
- To get more information about track, mouse over its "?" icon. This will bring up any descriptive information that the site administrator has provided for the track. In some cases, the administrator may not have provided this information.
- To change a track's appearance, click on the "?" icon. This will present you with a pop-up window that allows you to change many aspects of the track, including its height, display style, and color.

## Uploading Your Own and 3d Party Annotations

This browser supports uploading your own data set tracks. You can then share these tracks with other individuals and groups.

### Entering New Data Sets

To upload a custom track to the browser, click on the link labeled "Upload and Share Tracks" located towards the top of the screen. This will open a new text editing area. Type in one or more lines of genomic feature information following the example in the screenshot below. The simplest upload format is called BED, and takes three space-separated fields:

>     <chromosome> <start> <end>

Where <chromosome> is the name of the chromosome that the feature lives on, and <start> and <end> indicates the range that the feature spans. (The BED format uses zero-based coordinates, so the first base of the chromosome is actually position 0. Other formats accepted by GBrowse use the more familiar one-base coordinates.).

Press the "Upload" button. The indicated features will be uploaded to GBrowse and information about the upload set will be displayed in a new section similar to this one:

To view your uploaded annotations in a new browser track, click on the "View track" link. Note that you may need to navigate to the region of the genome containing the annotations in order to see them. To edit the annotations, click the "edit" link to the right of the name of the upload file (in this example "upload_24561").

To customize the appearance of the track, press the "edit" link to the right of the "Configuration" line. Note that this involves editing a configuration file that has many options. You can perform all basic customization tasks such as changing the height and color of your uploaded features, much more conveniently by clicking the "?" icon next to the track itself.

To add a description to the uploaded set, click on the line that reads "Click to add a description" and type in a one-line description of the data. Press the escape key to undo the changes. Press return or mouse out of the description area to accept the change.

To delete the uploaded annotation data completely, click the trash can icon.

To share an uploaded track with another person, go to the main browser tab

#### Uploading Files

For anything more than a short list of annotations, you will want to prepare your custom track(s) in a file on your local machine and upload the file to GBrowse. This is also mandatory for file formats that require fields to be separated by tabs rather than spaces. Use a text editor to prepare the track definitions and data and be sure to save as text only. Now click on the "From a file" link in the upload area, and follow the prompts to upload the file.

You can upload or type in as many annotation files as you desire. If you upload a new file with exactly the same name as an old one, it GBrowse will rename the new file by appending a "-1" to its end to avoid your inadvertently overwriting the old file. To replace an existing file, delete the old one before you upload the new one.

#### Annotation File Formats

GBrowse accepts custom track data in a variety of formats including BED, GFF, and GFF3. For dense quantitative data use Wiggle (WIG) format.

GBrowse also accepts a simple internal format called feature file format (FFF). The main advantage of this format is that it allows for extensive customization of the appearance of each track and feature.

In most cases, you can define multiple tracks in a single file by creating several "track" definition lines in BED or WIG format files, or by defining several track configuration sections in FFF format files. See the documentation of each format for assistance.

In addition to these genomic formats, you can upload dense genomic sequencing data in BAM or SAM format. This feature requires the administrator of the particular database on which GBrowse is running to have installed the BAM support libraries and to have initialized a genomic sequence track. At low magnifications, uploaded BAM/SAM tracks will show a coverage graph of the data. At higher magnifications, they will show individual reads and the alignment between the reads and the genome.

## Importing tracks from Remote Sources

GBrowse allows you to import track data from a variety of remote locations, including:

1. A track from another GBrowse instance that shares the same chromosomal coordinates.
2. A track definition file that someone has placed on an internet-accessible web or FTP server.
3. A track defined by a Distributed Annotation Server (DAS) server.

To import a track from a remote source, you must know its URL.

To import a track from another GBrowse instance, click on the radio wave () icon in the track title and then copy the URL that appears there. Go to the "Upload and Share Tracks" panel, and click on the "Import a track" link. This will open up a new text field. Paste in the copied URL and press "Upload".

If the remote track was successfully imported, a description of the remote track similar to the previous section's listing of uploaded tracks will appear.

To import a track from a Web or FTP file, make sure that the web or FTP server is accessible to the machine on which the GBrowse instance is running, and that file is in one of the upload formats recognized by GBrowse (e.g. BED or GFF3). Then click the "Import a track" and paste in the annotation file's URL as before. To import a track from a DAS server, identify the URL used by the DAS server for the desired track. The DAS registry will help you locate DAS servers with useful genomic data. Then cut and paste the DAS server URL into the remote track URL box as before.

You may add as many remote tracks as you wish. To delete one, simply click on the trash icon next to its name in the remote track listing.

## Quick Uploads

A quick way to upload one or two features is by adding an "add" argument to the gbrowse URL. For example, this URL will create a track named "MyDeletions" containing a feature named "Deletion3". Deletion3 occupies the region on chromosome chrI between 100,000 and 150,000:

> http://gbrowse_url/?add=chrI:100000..150000

or a multipart feature with segments at 100000..110000 and 120000..130000:

> http://gbrowse_url/?add=chrI:100000..110000,120000..130000

You can have as many "add" options as you like:

> http://gbrowse_url/?add=chrI:100000..110000,120000..130000;add=chrI:80000..90000

To label the track and the features within the track, you may use the extended format shown here:

> reference+trackName+featureName+start..stop,start..stop,start..stop ...

where "reference" is the name of the chromosome or contig, "trackName" is the name of the new track you wish to place the feature in, and "featureName" is the name of the feature you are uploading. As before, the list of "start..stop" coordinates are the start and end coordinates relative to "reference". For multisegmented features, specify multiple start..stop pairs separated by commas.

For more control over the way quick upload features appear, specify the "style" option to the URL:

> http://gbrowse_url/?style=MyDeletions+glyph=arrow+double=1+fgcolor=blue

This says to configure the "MyDeletions" track with the following options:

>     glyph=arrow
>     double=1
>     fgcolor=blue

See the uploaded annotation help file for more details

.

$Id$