HgTracks multi-region changes

This page provides an overview of the changes made to hgTracks and the position cart variable by Galt when implementing multi-region (a.k.a. "exon-mostly") display mode. It began as part of code review #16514 by Angie. Instead of adding these notes to the Redmine ticket, I am putting them in the wiki so that Galt can correct any of my misunderstandings, and hopefully this will serve as a rough guide for any developers who will need to interact with this code in the future.

The big merge of code changes for the initial implementation of multi-region display is 8c908f948b; see also http://genecats.cse.ucsc.edu/git-reports-history/v327/review/user/galt/index.html

hgTracks has always operated on the assumption that the user is viewing a single region of some reference assembly sequence. There are global variables for that region and global variables for layout parameters of a single region image. These global variables are referenced throughout all tracks' drawing code. Track loaders fetch data from a single region. Galt implemented multi-region display in a way that barely touched the bulk of hgTracks code -- quite an accomplishment! -- partly by introducing new structures and loops, and partly by carefully overwriting the pre-existing global variables. Developers working on loading and drawing code in the future can mostly ignore those changes and continue using the old globals in the same way as before. However, there may be cases in which track handlers will have to make use of data from all regions (for example, wiggle auto-scale). Developers who add a new global variable will have to decide whether it needs to be updated every time the current region changes. But hopefully they'll not add any more globals.  :)

Multi-region display UI

There is a new button underneath the browser image, labeled 'multi-region'. Clicking it produces a pop-up with options for multi-region display. In the initial version there is a radio button set as shown below, followed by a checkbox that controls whether the regions are visually separated by thin red lines (the default) or highlighting alternating regions.

(*) Show single-chromosome view (default)

( ) Show exons or ( ) genes using GENCODE v22. Use padding of: [6] bases.

( ) Custom regions from BED URL: [ ]

( ) Show one alternate haplotype, placed on its chromosome, using ID: [ chr1_KI270762v1_alt ]

[ ] Highlight alternating regions in multi-region view

The 'Show exons or genes' line appears only when a suitable gene table can be identified. The 'Show one alternate haplotype' option appears only when there is an altLocations sql table.

Within the four main options, there are additional parameters:

• a fifth mode option to omit regions between genes instead of between exons; default unselected
• the padding option for exon or gene mode; default 6
• the URL for a BED file (with optional multi-region-specific settings) provided by the user; default empty
• an alternate haplotype ID; default is "chr6_cox_hap2" or if not applicable, the first item in the altLocations table

There are also two new keyboard bindings: 'e v' changes the mode to 'Show exons' and 'd v' changes the mode to single-region.

The code includes several addition modes not shown above, mostly "demo" modes for testing during development. Since those are not reachable by users, I won't describe those.

Changes to the position cart variable (and hence other CGIs)

Before multi-region, the position variable was either a search term to be resolved or a chromosomal region spec. Once resolved, it had the form seq:start-end, and always began with a sequence name that could be found in the current db's chromInfo table, and had start and end coordinates relatiev to that assembly sequence. Now, when viewing custom regions from the user or an alt haplotype, the position cart var begins with virt and its start and end coordinates are for a "virtual chromosome" constructed by joining all regions.

The virt:start-end form does not (yet) make sense to any other CGI besides hgTracks, so some code has been added to the beginning of each CGI that uses the position variable to detect virt: at the beginning; if found, it swaps in the value of a new cart variable, nonVirtPosition.

Code changes

Needless to say, changing a paradigm in hgTracks involves adding and changing a lot of code.