v2 code release - URL parsing and persistent hyperlinks

UPDATE December 27th, 2012:
URL parameter function described in this post has gone void as new specifications are in use since Version 13, see this post for details:
http://washugb.blogspot.com/2012/12/url-parameter-specification-effective.html




Today we're very happy to release our second version of Wash U Epigenome Browser. Go to source code archive page and download subtleKnife.v2.tgz to get the code.

New features

You can now supply parameters through URL as a way to control browser behavior, just like good-old CGI programs do.

Very quickly, click following link and see how it works:

http://epigenomegateway.wustl.edu/browser/?genome=hg19&datahub=http://remc.wustl.edu/xzhou/hub.txt

Once clicked, the browser will be displayed showing human hg19 genome, and tracks from the sample data hub.

Expected use of this feature is for users to obtain persistent hyperlinks to current browsing status, and share it to collaborators. Also external web sites can provide links and button to direct users to visit our browser with customized display information (e.g. a specific composition of custom tracks hosted on external websites).

Indeed, URL with parameter is an alternative to session function. The URL could be truly persistent, as it doesn't require any kind of storage to keep it valid. But with session, its information must be kept in the database, and thus could be deleted and become invalid. Though using URL user might has to deal with really long URL strings, but with "session" parameter, the URL can be very short and handy.

The composition of such URL is:

[base URL] + '?' + [key1] + '=' + [value1] + '&' + [key2] + '=' + [value2] + '&' + [more key/values pairs]

Explanations:

1. Base URL is http://epigenomegateway.wustl.edu/browser/.
2. '?' the question mark must be present and immediately follows base URL.
3. Key and value are joined by '=', and multiple key/value pairs are joined by '&'.

Following is Key/Value specification. All keys are case-insensitive:

• "genome", the name of genome to display, allowed values are:
• hg19 (human)
• mm9 (mouse)
• danRer7 (zebrafish)
• dm3 (fruitfly)
• tair10 (arabidopsis)
• "session", to restore a saved session. Value is session id string
• "statusid" value is status ID, this parameter is used in conjugation with "session"
• "metadata", to decide which metadata terms are to be displayed in metadata color map. Value is comma joined metadata term names (experimental, only leaf terms have been tested to work in this way)
• "coordinate", to decide specific genomic position the browser should be displaying. Value is coordinate string in form of chr1:5000-6000
• "juxtapose", to run juxtaposition on a bigBed track. Value has two possibilities:
• if supplying URL, the URL must points to a valid bigBed file. Additional parameter "juxtaposecustom=on" must be supplied as well.
• if using native genomic feature track to run juxtaposition, valid track name must be provided (experimental, the list of bigBed tracks is not explicitly given but can be found in config/hg19/makeDb.sql file)
• "geneset", to run Gene Set View. Value is comma separated gene names. This parameter should not be used with "coordinate" or "juxtapose".
• "datahub", to display tracks from a data hub. Value is URL to a data hub descriptor file
• "hmtk", to display specific native heatmap tracks. Value is comma separated native heatmap track names (experimental, the list of native heatmap tracks is not explicitly given but can be found in config/hg19/track2Detail file)
• "customhmtk", to display custom heatmap tracks. Value is in form of "name1,url1,name2,url2,...", where name/url is to define one custom heatmap track. All fields are joined by comma, so track name must not contain comma.
• "gftk", to display specific native genomic feature tracks. Value is in form of "name1,mode1,name2,mode2,...", where name/mode is to define display of one native genomic feature track. Mode must be one of thin/full/density (experimental)
• "customgftk", to display custom genomic feature tracks. Value is in form of "name1,url1,mode1,name2,url2,mode2,...". It has almost same requirement as above.
• "bam", to display BAM tracks hosted on our server. This function is experimental because we are still working to align and generate BAM files for every heatmap tracks.
• "custombam" to display custom BAM tracks, value is in form of "name1,url1,mode1,name2,url2,mode2,...". It has identical requirement as "customgftk".

In next code release we expect the browser to be able to automatically generate URL as a snapshot of current browsing status.

Bug fix

1. The situation of no term displayed in metadata color map now works with session saving/restore.
2. The browser now tolerates empty lines in data hub descriptor file.
3. When no track is displayed in genome heatmap, clicking "add track" button in pairwise comparison panel won't encounter error. A warning message will be printed out in message console complaining there's no track to choose from.

Minor changes

In the track selection panel, custom genomic feature tracks and BAM tracks are presented in following new way:

Click the new tabs "Genomic features / custom" and "Read alignments / custom" to see tracks of these types.

In Bird's Eye View panel, left click the wiggle plot image to show a small context menu (but not right click):