Accessing the Genome Browser Programmatically Part 3 – Controlling the Genome Browser Image

The previous parts of this series (part 1 and part 2) focused on how to use the Genome Browser to obtain data, and for this third and final post we’re gonna divert from that theme and talk about how to control the track image itself. Note: We now have an API which can also perform many of these functions.

Standard procedure for obtaining images of the browser is to configure the view exactly as you want, and then use the “View->PDF/PS” option in the menu bar in order to download a PDF or PostScript of your image. In addition to this method, you can generate PNG images on the fly with the following hgRenderTracks template:
http://genome.ucsc.edu/cgi-bin/hgRenderTracks?parameters

Parameters should be replaced by the URL key-value pairs that the main track display, hgTracks, understands, like ‘db=hg19’ or ‘knownGene=pack’. For example, to compare the transcripts provided by NCBI to UCSC’s own alignments of the transcripts at the ABO locus, you can use the following URL and the cURL program to download a PNG file:

curl 'http://genome.ucsc.edu/cgi-bin/hgRenderTracks?db=hg19&position=chr9:136130563-136150630&hideTracks=1&refSeqComposite=pack&ncbiRefSeqCurated_sel=1&ucscRefSeqView=pack&refGene_sel=1&pubs=pack' > example.png

Opening example.png in your favorite image viewer will display the following image:

There are many additional parameters described on the Sharing your custom track section of the custom tracks help page. Using these parameters you can configure hgRenderTracks to display any combinations of tracks, and along the hgt.customText parameter, also show your custom tracks with them.

To illustrate, if I have the following custom track:

browser hide all
browser gold=pack
browser gap=pack
browser visibility=pack
chr1 1000 2000
chr1 2100 3000
chr1 3100 4000
…

Hosted on the web at http://genome-test.soe.ucsc.edu/~chmalee/exCustomTrack.bed, then I can tell hgRenderTracks to load this file with the hgt.customText parameter like so:

http://genome.ucsc.edu/cgi-bin/hgRenderTracks?db=hg38&position=chr1:1-100000&hgt.customText=http://genome-test.soe.ucsc.edu/~chmalee/exCustomTrack.bed

The “browser” lines at the beginning of the custom track indicate which native tracks to turn on along their visibilities, while the “hide all” line turns all the other native tracks off. In addition to these basic instructions there are many more examples on the UCSC Genome Browser Wiki.

What about when you want to view a genome and annotations not hosted on our site? If you have a FASTA file of your genome available, you can use faToTwoBit to convert your genome into a 2bit file, then make an assembly hub out of your data. Once you’ve created your hub, you can view the hub with the hubUrl setting. As an example, I have hosted an assembly hub for Arabadopsis thaliana here, and I can view the hub via a single URL like so:

https://genome.ucsc.edu/cgi-bin/hgTracks?genome=araTha1&hubUrl=https://genome-test.gi.ucsc.edu/~chmalee/araTha1/plantAraTha1/hub.txt.

If your data needs to stay behind your local firewall, then you can use the GBiB and GBiC products so you can set up your own “copy” of the UCSC Genome Browser that meets your privacy needs.

Further Reading:

If after reading this blog post you have any public questions, please email genome@soe.ucsc.edu. All messages sent to that address are archived on a publicly accessible forum. If your question includes sensitive data, you may send it instead to genome-www@soe.ucsc.edu.

2 thoughts on “Accessing the Genome Browser Programmatically Part 3 – Controlling the Genome Browser Image”

Rekha March 19, 2019 at 10:12 pm

Hi,

I am trying to download images for tracks other than defaults ones for e.g. CpG islands via curl from GBiC server. What are the parameters I need to give? Please advise.

Brian Lee March 20, 2019 at 2:31 pm

Dear Rekha,

Thank you for your question about obtaining an image of specific tracks. Please know our mailing list genome@soe.ucsc.edu is always available for questions.

You can look to this section about optional parameters that will help you guide how to build a URL to the Browser to specify certain tracks:
http://genome.ucsc.edu/goldenPath/help/customTrack.html#optParams

For example, if you were not interested in the default tracks and only wanted to display a specific track you would use the hideTracks=1&=full|dense|pack|hide approach. In this case, you are interested in only the CpG Islands track (cpgIslandExt), that exists within another track super track (cpgIslandSuper). This following URL will hide all tracks and then turn on that super track and then also the underlying CpG island track:

http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hideTracks=1&cpgIslandSuper=full&cpgIslandExt=pack

You could add other tracks of interest as well, such as GC percent

http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hideTracks=1&cpgIslandSuper=full&cpgIslandExt=pack&gc5BaseBw=full

Or you could also attach a hub and display specific subtracks of a hub. In this case the GTEx Hub (note it will only display on the genome.ucsc.edu website as access to the hub is restricted to certain IP ranges):

http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hideTracks=1&cpgIslandSuper=full&cpgIslandExt=pack&gc5BaseBw=full&hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt&gtexRnaSignalFemaleYoung_hideKids=1&gtexRnaSignalFemaleYoung=full&gtexRnaSignalSRR1311348=full&ignoreCookie=1

This hub example is also using a feature in the URL ignoreCookie=1 because it uses a new feature compositeTrackName_hideKids=1 that hides subtracks within a composite, that the hideTracks=1 parameter will not necessarily hide.

With the Browser looking as you desire, you can change the /hgTracks/ section to /hgRenderTracks/ and pull down just the image:

curl ‘http://genome.ucsc.edu/cgi-bin/hgRenderTracks?db=hg38&hideTracks=1&cpgIslandSuper=full&cpgIslandExt=pack&gc5BaseBw=full&hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt&gtexRnaSignalFemaleYoung_hideKids=1&gtexRnaSignalFemaleYoung=full&gtexRnaSignalSRR1311348=full&ignoreCookie=1&position=chr10:67,884,669-67,918,390’ > SIRT1_snapshot.png

This SIRT1_snapshot.png image shows data for a gene SIRT1 in the position chr10:67,884,669-67,918,390 with just a specific subtrack from the GTEx hub displayed and the GC Percent Track and CpG island track turned on. To learn the names of tracks, you can navigate to their track description pages and look for the g= value in the URL, such as for the GC Percent track:

http://genome.ucsc.edu/cgi-bin/hgTrackUi?db=hg38&g=gc5BaseBw

The gc5BaseBw is the unique track name given to this track. In a similar fashion, if you have built a track hub and know the unique track names (or visit the trackDb.txt to find the names, and note they are not necessarily equivalent with the shortLabel) you can call specific tracks to display by the URL as well. The compositeTrackName_hideKids=1 feature is only needed when you are dealing with a composite group of tracks and want to hide all the default displaying tracks.

Thank you again for your inquiry and using the UCSC Genome Browser. If you have any further public questions, please send them to genome@soe.ucsc.edu. All messages sent to that address are archived on a publicly-accessible forum. If your question includes sensitive data, you may send it instead to genome-www@soe.ucsc.edu.

Comments are closed.