File: general_help.html

package info (click to toggle)
gbrowse 2.56%2Bdfsg-2
links: PTS, VCS
area: main
in suites: stretch
size: 13,112 kB
ctags: 4,436
sloc: perl: 50,765; sh: 249; sql: 62; makefile: 45; ansic: 27
file content (573 lines) | stat: -rw-r--r-- 20,168 bytes
parent folder | download | duplicates (7)
<html>
<head>
<link type="text/css" media="all" rel="stylesheet" href="/gbrowse2/css/gbrowse.css" />
<link type="text/css" media="all" rel="stylesheet" href="/gbrowse2/css/gbrowse_warm.css" />
</head>
<body>


<table width="100%"  style="border:ridge">
  <tr class="searchtitle">
    <th><a href="#selecting">Selecting Regions</a></th>
    <th><a href="#navigation">Overview Panel</a></th>
    <th><a href="#detail">Detail Panel</a></th>
    <th><a href="#upload">Adding Annotations</a></th>
    <th><a href="#quicky">Quick Uploads</a></th>
  </tr>
</table>


<h1>Generic Genome Browser: General Help</h1>

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.

<h2><a name="selecting">Selecting a Region of the Genome</a></h2>

<p>

<img src="images/help/landmark.png" align="RIGHT" class="figure">

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:

<dl>
  <dt><b>a chromosome name</b>
  <dd>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, <i>C. elegans</i> chromosomes are
      indicated using roman numerals, such as III,
      <i>D. melanogaster</i> uses chromosome arms such as 2L and 2R,
      while <i>H. sapiens</i> uses arabic numbers such as 9.
      <p>
  <dt><b>a chromosome band</b>
  <dd>For genomes that have named banding patterns, you can use the standard
      nomenclature such as 1q13.<p>
  <dt><b>a gene name</b>
  <dd>You can enter the name of a gene using the standard nomenclature
      for that species.
      <p>
  <dt><b>a contig or clone name</b>
  <dd>You can enter the name of a structural landmark such as a
      cosmid, BAC or contig.
      <p>
  <dt><b>an accession number</b>
  <dd>You can enter a GenBank or EMBL accession number.
      <p>
  <dt><b>protein names, primer names, ORF IDs, author names...</b>
  <dd>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.
</dl>

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.

<h3>The Overview and Detail Panels</h3>

<p>

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:

<p>

<center>
<img src="images/help/overview+detail.png" class="figure">
</center>

<p>

<dl>
  <dt><b>overview panel</b>
  <dd>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.
      <p>
  <dt><b>region panel</b>
  <dd>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.
  <dt><b>detail panel</b>
  <dd>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.      
</dl>

<h3>Specifying the Landmark Class</h3>

<p>

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

<h3>Viewing a Precise Region around a Landmark</h3>

<p>

You can view a precise region around a landmark using the notation
<i>landmark:start..stop</i>, where <i>start</i> and <i>stop</i> 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 <i>C. elegans</i> 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
<i>mek-1:-99..500</i>.

<p>

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.

<p>

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

<h3>Searching for Keywords and Multiple Hits</h3>

<p>

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.

<p>

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:

<center>
<img src="images/help/multiple_hits.png" class="figure">
</center>

<h3>Autocompletion</h3>

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.

<hr>

<h2><a name="navigation">Navigation</a></h2>

<img src="images/help/navbar.png" class="figure">

<p>

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

<dl>
  <dt><b>Click and drag on any of the rulers</b></dt>
  <dd>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.</dd>
      <p>
  <dt><b>Scroll left or right with the &lt;&lt;, &lt;,
      &gt; and &gt;&gt; buttons</b>
  <dd>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
      <b>&lt;&lt;</b> and <b>&gt;&gt;</b> buttons scroll an entire
      screen's worth, while <b>&lt;</b> and <b>&gt;&gt;</b> scroll a
      half screen.
      <p>
  <dt><b>Zoom in or out using the "Show XXX Kbp" menu.</b>
  <dd>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.
      <p>
  <dt><b>Make fine adjustments on the zoom level using the "-" and
      "+" buttons.</b>
  <dd>Press the <b>-</b> and <b>+</b> buttons to change the zoom level
      by small increments (usually 10-20%, depending on how the
      browser is configured).
      <p>
      
  <dt><b>Flip the orientation by selecting the "flip" checkbox</b>
  <dd>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.
      <p>
  <dt><b>Recenter the detail panel by clicking on its scale</b>
  <dd>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.
      <p>
  <dt><b>Mouse over a feature to get more information about it</b>
  <dd>Mousing over a feature will usually bring up a text bubble
      that contains more identifying information about the feature.
      <p>
  <dt><b>Click on a feature to see its details</b>
  <dd>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.
      <p>
