Broad: Annotation: Argo: Applet

What is the Argo Applet?

The Argo Applet is a minimal version of the Argo Genome Browser that can be embedded in an html page as a java applet. We use this applet on our own site to display our own data, but you can easily use it on your own site to display your own data. This document describes how.

What does the Argo Applet look like?

The argo applet will not work on all browsers. It requires the java plugin 1.4.1 or highter. The first time you click on one of the links below it may take a little while to load. Your browser then caches the applet and subsequent visits will be faster.

  1. View the applet on some static test data.
  2. View the applet on some dynamic live data.
  3. View the the applet as we actually use it on our site.

Here is a screenshot:

Quick start: download the applet, html, and test data.

Into the same directory, download:

  1. the applet jar.
  2. the html.
  3. the 3 data files: sequence, tracks, features.

Open the static.html file in your web browser to run the applet locally. Modify or swap out the data files to see your own data.

The Applet Parameters

Besides some standard applet setup parameters, argo applet requires just three more. They are sequence, feature, and track. Each takes a URL, relative or absolute, that the applet will use to retrieve the sequence, feature, and track information it needs.

Example:

<PARAM NAME = "features" VALUE   = "features.gff3" >
<PARAM NAME = "tracks"   VALUE   = "tracks.tab" >
<PARAM NAME = "sequence" VALUE   = "sequence.fa" >

Note that because "applets can only phone home" these data files must be on the same webserver as the applet. Each data file format is described below.

In addition to the above minimal, required parameters, there are three optional parameters, described below: menu, ruler, splitStrands.

The Sequence File Format

The sequence file must be in fasta format with a specially formatted header. The specially formatted header consists of the following 6 tab delimited fields:

  1. sequence id
  2. segment start
  3. segment stop
  4. sequence length
  5. sequence alphabet - (dna or protein)
  6. sequence label

Segment start and stop are useful if you are pointing at a fasta file that contains a small section of a much larger sequence (say, a region of a human chromosome). By setting the segment start and stop appropriately, your features can still use chromosomal coordinates. If you are looking at an entire sequence just set the segment start to 1 and the stop to the sequence length, as in the example below.

Example:

>7000000000506641    1    8805    8805    dna    Neurospora crassa contig 3.698

Sample Sequence File.

Note: tab characters, not spaces, must be used as delimiters.

The Feature File Format

The feature file format used by the argo applet is a subset of gff3. It is a subset because argo only supports only a two level parent-child hierarchy instead of the unlimited number that gff3 permits. In addition, tracking is based on the parent feature. The tracks assigned to subfeatures are ignored. Field 2 ("source") is used for track assignment. See the next section for more on what this means.

gff3 spec

The following example shows how a 3 exon transcript and a simple repeat feature might be represented:

##gff-version	3
##sequence-region	7000000000506641	1	8805
7000000000506641	ANNOTATED	mRNA	5974	6485	.	-	.	ID=7000000009318382;Name=(NCU09983.1)%20predicted%20protein
7000000000506641	ANNOTATED	exon	5974	5991	.	-	.	Parent=7000000009318382;
7000000000506641	ANNOTATED	exon	6286	6298	.	-	.	Parent=7000000009318382;
7000000000506641	ANNOTATED	exon	6472	6485	.	-	.	Parent=7000000009318382;
7000000000506641	REPEAT	mRNA	1	210	.	+	.	ID=7000000014971588;Name=Repeat%20of%20multiplicity%202%2C%20cluster%20ID%207000000000083202

Argo ignores the value in field 3 ("method"), but note that the gff3 spec requires that it be part of a controlled vocabulary.

Note that values in the attribute field (field 9) must be URI escaped.

Sample Feature File.

Warning: Argo will not handle more than 2 levels of feature hierarchy gracefully. This is an issue we are actively looking into.

The Track File Format

The track file contains information about how to display features for each track identifier and what url, if any, to open when they are clicked. Each value in the gff3 feature file column #2 must have a corresponding entry in the track file. The format is tab delimited with the following 4 fields (3 required, 1 optional):

  1. Track id (corresponds to values in gff3 feature file column #2)
  2. Track color (hexadecimal)
  3. Track label
  4. URL to open when features of this track are double clicked (optional). This may be a static url or a template url where alphanumeric values preceded by a dollar sign are treated as placeholders for the interpolation of corresponding feature values. Placeholders are case insensitive. Placeholders may be any key in the gff3 attribute column.
  5. Template URL to use for editing features of this track (optional, see editing, below)

The order of the entries in the track file determines the sort order in which features of that track will be displayed in the argo applet. In the default split strand view, features will be stranded toward the strand boundary (more or less the middle of the screen). In the optional unsplit view, features are sorted toward the top of the screen.

Example:

ANNOTATED	00FFFF	Annotated Transcript	/cgi-bin/annotation/neurospora/findfeatures.cgi?page=fulldetail&FEATUREID=$id
BLASTX	00FF00	BlastX
BLASTN	FFFFCC	BlastN
REPEAT	CCCCCC	Repeat

Javascript URLS are also supported. Example:

ANNOTATED	00FFFF	Annotated Transcript	javascript:alert('The id of the feature you just clicked on is $id')

This is useful if you want argo to cooperate with an html form.

Sample Track File.

Custom Menus (optional)

You can add custom functionality to the argo applet by listing custom menu action template urls to open for selected features.

Each custom menu is describe in a file whose location is given to the applet the menu parameter.

Example:

<PARAM NAME = "menu" VALUE = "menu.tab" >

The first row in the custom menu file gives the name of the menu.

Additional rows in this file describe individual menu items and are 4 column tab delimited. The first column contains the menu item action label, the second column indicates whether multiple features may be operated on or just one (* or 1), the third column contains the comma dilimited track ids (*=all) that may be operated on, and the fourth column contains the template url for this action.

Operating on Sequence Columns: Sequence columns are temporary glyphs created when the user drags along the sequence ruler. Use the track id 'COLUMN' to indicate that an action may operate on sequence columns. The '*' does not include sequence columns. To operator on both all features and sequence columns, use '*,COLUMN'

Example:

Custom
Action #1	*	*	http://www.broad.mit.edu/annotation/cgi-bin/test.cgi?id=$id
INSERT PRIMER	1	COLUMN	http://www.broad.mit.edu/annotation/cgi-bin/insert-primer.cgi?sequence=$sequence&start=$start&stop=$stop&strand=$strand
DELETE PRIMER	*	PRIMER	http://www.broad.mit.edu/annotation/cgi-bin/delete-primer.cgi?id=$id
UPDATE PRIMER	1	PRIMER	http://www.broad.mit.edu/annotation/cgi-bin/update-primer.cgi?id=$id&start=$start&stop=$stop&strand=$strand

The template url is the same format that is used in the track file specified above. But if multiple features are selected, multiple url parameters will be interpolated.

See a custom menu in action here.

Rulers (optional)

You can add rulers to the argo applet by specifying ruler data urls and labels using the ruler parameter.

The format of the custom ruler file is 2 column tab delimited. The first column contains the sequence position, the second a numberic value associated with this position.

See a custom menu in action here.

(Un)Split Strands (optional)

By default, argo splits features up by strand. Positive strand features go on top, negative strand features go on the bottom. This may not make sense for you data. To disable this behavior, use the splitStrands applet parameter and give it a value of "0."

Example:

<PARAM NAME = "splitStrands" VALUE = "0" >

Contact: Reinhard Engels
argo-support@broad.mit.edu