Displaying Your Own Annotations in the Genome Browser
The Genome Browser provides dozens of aligned annotation tracks that have been computed at UCSC or
have been provided by outside collaborators. In addition to these standard tracks, it is also
possible for users to upload their own annotation data for temporary display in the browser. These
custom annotation tracks are viewable only on the machine from which they were uploaded and are
automatically discarded 48 hours after the last time they are accessed, unless they are saved in a
Session. Optionally, users can make custom
annotations viewable by others as well. For a more stable option for custom annotations, we suggest
using track hubs. A third, more technical, option is to operate a mirror. Custom tracks work well for quickly displaying data, while track hubs are
more configurable and permanent.
Custom tracks are a wonderful tool for research scientists using the Genome Browser. Because space
is limited in the Genome Browser track window, many excellent genome-wide tracks cannot be included
in the standard set of tracks packaged with the browser. Other tracks of interest may be excluded
from distribution because the annotation track data is too specific to be of general interest or
can't be shared until journal publication. In the past, many individuals and labs contributed custom
tracks to the Genome Browser website for use by others. To view a list of these custom annotation
tracks, click here.
Track hubs are now the preferred approach for viewing and sharing data on the Browser. Labs,
consortia, and institutions submit their hubs to be listed as a Public Hub. Track hubs require remotely hosted data. They use binary index
files which allow the browser to quickly access only what is relevant for the current region being
viewed in the browser. See the track hub help
page for more information.
Custom annotation tracks are similar to standard tracks, but never become part of the MySQL genome
database. Each track has its own controller and persists even when not displayed in the Genome
Browser window, e.g., if the position changes to a range that no longer includes the track.
Typically, custom annotation tracks are aligned under corresponding genomic sequence, but they can
also be completely unrelated to the data. For example, a track can be displayed under a long
sequence consisting of millions of Ns.
Genome Browser annotation tracks are based on files in line-oriented format. Each line in the file
defines a display characteristic for the track or defines a data item within the track. Annotation
files contain three types of lines: browser lines, track lines, and data lines. Empty lines and
those starting with "#" are ignored.
To construct an annotation file and display it in the Genome Browser, follow these steps:
Step 1. Format the data set
Formulate your data set as a tab-separated file using one of the formats supported by the Genome
Browser. Annotation data can be in standard
GFF format or in a format designed specifically for
the Human Genome Project or UCSC Genome Browser, including
bedGraph,
GTF,
PSL,
BED,
bigBed, WIG,
bigGenePred,
bigMaf,
bigChain,
bigPsl,
barChart,
bigBarChart,
bigWig,
BAM,
CRAM,
VCF,
MAF,
BED detail,
Personal Genome SNP,
broadPeak,
narrowPeak,
and microarray
(BED15). GFF and GTF files must be tab-delimited rather than space-delimited to display
correctly. Chromosome references must be of the form chrN (the parsing of chromosome names
is case-sensitive). You may include more than one data set in your
annotation file; these need not be in the same format.
Step 2. Define the Genome Browser display characteristics
Add one or more optional browser lines to the beginning of your formatted data
file to configure the overall display of the Genome Browser when it initially shows your annotation
data. Browser lines allow you to configure such things as the genome position that the Genome
Browser will initially open to, the width of the display, and the configuration of the other
annotation tracks that are shown (or hidden) in the initial display. NOTE: If the browser position
is not explicitly set in the annotation file, the initial display will default to the position
setting most recently used by the user, which may not be an appropriate position for viewing the
annotation track.
Step 3. Define the annotation track display characteristics
Following the browser lines--and immediately preceding the formatted data--add a
track line to define the display attributes for your annotation data set. Track
lines enable you to define annotation track characteristics such as the name, description, colors,
initial display mode, use score, etc. The track type=<track_type>
attribute is required for some tracks. If you have included more than one data set in your
annotation file, insert a track line at the beginning of each new set of data.
Example #1:
Here is an example of a simple annotation file that contains a list of chromosome coordinates.
browser position chr22:20100000-20100900
track name=coords description="Chromosome coordinates list" visibility=2
chr22 20100000 20100100
chr22 20100011 20100200
chr22 20100215 20100400
chr22 20100350 20100500
chr22 20100700 20100800
chr22 20100700 20100900
Click here to view this track in the Genome Browser.
Example #2:
Here is an example of an annotation file that defines 2 separate annotation tracks in BED format.
The first track displays blue one-base tick marks every 10000 bases on chr 22. The second track
displays red 100-base features alternating with blank space in the same region of chr 22.
browser position chr22:20100000-20140000
track name=spacer description="Blue ticks every 10000 bases" color=0,0,255,
chr22 20100000 20100001
chr22 20110000 20110001
chr22 20120000 20120001
track name=even description="Red ticks every 100 bases, skip 100" color=255,0,0
chr22 20100000 20100100 first
chr22 20100200 20100300 second
chr22 20100400 20100500 third
Click here to view this track in the Genome Browser.
Example #3A:
This example shows an annotation file containing one data set in BED format. The track displays
features with multiple blocks, a thick end and thin end, and hatch marks indicating the direction of
transcription. The track labels display in green (0,128,0), and the gray level of the each feature
reflects the score value of that line. NOTE: The track name line in this example has been split over
2 lines for documentation purposes. If you paste this example into the Genome Browser, you must
remove the line break to display the track successfully. Click here for a copy of this example that can be pasted into the browser without
editing.
browser position chr22:1000-10000
browser hide all
track name="BED track" description="BED format custom track example" visibility=2
color=0,128,0 useScore=1
chr22 1000 5000 itemA 960 + 1100 4700 0 2 1567,1488, 0,2512
chr22 2000 7000 itemB 200 - 2200 6950 0 4 433,100,550,1500 0,500,2000,3500
Click
here to view this track in the Genome Browser.
Example 3B:
This example shows a simple annotation file containing one data set in the bigBed format. This track
displays random sized blocks across chr21 in the human genome. The big data formats, such as the
bigBed format, can be uploaded using a bigDataUrl that is specified in the track line. For more
information on these track line parameters, refer to the Track Lines
section.
You may paste these two lines directly into the "Add Custom Tracks" page to view this example in the
browser:
browser position chr21:33,031,597-33,041,570
track type=bigBed name="bigBed Example One" description="A bigBed file" bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb
Alternatively, you may also upload just the URL of the bigBed file:
http://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb
This will infer the track type as "bigBed" based on the file extension and set the track
name to "bigBedExample".
Step 4. Display your annotation track in the Genome Browser
To view your annotation data in the Genome Browser, open the Genome Browser
home page and click the Genome Browser link in the
top menu bar. On the Gateway page that displays, select the
genome and assembly on which your annotation data is based, then click the "add custom
tracks" button. (Note: if the Gateway displays the "manage custom tracks" button
instead, see Displaying and Managing Custom Tracks for information on how
to display your track.)
On the Add Custom Tracks page, load the annotation track data or URL for your custom track into the
upper text box and the track documentation (optional) into the lower text box, then click the
Submit button. Tracks may be loaded by entering text, a URL, or a pathname on your local computer.
The track type=<track_type> attribute is required for some tracks.
For more information on these methods, as well as information on creating and adding track
documentation, see Loading a Custom Track into the Genome Browser.
If you encounter difficulties displaying your annotation, read the section
Troubleshooting Annotation Display Problems.
Step 5. (Optional) Add details pages for individual track features
After you've constructed your track and have successfully displayed it in the Genome Browser, you
may wish to customize the details pages for individual track features. The Genome Browser
automatically creates a default details page for each feature in the track containing the feature's
name, position information, and a link to the corresponding DNA sequence. To view the details page
for a feature in your custom annotation track (in full, pack, or squish display mode), click on the
item's label in the annotation track window.
You can add a link from a details page to an external web page containing additional information
about the feature by using the track line url attribute. In the annotation file, set the
url attribute in the track line to point to a publicly available page on a web server. The
url attribute substitutes each occurrence of '$$' in the URL string with the name defined
by the name attribute. You can take advantage of this feature to provide individualized
information for each feature in your track by creating HTML anchors that correspond to the feature
names in your web page.
Example 4:
Here is an example of a file in which the url attribute has been set to point to the file
http://genome.ucsc.edu/goldenPath/help/clones.html. The
'#$$' appended to the end of the file name in the example points to the HTML NAME tag within the
file that matches the name of the feature (cloneA, cloneB, etc.). NOTE: The track line in this
example has been split over 2 lines for documentation purposes. If you paste this example into the
browser, you must remove the line break to display the track successfully. Click
here for a copy of this example that can be
pasted into the browser without editing.
browser position chr22:10000000-10020000
browser hide all
track name=clones description="Clones" visibility=2
color=0,128,0 useScore=1
url="http://genome.ucsc.edu/goldenPath/help/clones.html#$$"
chr22 10000000 10004000 cloneA 960
chr22 10002000 10006000 cloneB 200
chr22 10005000 10009000 cloneC 700
chr22 10006000 10010000 cloneD 600
chr22 10011000 10015000 cloneE 300
chr22 10012000 10017000 cloneF 100
Click
here to display this track in the Genome Browser.
Step 6. (Optional) Share your annotation track with others
The previous steps showed you how to upload annotation data for your own use on your own machine.
However, many users would like to share their annotation data with members of their research group
on different machines or with colleagues at other sites. To learn how to make your Genome Browser
annotation track viewable by others, read the section Sharing Your Annotation Track
with Others.
Loading a custom track into the Genome Browser
Using the Genome Browser's custom track upload and management utility, annotation tracks may be
added for display in the Genome Browser, deleted from the Genome Browser, or updated with new data
and/or display options. You may also use this interface to upload and manage custom track sets for
multiple genome assemblies.
To load a custom track into the Genome Browser:
Step 1. Open the Add Custom Tracks page
Select the top blue bar "My Data" menu and click Custom
Tracks. Or, when browsing tracks, click the "add custom tracks" button below the
Genome Browser. (Note: if one or more tracks have already
been uploaded during the current Browser session, additional tracks may be loaded on the Manage
Custom Tracks page. In this case, the button on the Browser page will be labeled "manage
custom tracks" and will automatically direct you to the track management page. See
Displaying and Managing Custom Tracks for more information.)
Step 2. Load the custom track data
The Add Custom Tracks page contains separate sections for uploading custom track data and optional
custom track descriptive documentation. Load the annotation data into the upper section by one of
the following methods:
-
Enter one or more URLs for custom tracks (one per line) in the data text box. The Genome Browser
supports both the HTTP and FTP (passive-only) protocols.
-
Data provided by a URL may need to be proceeded by a separate line defining
type=<track_type> required for some tracks, for example such as
"track type=broadPeak".
-
Click the "Browse" button directly above the data text box, then choose a custom track
file from your local computer, or type the pathname of the file into the "upload" text
box adjacent to the "Browse" button. The custom track data may be compressed by any of
the following programs: gzip (.gz), compress (.Z), or bzip2 (.bz2).
Files containing compressed data must include the appropriate suffix in their names.
-
Paste or type the custom track data directly into the data box. Because the text in this box will
not be saved to a file, this method is not recommended unless you have a copy of the data
elsewhere.
Multiple custom tracks may be uploaded at one time on the Add Custom Tracks page through one of the
following methods:
-
Put all the tracks into the same file (rather than separate files), then load the file via the
Browse button.
-
Place your track files in a web-accessible location on your server, then load them into the Genome
Browser by pasting their URLs into the data box.
NOTE: Please limit the number of custom tracks that you upload and maintain to less
than 1000 tracks. If you have more than this suggested limit of 1000 tracks, please consider
setting up a track hub instead.
Step 3. (Optional) Load the custom track description page
If desired, you can provide optional descriptive text (in plain or HTML format) to accompany your
custom track. This text will be displayed when a user clicks the track's description button on the
Genome Browser annotation tracks page. Descriptive text may be loaded by one of the following
methods:
-
Click the "Browse" button directly above the documentation text box, then choose a text
file from your local computer, or type the pathname of the file into the "upload" text
box adjacent to the "Browse" button.
-
Paste or type the custom track data directly into the data box. Note that the text in this box
will not be saved to a file; therefore, this method is not recommended except for temporary
documentation purposes.
-
If your descriptive text is located on a website, you can reference it from your custom track file
by defining the track line attribute "htmlUrl":
htmlUrl=<external_url>. In this case, there is no need to insert
anything into the documentation text box.
To format your description page in a style that is consistent with standard Genome Browser tracks,
click the template link below the documentation text box for an HTML template that may be copied and pasted into a file for editing.
If you load multiple custom tracks simultaneously using one of the methods described in Step 2, a
track description can be associated only with the last custom track loaded, unless you upload the
descriptive text using the track line "htmlUrl" attribute described above.
Step 4. Upload the track
Click the Submit button to load your custom track data and documentation into the Genome
Browser. If the track uploads successfully, you will be directed to the custom track management page
where you can display your track, update an uploaded track, add more tracks, or delete uploaded
tracks. If the Genome Browser encounters a problem while loading your track, it will display an
error. See the section Troubleshooting Annotation Display Problems for help
in diagnosing custom track problems.
NOTE: Please limit the number of custom tracks that you upload and maintain to less
than 1000 tracks. If you have more than this suggested limit of 1000 tracks, please consider
setting up a track hub instead.
Displaying and managing custom tracks
After a custom track has been successfully loaded into the Genome Browser, you can display it -- as
well as manage your entire custom track set -- via the options on the Manage Custom Tracks page.
This page automatically displays when a track has been uploaded into the Genome Browser (see
Loading a Custom Track into the Genome Browser). Alternatively, you can
access the track management page by clicking the "manage custom tracks" button on the
Gateway or Genome Browser annotation tracks pages. (Note that the track management page is available
only if at least one track has been loaded during the current browser session; otherwise, this
button is labeled "add custom tracks" and opens the Add Custom Track page.)
The table on the Manage Custom Tracks page shows the current set of uploaded custom tracks for the
genome and assembly specified at the top of the page. If tracks have been loaded for more than one
genome assembly, pulldown lists are displayed; to view the uploaded tracks for a different assembly,
select the desired genome and assembly option from the lists.
The following track information is displayed in the Manage Custom Tracks table:
-
Name: a hyperlink to the Update Custom Track page where you can update your
track configuration and data.
-
Description: the value of the "description" attribute from the track
line, if present. If no description is included in the input file, this field contains the track
name.
-
Type: the track type, determined by the Browser based on the format of the
data.
-
Doc: displays "Y" (Yes) if a description page has been uploaded for the
track; otherwise the field is blank.
-
Items: the number of data items in the custom track file. An item count is not
displayed for tracks lacking individual items (e.g. wiggle format data).
-
Pos: the default chromosomal position defined by the track file in either the
browser line "position" attribute or the first data line. Click this link to open the
Genome Browser or Table Browser at the specified position (Note: only the chromosome name is shown
in this column). The Pos column remains blank if the track lacks individual items (e.g. wiggle
format data) and the browser line "position" attribute hasn't been set.
Displaying a custom track in the Genome Browser
Click the "go to genome browser" button to display the entire custom track set for the
specified genome assembly in the Genome Browser. By default, the browser will open to the position
specified in the browser line "position" attribute or first data line of the first custom
track in the table, or the last-accessed Genome Browser position if the track is in wiggle data
format. To open the display at the default position for another track in the list, click the track's
position link in the Pos column.
Viewing a custom track in the Table Browser
Click the "go to table browser" button to access the data for the custom track set in the
Table Browser. The custom tracks will be listed in the "Custom Tracks" group pulldown
list.
Loading additional custom tracks
To load a new custom track into the currently displayed track set, click the "add custom
tracks" button. To change the genome assembly to which the track should be added, select the
appropriate options from the pulldown lists at the top of the page. For instructions on adding a
custom track on the Add Custom Tracks page, see Loading a Custom Track into the
Genome Browser.
Removing one or more custom tracks
To remove custom tracks from the uploaded track set, click the checkboxes in the "delete"
column for all tracks you wish to remove, then click the "delete" button. A custom track
may also be removed by clicking the "Remove custom track" button on the track's
description page. Note: removing the track from the Genome Browser does not delete the track file
from your server or local disk.
Updating a custom track
To update the stored information for a loaded custom track, click the track's link in the
"Name" column in the Manage Custom Tracks table. A custom track may also be updated by
clicking the "Update custom track" button on the track's description page.
The Update Custom Track page provides sections for modifying the track configuration information
(the browser lines and track lines), the annotation data, and the descriptive documentation that
accompanies the track. Existing track configuration lines are displayed in the top "Edit
configuration" text box. In the current implementation of this utility, the existing annotation
data is not displayed. Because of this, the data cannot be incrementally edited through this
interface, but instead must be fully replaced using one of the data entry methods described in
Loading a Custom Track into the Genome Browser. If description text has been
uploaded for the track, it will be displayed in the track documentation edit box, where it may be
edited or completely replaced. Once you have completed your updates, click the Submit button to
upload the new data into the Genome Browser.
If the data or description text for your custom track was originally loaded from a file on your hard
disk or server, you should first edit the file, then reload it from the Update Custom Track page
using the "Browse" button. Note that edits made on this page to description text uploaded
from a file will not be saved to the original file on your computer or server. Because of this, we
recommend that you use the documentation edit box only for changes made to text that was typed or
pasted in.
Browser lines
Browser lines configure the overall display of the Genome Browser window when your annotation file
is uploaded. Each line defines one display attribute. Browser lines consist of the format:
browser attribute_name attribute_value(s)
For example, if the browser line browser position chr22:1-20000
is included in the
annotation file, the Genome Browser window will initially display the first 20000 bases of chr
22.
The following browser line attribute name/value options are available. The value
track_primary_table_name must be set to the name of the primary table on which the
track is based. To identify this table, open up the
Table Browser,
select the correct genome assembly, then select the track name from the
track list. The table list will show the primary table.
Alternatively, the primary table name can be obtained from a mouseover on the
track name in the track control section.
You can also find instructions on how to find this table name in the video
"How do I learn which tables
belong to a data track on the UCSC Genome Browser?".
Note that composite track subtracks are not valid track_primary_table_name values. To find
the symbolic name of a composite track, look in the tableName field in the trackDb
table, or mouse over the track name in the track control section. It is not possible to display only
a subset of the subtracks at this time.
-
position <position> - Determines the part of the genome that the Genome
Browser will initially open to, in chromosome:start-end format.
-
hide all - Hides all annotation tracks except for those listed in the custom
track file.
-
hide <track_primary_table_name(s)> - Hides the listed tracks.
Multiple track names should be space-separated.
-
dense all - Displays all tracks in dense mode. NOTE: Use the "all"
option cautiously. If the browser display includes a large number of tracks or a large position
range, this option may overload your browser's resources and cause an error or timeout.
-
dense <track_primary_table_name(s)> - Displays the specified
tracks in dense mode. Symbolic names must be used. Multiple track names should be
space-separated.
-
pack all - Displays all tracks in pack mode. See NOTE for "dense
all".
- pack <track_primary_table_name(s)> - Displays the specified
tracks in pack mode. Symbolic names must be used. Multiple track names should be
space-separated.
-
squish all - Displays all tracks in squish mode. See NOTE for "dense
all".
-
squish <track_primary_table_name(s)> - Displays the specified
tracks in squish mode. Symbolic names must be used. Multiple track names should be
space-separated.
-
full all - Displays all tracks in full mode. See NOTE for "dense
all".
-
full <track_primary_table_name(s)> - Displays the specified tracks
in full mode. Symbolic names must be used. Multiple track names should be space-separated.
Definition: <track_primary_table_name(s)>. You can find the primary
table name by clicking "View Table Schema" from the track's description page, or from the Table
Browser. It will be listed as the Primary Table. Alternatively, you can mouse-over the track label
in the Browser and look at the URL the link points to. The part after the g= in the URL is the
track's primary table name (e.g., for UCSC Genes you will see g=knownGene in the URL. The track
primary table is knownGene).
Note that the Genome Browser will open to the range defined in the Gateway page search term
box or the position saved as the default unless the browser line position attribute is defined in
the annotation file. Although this attribute is optional, it's recommended that you set this value
in your annotation file to ensure that the track will appear in the display range when it is
uploaded into the Genome Browser.
Track lines
Track lines define the display attributes for all lines in an annotation data set. If more than one
data set is included in the annotation file, each group of data must be preceded by a track line
that describes the display characteristics for that set of data. A track line begins with the word
track
, followed by one or more attribute=value
pairs. Unlike browser
lines - in which each attribute is defined on a separate line - all of the track attributes for a
given set of data are listed on one line with no line breaks. The inadvertent insertion of
a line break into a track line will generate an error when you attempt to upload the annotation
track into the Genome Browser.
The following track line attribute=value pairs are defined in the Genome Browser:
-
name=<track_label> - Defines the track label that will be displayed to
the left of the track in the Genome Browser window, and also the label of the track control at the
bottom of the screen. The name can consist of up to 15 characters, and must be enclosed in quotes
if the text contains spaces. We recommend that the track_label be restricted to alpha-numeric
characters and spaces to avoid potential parsing problems. The default value is "User
Track".
-
description=<center_label> - Defines the center label of the track in
the Genome Browser window. The description can consist of up to 60 characters, and must be
enclosed in quotes if the text contains spaces. The default value is "User Supplied
Track".
-
type=<track_type> - Defines the track type. The track type attribute is
required for BAM,
BED detail,
bedGraph,
bigBed,
bigWig,
broadPeak,
narrowPeak,
Microarray,
VCF and
WIG tracks.
-
visibility=<display_mode> - Defines the initial display mode of the
annotation track. Values for display_mode include: 0 - hide, 1 - dense, 2 - full, 3 -
pack, and 4 - squish. The numerical values or the words can be used, i.e., full mode may be
specified by "2" or "full". The default is "1".
-
color=<RRR,GGG,BBB> - Defines the main color for the annotation track.
The track color consists of three comma-separated RGB values from 0-255. The default value is
0,0,0 (black).
-
itemRgb=On - If this attribute is present and is set to "On", the
Genome Browser will use the RGB value shown in the itemRgb field in each data line of
the associated BED track to determine the display color of the data on that line.
-
colorByStrand=<RRR,GGG,BBB RRR,GGG,BBB> - Sets colors for + and -
strands, in that order. The colors consist of three comma-separated RGB values from 0-255 each.
The default is 0,0,0 0,0,0 (both black).
-
useScore=<use_score> - If this attribute is present and is set to 1,
the score field in each of the track's data lines will be used to determine the level of
shading in which the data is displayed. The track will display in shades of gray unless the
color attribute is set to 100,50,0 (shades of brown) or 0,60,120 (shades of blue). The
default setting for useScore is "0". This table shows the Genome Browser's
translation of BED score values into shades of gray:
shade |
|
|
|
|
|
|
|
|
|
score in range |
≤ 166 |
167-277 |
278-388 |
389-499 |
500-611 |
612-722 |
723-833 |
834-944 |
≥ 945 |
-
group=<group> - Defines the annotation track group in which the custom
track will display in the Genome Browser window. By default, group is set to
"user", which causes custom tracks to display at the top of the track listing in the
group "Custom Tracks". The value for "group" must be the
"name" of one of the predefined track groups. To get a list of allowable group names for
an assembly, go to the table browser and select "group: All Tables" "table:
grp" and "get output" Entries in the "name" column may be used.
(Note that mirrors may define other group names in the grp table.)
-
priority=<priority> - When the group attribute is set, defines
the display position of the track relative to other tracks within the same group in the Genome
Browser window. If group is not set, the priority attribute defines the track's
order relative to other custom tracks displayed in the default group, "user".
-
db=<UCSC_assembly_name> - When set, indicates the specific genome
assembly for which the annotation data is intended; the custom track manager will display an error
if a user attempts to load the track onto a different assembly. Any valid UCSC assembly ID may be
used (eg. hg18, mm8, felCat1, etc.). The default setting is blank, allowing the custom
track to be displayed on any assembly.
-
offset=<offset> - Defines a number to be added to all coordinates in the
annotation track. The default is "0".
-
maxItems=<#> - Defines the maximum number of items the track can
contain. The default value is 250. Be aware that tracks with an extremely large number of items
can cause system instability. The
Kent source
utility bedItemOverlapCount can assist in analyzing base overlap with large tracks.
-
url=<external_url> - Defines a URL for an external link associated with
this track. This URL will be used in the details page for the track. Any "$$"in this
string this will be substituted with the item name. There is no default for this attribute.
-
htmlUrl=<external_url> - Defines a URL for an HTML description page to
be displayed with this track. There is no default for this attribute. A template for a standard
format HTML track description is here.
-
bigDataUrl=<external_url> - Defines a URL to the data file for
BAM,
CRAM,
bigBed,
bigWig or
VCF tracks. This is a required attribute for those
track types. There is no default for this attribute.
Here is an example of a properly formatted track line using the bigBed format, with accompanying
browser line:
browser position chr21:33,031,597-33,041,570
track type=bigBed name="bigBed Example One" description="A bigBed file" bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb
Sharing your annotation track with others
To make your Genome Browser annotation track viewable by people on other machines or at other sites,
follow the steps below. (Note that some of the URL examples in this section have been broken up into
2 lines for documentation display purposes).
Step 1. Put your formatted annotation file on your web site. Be sure that the file
permissions allow it to be read by others.
Step 2. Construct a URL that will link this annotation file to the Genome Browser.
The URL must contain 3 pieces of information specific to your annotation data:
-
The species or genome assembly on which your annotation data is based. To automatically display
the most recent assembly for a given organism, set the org parameter: e.g.
org=human
. To specify a particular genome assembly for an organism, use the
db parameter, db=database_name
, where database_name is the UCSC
code for the genome assembly. For a list of these codes, see the Genome Browser
FAQ. Examples of this include:
db=hg16 (Human July 2003 assembly), db=mm6 (Mouse Mar. 2005 assembly).
-
The genome position to which the Genome Browser should initially open. This information is of the
form
position=chr_position
, where chr_position is a chromosome number, with
or without a set of coordinates. Examples of this include: position=chr22,
position=chr22:15916196-31832390.
-
The URL of the annotation file on your web site. This information is of the form
hgt.customText=URL
, where URL points to the annotation file on your website.
An example of an annotation file URL is http://genome.ucsc.edu/goldenPath/help/test.bed.
You can add other optional parameters to the URL: (Note: Display may vary if you have conflicting
cart variables, for example having both hide all and highlight features.)
-
hgFind.matches=listOfNames
- highlight features given their names -
example link to highlight two transcripts of the ABO gene
-
<trackName>=full|dense|pack|hide
- show the default tracks adding a track and
set it to full, dense, pack or hide visibility -
example link to show the default or user-selected tracks and set the
Chromosome Bands track to "pack" view. Please note that for this feature to work with
custom tracks you must use their unique assigned name and identifier number
ct_name_####
, only with the full custom track name will this feature work:
ct_name_####=full
-
hideTracks=1
- hide all tracks -
example link to show no tracks at all
-
hideTracks=1&<trackName>=full|dense|pack|hide
- hide all tracks and show
other tracks -
example link to show only the Chromosome Bands track and nothing else
-
hgt.reset=1
- show only the default tracks -
example link
-
hgt.toggleRevCmplDisp=1
- show the reverse-complement -
example link to show the reverse-complement of the ABO gene
-
oligoMatch=pack&hgt.oligoMatch=DNASEQ
- switch on the Short Match track and
highlight a matching sequence -
example link to highlight the TATAWAR motif in the ABO locus
-
highlight=<DB>.<CHROM>:<START>-<END>#<COLOR>|...
-
highlight one or more regions in a given color on the image. Note that the arguments have to be
URL-encoded for Internet browsers, so ":" becomes "%3A", "#"
becomes "%23" and "|" becomes "%7"C. -
example link to highlight two parts of the ABO locus in red and blue.
-
pix=<number>
- set the width of the image in pixels -
example link to create a 300-pixel wide image
-
hgt.labelWidth=<number>
- set the size of the left-side label area -
example link to increase the label area to 50 characters
-
textSize=<number>
- set the size of text font -
example link to increase the text font size to 12 pixels
-
guidelines=on/off
- activate or deactivate the blue guidelines -
example link to switch off blue guidelines
-
enableHighlightingDialog=0/1
- activate or deactivate the highlighting/zoom
dialog - example link to default to zoom mode and switch off the highlight
dialog
If a login and password is required to access data loaded through a URL (e.g., via https:
protocol), this information can be included in the URL using the format
protocol://user:password@server.com/somepath. Only Basic Authentication is supported for HTTP.
Note that passwords included in URLs are not protected. If a password contains a non-alphanumeric
character, such as $, the character must be replaced by the hexadecimal representation for
that character. For example, in the password mypwd$wk, the $ character should be replaced
by %24, resulting in the modified password mypwd%24wk.
For integration into your own website e.g. in an html IFRAME, you can obtain the track image only,
without the rest of the genome browser user interface, by replacing hgTracks in the URL with
hgRenderTracks, like in this example:
http://genome.ucsc.edu/cgi-bin/hgRenderTracks?db=hg19&position=chr9%3A136130563-136150630
Combine the above pieces of information into a URL of the following format (the information
specific to your annotation file is highlighted):
http://genome.ucsc.edu/cgi-bin/hgTracks?org=organism_name&position=chr_position&hgt.customText=URL
Example 10:
The following URL will open up the Genome Browser window to display chr 22 of the latest human
genome assembly and will show the annotation track pointed to by the URL
http://genome.ucsc.edu/goldenPath/help/test.bed:
http://genome.ucsc.edu/cgi-bin/hgTracks?org=human&position=chr22&hgt.customText=http://genome.ucsc.edu/goldenPath/help/test.bed
Step 3. Provide the URL to others. To upload a custom annotation track pointed to
by a URL into the Genome Browser, paste the URL into the large text edit box on the Add Custom
Tracks page, then click the Submit button.
If you'd like to share your annotation track with a broader audience, send the URL for your
track—along with a description of the format, methods, and data used—to the UCSC Genome
mailing list
genome@soe.ucsc.edu.
Example 11:
If you would like to share a URL that your colleague can click on directly, rather than loading it
in the Custom Track tool (as in Example 10), then the URL will need a few extra parameters. Let's
assume that your data is on a server at your institution in one of the large data formats:
bigBed,
bigWig,
BAM,
CRAM, or
VCF.
In this case, the URL must include an hgct_customText
parameter, which
simulates the text box on the Custom Tracks page. Also, the URL must include
the bigDataUrl
that points to the data file on your server.
So, a clickable URL that opens a remote bigBed track for the hg18 assembly to a certain location on
chr21 would look like this:
http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg18&position=chr21:33038447-33041505&hgct_customText
=track%20type=bigBed%20name=myBigBedTrack%20description=%22a%20bigBed%20track%22%20visibility=
full%20bigDataUrl=http://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb
Custom Tracks can also be shared with others through named sessions. First, upload your tracks as
discussed in the Loading a Custom Track into the Genome Browser section. Then create a named session that includes your custom tracks by navigating to the "Sessions"
page through the "My Data" section in the menu bar. Once there, follow the instructions in the
Creating a Session section of the Sessions help page.
Once you have saved your custom track into a named session, you can share that session with others
by sharing the URL from the "Browser" link or emailing it to them directly by clicking
the "Email" link.
Tip: Multiple tracks can be placed into one custom track submission. To do so,
create a new file that contains the
track lines to each file that will be
included. To submit this custom set of tracks, merely use the URL to this new file.
Troubleshooting annotation display problems
Occasionally users encounter problems when uploading annotation files to the Genome Browser. In
most cases, these problems are caused by errors in the format of the annotation file and can be
tracked down using the information displayed in the error message. This section contains suggestions
for resolving common display problems. If you are still unable to successfully display your
data, please contact
genome@soe.ucsc.edu
for further assistance.
Messages sent to this address will be posted to the moderated genome mailing list, which is
archived on a SEARCHABLE, PUBLIC
Google Groups
forum.
Problem: When I try one of your examples by cutting and pasting it into
the Genome Browser, I get an error message.
Solution: Check that none of the browser lines, track lines, or data lines
in your annotation file contains a line break. If the example contains GFF or GTF data lines, check
that all the fields are tab-separated rather than space-separated.
Problem: When I click the submit button, I get the error message "line 1 of custom input:".
Solution: Check that none of the browser lines, track lines, or data
lines in your annotation file contains a line break. A common source for this problem is the track
line: all of the attribute pairs must on the same line and must not be separated by a line break.
If you are uploading your annotation file by pasting it into the text box on the Genome Browser
Gateway page, check that the cut-and-paste operation did not inadvertently insert unwanted line
feeds into the longer lines.
Problem: When I click the submit button, I get the error message
"line # of custom input: missing = in var/val pair".
Solution: Check for incorrect syntax in the track lines in the annotation
file. Be sure that each track line attribute pair consists of the format
attribute=attribute name.
Problem: When I click the submit button, I get the error message
"line # of custom input: BED chromStarts[i] must be in ascending order".
Solution: This is most likely caused by a logical conflict in the Genome
Browse software. It accepts custom GFF tracks that have multiple "exons" at the same
position, but not BED tracks. Because the browser translates GFF tracks to BED format before
storing the custom track data, GFF tracks with multiple exons will case an error when the BED is
read back in. To work around this problem, remove duplicate lines in the GFF track.
Problem: When I click the submit button, the Genome Browser
track window displays OK, but my track isn't visible.
Solution: Check the browser and track lines in your annotation file to
make sure that you haven't accidentally set the display mode for the track to hide. If you
are using the Annotation File box on the Genome Browser Gateway page to upload the track, check that
you've entered the correct file name. If neither of these is the cause of the problem, try resetting
the Genome Browser to clear any settings that may be preventing the annotation to display. To reset
the Genome Browser, click the Click here to reset link on the Gateway page. If the
annotation track still doesn't display, you may need to clear the cookies in your Internet browser
as well (refer to your Internet browser's documentation for further information).
Problem: I am trying to upload some custom tracks (.gz files) to the
Genome Browser using a URL from a GEO query. However, the upload is failing with the error
"line 1 of .gz: thickStart after thickEnd".
Solution: The custom track mechanism supports plain BED files (not bigBed)
that are of the type broadPeak or
narrowPeak. Set the track attribute
type=<track_type> to enable the loader to correctly process the
special columns at the end of each line. Your track type entry should consist of two lines: the
first to define the track type and the second to specify the URL. For example:
track type=broadPeak
http://www.ncbi.nlm.nih.gov/geosuppl/...
Problem: I've gotten my annotation track to display, but now I can't make
it go away! How do I remove an annotation track from my Genome Browser display?
Solution: To remove only one track, click the Manage Custom
Tracks button and delete the desired track using the checkbox and Delete button. To quickly
remove all of your custom tracks, reset the Genome Browser to its default settings by clicking the
Click here to reset link on the Gateway page. Note that this reset will also remove any
other customizations you have made to your Genome Browser display.
Problem: I put my custom track files on Google Drive and they won't
display in the browser. Why?
OR
Problem: When I try to visualize my custom tracks in the Browser, I
receive the error message "Byte-range request was ignored by server".
Solution: Data servers (such as Google Drive) used to work for hosting
simple text-based custom tracks, but things have changed. For large custom track data sets, the use
of indexed binary formats such as bigBed and bigWig is preferable but never worked with Google Drive
and often fail with other free data providers. These formats provide much faster display performance
because only the portion of the file needed to display the currently viewed region must be
transferred to the Genome Browser server. To allow this type of display, byte-range support must be
enabled on the data server. To check if your server has byte-range requests enabled, issue the
following command:
> curl -I <URL of your file>
In order for your server to host bigBed and bigWig files (or track hubs) for Genome Browser display,
the command output must contain:
> Accept-Ranges: bytes
If you do not receive this output, you may be able to resolve the problem through one of the
following actions:
-
Check with the systems administrators about the configuration of the server. This will often
solve the problem.
-
Find another site with a server that supports byte-ranges.
-
Install an Apache alternative http server such as Cherokee.
Please note that this does not constitute an endorsement by UCSC for using Google Drive to host
your data.
Problem: I used to host files on Dropbox which used to accept byte-range
requests, but I can't get my data to display. Why?
Solution: Dropbox recently changed the ability to stream large amounts of
data making binary files hosted there inaccessible to the browser. If you use Dropbox for smaller
text based track hubs you need to enable the "Public Folder" function on Dropbox, rather
than using the "Share Link" function. For custom tracks that require an associated index
file, the Public Folder approach will allow the Browser to locate the file, whereas the Share Link
feature creates a unique, unassociated link for each file. To enable your Dropbox public folder,
navigate to the following site: https://www.dropbox.com/enable_public_folder. If you are using a free Dropbox
account, note that Dropbox may throttle access to your data to prevent their servers from becoming
overloaded; this may in turn block the Genome Browser's access to the data, preventing the display
of your tracks. Paid Dropbox accounts may not experience this problem. Also, keep in mind that
files in your Dropbox Public Folder are public, and therefore may be indexed by Google. Please note
that this does not constitute an endorsement by UCSC for using Dropbox to host your
data.