</dl>

<br clear="all">

<hr>

<h2><a name="detail">The Detail Panel</a></h2>

<p>

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.

<p>

<center>
<img src="images/help/detail.png" class="figure">
</center>

<p>

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

<p>

<ul>
<li><b>To reorder a track</b>, click on its name and drag it up or down to the
desired position.</li>
<li><b>To minimize a track</b>, 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.</li>
<li><b>To turn off a track</b>, click on its "x" icon. The track will
    disappear entirely, but can be reenabled by selecting its name in
    the track table described below.</li>
<li><b>To share a track</b> 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 (<img src="images/buttons/share.png" />. 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 <a href="#importing">Importing
    Tracks</a> for more details.</li>
<li><b>To get more information about track</b>, 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.</li>
<li><b>To change a track's appearance</b>, 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.</li>
</ul>

<hr>

<h2><a name="upload">Uploading Your Own and 3d Party Annotations</a></h2>

<p>

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

<h3>Entering New Data Sets</h3>

<p>

<img src="images/help/upload.png" class="figure">

<p>

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:

<blockquote>
<pre>
&lt;chromosome&gt; &lt;start&gt; &lt;end&gt;
</pre>
</blockquote>

<p>Where &lt;chromosome&gt; is the name of the chromosome that the
feature lives on, and &lt;start&gt; and &lt;end&gt; indicates the
range that the feature spans. (<i>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.</i>).

<p>

<img src="images/help/upload_field.png" class="figure" />

<p>

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:

<p>

<img src="images/help/upload_list.png" class="figure" />

<p>

To <b>view</b> 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").

<p> To <a href="annotation_help.html#customize">customize the
appearance</a> 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 <a href="annotation_help.html">options</a>. 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.

<p>

To <b>add a description</b> 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.

<p>

To <b>delete</b> the uploaded annotation data completely, click the trash can
icon.

<p>

To <b>share</b> an uploaded track with another person, go to the main
browser tab 

<h4>Uploading Files </h4>

<p>

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 <b>as text only</b>. Now click on the "From a file" link in the
upload area, and follow the prompts to upload the file.

<p>

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.

<h4>Annotation File Formats</h4>

<p>

GBrowse accepts custom track data in a variety of formats including <a
href="http://genome.ucsc.edu/FAQ/FAQformat#format1"
target="_blank">BED</a>, <a
href="http://genome.ucsc.edu/FAQ/FAQformat#format3"
target="_blank">GFF</a>, and <a
href="http://www.sequenceontology.org/gff3.shtml"
target="_blank">GFF3</a>. For dense quantitative data use <a
href="http://genome.ucsc.edu/goldenPath/help/wiggle.html"
target="_blank">Wiggle (WIG)</a> format.

<p>

GBrowse also accepts a simple internal format called <a
href="annotation_help.html" target="_blank">feature file format
(FFF)</a>. The main advantage of this format is that it allows for
extensive customization of the appearance of each track and feature.

<p>

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.

<p>

In addition to these genomic formats, you can upload dense genomic
sequencing data in <a href="http://samtools.sourceforge.net/"
target="_blank">BAM or SAM</a> 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.

<hr>

<h2 name="importing">Importing tracks from Remote Sources</h2>

<p>

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

<ol>
  <li>A track from another GBrowse instance that shares the same
  chromosomal coordinates.

  <li>A track definition file that someone has placed on an
  internet-accessible web or FTP server.
      
  <li>A track defined by a <a
  href="http://www.dasregistry.org/">Distributed Annotation Server
  (DAS)</a> server.
</ol>

<p>

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

<p>

<b>To import a track from another GBrowse instance</b>, click on the
radio wave (<img src="images/buttons/share.png" />) 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".

<p>

<img src="images/help/remote.png" class="figure">

<p>

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.

<p>

<b>To import a track from a Web or FTP file</b>, 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.

<b>To import a track from a DAS server</b>, identify the URL used by
the DAS server for the desired track. The <a
href="http://www.dasregistry.org/">DAS registry</a> 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.

<p>

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.

<hr>

<h2><a name="quicky">Quick Uploads</a></h2>

<p>

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:

</p>

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

<p>

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

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

<p>

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

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

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

<blockquote>
reference+trackName+featureName+start..stop,start..stop,start..stop ...
</blockquote>

<p>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.</p>

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

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

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

<blockquote><pre>
glyph=arrow
double=1
fgcolor=blue
</pre></blockquote>

<p>See <a href="annotation_help.html">the uploaded annotation help
file</a> for more details</p>.

<hr>

$Id$

</body>
</html>