DAVIEWER Manual

The latest source code can be found on Github here.

Table of Contents:

  1. Building DaViewer
  2. DaViewer Interface Elements
  3. Menu/Toolbar Commands
  4. Open Dialog
  5. Palette Dialog
    1. Basic Tab
    2. Quality Tab
    3. Masks Tab
  6. Display Area Interaction
  7. Queries
  8. Views

Building DaViewer:

To build DaViewer you will need to download the latest (free) version of the Qt library which you can get here.  Once Qt is installed you will need to set the shell variable QTDIR to the path at which you chose to install the Qt library.  I set this variable in the shell file .login at my root so that every time I open a UNIX command line window, Qt is known.  Another good spot to set this shell variable is .cshrc (for bash) or your shell’s equivalent.

To make the viewer you must first utter “qmake viewer.pro” in the directory to which you downloaded the module.  qmake is a Qt program (much like configure) that constructs a Makefile from the specification given in viewer.pro.  You then simply say “make” and hopefully the compiles all go off without complaint.  You should then find the DaViewer application in the folder, which you can launch by double clicking it.

DaViewer Interface Elements:

When initially launched the viewer presents menu elements in the native style of the OS and opens a single window that contains a toolbar at the upper border, a viewing area that has zoom and scroll sliders for both the vertical and horizontal axes, and a query panel at the bottom border.  The zoom sliders set the magnification for the horizontal and vertical axes of the display, and the scroll sliders (that adjust the page bar in response to the associated zoom) allow you to scroll in the relevant dimensions.  When zoomed all the way out, the entire current data set is displayed.  At maximum zoom, 30 horizontal lines are displayed in the vertical dimension, and 1000bp are displayed in the horizontal direction.Screen Shot 2016-06-01 at 5.40.05 PMMenu/Toolbar Commands:

The complete set of menu options is shown in the figure below in the style of Mac OS X.  Most commands have a keyboard short-cut shown to the right of the selection, and the five most common commands are in the tool bar and the menus as indicated by the common icon for the operation shown immediately to the left of the command name in the menus.  Pressing the toolbar button has the same effect as selecting the command in the corresponding menu or typing the corresponding keyboard short cut.

Screen Shot 2016-06-18 at 8.24.29 PMDaViewer Menu: This menu contains Mac-specific options save for the the “Quit DaViewer” command which closes all viewer menus, saves the current palette to your preferences if a user view is not in effect, and quits the application.

Open: Opens an input dialog explained in detail below, where in a user asks the viewer to input and view a particular data set.

Palette: The viewer has the concept of a palette which specifies all the options/choices for viewing a data set included the colors of various objects.  This comman opens a dialog where in a user can modify a palette and create named views of a particular palette setting.

“Duplicate”: Opens another viewing window with exactly the same contents as the current active window.  The new window is placed over the active window, slightly lower and slightly to the left on your screen.

“Hide/Shows Query”: If “Hide” then the query panel disappears in all windows and the menu command is changed to its “Show” version.  If “Show” then the query panel reappears in all windows and the menu command reverts to its “Hide” version.

“Hide/Shows Toolbar”: If “Hide” then the toolbar disappears in all windows and the menu command is changed to its “Show” version.  If “Show” then the toolbar reappears in all windows and the menu command reverts to its “Hide” version.

“Tile”: Arrange on-screen windows into a tiling of the screen, maximizing each window to the degree possible.

“Cascade”: Arrange the window into a cascade of overlapping windows with the active window on top.

“Window” Menu:  Mac OS X convention commands for managing the open windows of the viewer.

Open Dialog:

Activating the Open command from the toolbar, keyboard, Screen Shot 2016-06-02 at 10.56.05 PMor menus opens this dialog.  An example is shown immediately at right.  A DaViewer data set consists of a sorted .las file containing the local alignments (LAs) of a number of overlap piles and the underlying database or database pair that was compared or mapped to produce the .las file.  In the example at right, the overlap piles for the first block of DB ECNEW will be opened as soon as the Open button is pressed in the dialog.

The LA file, A-database, and B-database (if the box to its left is checked) can be input either by directly typing in the path to the desired file, or by clicking tScreen Shot 2016-06-02 at 10.58.47 PMhe Pick button, which opens a system file dialog with which you can navigate and select the desired file, where the type (.las, .db, or .dam) of the file is enforced.  The given data set becomes the current data set and is shown in the display area if the Open button is pressed or if the return key is typed.  If the Cancel button is pressed then the current data set remains unchanged.  The snapshot at right shows an example where both the A- and the B-databases (one is a DAM the other a DB) are required.  In this case the piles are with respect to the contigs of DAM K12 and the B-reads in each pile are from the DB ECNEW.

Screen Shot 2016-06-02 at 10.59.22 PMThe current data set can further be a subset of the A database specified by checking the box at left on the Reads line and then entering the range (inclusive) of A-reads desired.  One can also request that the palette of a specific view (see section on Views) be used to display the new data set.  The dialog at right gives an example of both a subset and a selected view.

Palette Dialog:

Screen Shot 2016-06-17 at 3.22.15 PMThe color and display of objects is quite flexible and controlled by the settings in the Palette dialog.  Activating the Palette command from the toolbar, keyboard, or menus opens this dialog which consists of three separate tabs Basic, Quality, and Masks, and a common view control area at the bottom.  One can adjust various settings controlling the display in the dialog which will take effect when the OK button is pressed or the return key is typed (upon which the dialog also closes).  Closing the dialog with the Cancel button ignores any adjustments made, the palette remains unchanged.  In this section, just the graphic display options settable in the tab panes will be described.  View control is described at the end of this document in the section entitled “Views”.

Palette Dialog: Basic Tab

An example of the Palette dialog with the Basic tab displayed is shown immediately above.  In the top segment of the Basic tab area, one can set the color of (a) the display area Background, (b) Reference (or A-) read lines (and also the scale annotations at the bottom of the display), (c) all Aligned (or B-read) segments, (d) Unaligned branch tips, (e) Grid lines, and (e) the Hilight hover.  When sufficiently zoomed in on a data set for it to be reasonable and sensible to do so, (a) vertical, dashed grid lines are displayed to help one understand the reference read relative positions of objects, and (b) when the mouse hovers over an aligned segment it is hilighted in the specified hover color along with all other segments involving the same B-read.  Both of these features can be turned on or off with the check box to the left of its color box.

Daviewer displays pile-o-grams, which are representations of how all of the reads in a data set align to a given A-read.  The piles are displayed for the A-reads in order from the first to last, left to right, as set when the data set was opened.  In the scene below A-reads 91 to 100 and their piles are in the field of view.  The long gold-yellow bar at the top represents the A-read and every white bar below it represents the A-interval of an alignment of the A-read with another (B-)read.  The brown branch tips indicate that the B-read continues but does not align with the A-read  (note that some white bars have brown tips, others do not).  At the bottom of the display area is a ruler which at the given level of magnification displays a gold bar with the number of the read below it at left.  Once can also see dashed lines (red and cyan hued) between white alignment bars which are drawn in response to the Show overlaps and Show bridges options in the Basic tab.

Screen Shot 2016-06-17 at 4.33.03 PMConsider the situation where a B-read has multiple distinct locally-aligned segments with a particular A-read.  This could arise because of repetitive sequence, or it could arise because the quality of the A- or B-read is so bad in some parts that the overall alignment between the two reads is interrupted by the low quality sequence.  In the later event, it will be the case that the amount of sequence in A and B, say Alen and Blen, between the two local alignments on either side of the bad stretch, are of comparable length.  In such an instance we say the the gap can be bridged and would like to think of the two local alignments as one chained alignment.  With the the Show bridges option set, a dashed line is drawn between the two white local alignment bars indicating the relationship. Similarly, albeit more rarely, two local alignments will actually overlap and in a consistent manner in terms of the amount of overlapped sequence, Alen and Blen, in A and B and with the Show overlaps option set, this relationship will also be shown by a dashed line under the interval of overlap.

The gap/overlap lengths, Alen and Blen, for both bridge and overlap patterns are never exactly the same so one must specify the maximum amount of compression and expansion in the in the relative ratio of Blen to Alen.  Moreover, color ramps from the maximum permitted compression, to perfectly relaxed (Alen=Blen), and from relaxed to the maximum permitted stretch are specified by setting the color at each extreme in the 3 color boxes below the labels.  For the panel above, a max compression and stretch of 30% is specified, i.e. .7*Alen <= Blen <= 1.3*Alen, with a maximally compressed (Blen = .7*Alen) connector drawn as red-dashed line, a perfectly relaxed connector as a white-dashed line, and a maximally stretched (Blen = 1.3*Alen) connector as a cyan-dashed line, with proportionate color ramping for intermediate compression/stretch ratios.  In the example below, the mouse was pressed on the left of the two white bars in a chain that is hilighted in cyan (the hover color) resulting in the display of a popup menu which indicates that the two alignments are between the intervals [0,2448] and [3476,5999} of read 95 (the A-read), and the intervals [7532,5308] and [4420,1687] of read 1997 (the B-read), respectively.  The B-read coordinates decrease indicating it is complemented relative A, and the compressed connector has Alen = 1028 and Blen = 888.  Finally note that the approximate interval [2500,3500] of the A-read is covered by numerous compressed chains, and the approximate interval [6700,6800] of the A-read is covered by numerous stretched chains.  The fact that most alignments chain across these gaps consistently (with respect to stretch/compress ratio) signals that the regions are likely low quality portions of the A-read.Screen Shot 2016-06-25 at 3.07.10 PMWith the introduction of damapper, .las files so produced are already organized into chains.  If such a file is given to DaViewer then the chaining is taken from the file and only the visibility and coloring of the chain dashes is controlled by the settings in the Basic Tab.  The compression and stretch maximums used by damapper is 40% and the numbers in the line edits of the control are ignored.

Palette Dialog: Quality Tab

For every local alignment, daligner computes and stores the number of differences between the reads every T bases of the A-read, where T is the trace-point spacing set by the -s parameter to daligner (which has a default value of 100).  If the Show match qv’s checkbox is set in the Quality tab (shown below right) then when one is sufficiently zoomed in each segment of T bases in an alignment is colored aScreen Shot 2016-06-17 at 3.13.08 PMccording to either a Tri-State threshold scheme or a color Ramp depending on which of the two radio buttons below the checkbox is selected.

If a color ramp scheme is chosen then 10 color boxes appear below the radio buttons and each box specifies the color of a 5% interval of the possible difference percentiles, where the left-most box corresponds to 0-5%, the next box to 5-10%, and so on to the right-most box which corresponds to 45-100%.  The difference percentile of a trace point interval is the number of difference between the A- and B-read in that interval multiplied by 100/T.

If a tri-state scheme is chosen then 3 color boxes appear below the radio button along with line-edits under the left and rightmost boxes.  Any segment with a percentile not greater than the value in the leftmost line-edit is considered “good” and colored according to the leftmost box, any percentile not less than the value in the rightmost line-edit is considered “bad” and colored according to the rightmost box, and any other percentile is considered “uncertain” and colored according to the middle color box.  In the example above right, a tri-state control is shown for the “Show qual qv’s” option which similarly takes a coloring scheme like the “Show match qv’s” option.

If one has run DASqv on a dataset to produce a .qual track for the reads, then Daviewer will automatically find the track when the data set is opened, and will display options for coloring trace point intervals of the A-read according to the intrinsic quality value assigned to each interval by DASqv.  The options are exactly as for match intervals save that it is the intervals of the A-read line that are colored, and not the intervals of the local alignment lines below it.  However, if the “on B” checkbox is set, then the intrinsic quality value of the relevant intervals of the B-reads are displayed on the local alignment lines, and the “Show match qv’s checkbox is turned off (as one cannot simultaneously display both).

Screen Shot 2016-06-18 at 8.43.00 PMIn the panel above, find 3 snippets of piles where the A-read line and local alignment line segments are colored according to the setting shown immediately below each.

If one has run damapper on a dataset with the -p option to produce a .prof track for the reads, then Daviewer will automatically find the track when the data set is opened, and will give you options for displaying and coloring a repeat profile ofScreen Shot 2016-07-31 at 6.19.55 PM the A-reads in the Quality Tab.  As shown at right the controls are analogous to those for match and qual qv’s save that the ramp option only has 5 levels corresponding to 1, 2-10, 11-20, 21-30, and 31-40.  Recall profile values are floor(log10 c/10) when is the estimated repeat copy number c > 1, so in terms of copy number the 5 levels correspond to 1, 2-10, 11-100, 101-1000, and 1001-10,000 (or above).  Segments of a read that matched nothing have a score of 0 and are not displayed.  The profile is displayed just below the A-read when sufficiently zoomed in in both the horizontal and vertical axes.  If the vertical zoom is sufficient to allow it, the higher copy numbers are displayed in thicker lines as illustrated below.

Screen Shot 2016-07-31 at 6.30.48 PM

Palette Dialog: Masks Tab

Many commands such as DBdust, TANmask, REPmask, and DAStrim produce Dazzler database tracks that are specifically interval tracks in that they encode a collection of intervals over each read in the data base.  When a new data Screen Shot 2016-06-17 at 3.13.52 PMset is opened, daviewer, searches for and finds all interval tracks that have been created with respect to the A-database of the data set and presents controls for their display in the Masks tab of the Palette dialog as illustrated at right.  For each interval track there is a row that from left-to-right consists of: (a) a double-arrow move icon, (b) a check box that determine whether the track is displayed, (c) a combo-box with which one can set the register on which the track is displayed, (d) an “on B” option which when checked displays the intervals also on the B-coordinates of the alignment lines, (e) a color box with which one sets the display color, and (f) the name of the track.  Normally, the tracks are displayed as line segments in the coordinate system of the A-read.  Conceptually, the A-read line is on register 0, and there are an unbounded number of registers above register 0, numbered consecutively from 0, on which one can draw track lines.  As in the example, there are often so many tracks that one might wish to order their display in the Mask tab.  One can move the rows for each track, by depressing the Screen Shot 2016-06-25 at 3.07.24 PMmove double arrow icon of a track control at left and then dragging and dropping the row where you would like it.    For example, at right the user has depressed the “keep” track’s movement icon, at which time the row’s widgets were re-displayed as inactive and a thick blue proxy bar appears and begins to track the cursor as long as the mouse button is depressed.  The cursor and proxy bar are currently between the split and adapt tracks, and if the user were to release the button at this moment, then the keep track would be placed between them and its widgets redrawn as active.  We conclude with a couple of examples below of the display of tracks according to the Mask tab example, where the “hq“, “span“, and “split” tracks are all drawn on register 1, “hole“‘s are drawn on register 2, and the intervals “keep” in register 3.

Screen Shot 2016-06-23 at 1.50.41 PMScreen Shot 2016-06-23 at 1.50.50 PMDisplay Area Interaction:

Mouse actions within the drawing area provide for (a) mouse centered zoom in and out along the horizontal axes, (b) direct scrolling in the vertical and horizontal directions by grab and drag, (c) popup menus detailing the coordinates of selected items, (d) hoover hilighting, and (e) the ability to hilight all alignment bars involving a given B-read in a selected color.

The ruler is the bar or set of bars at the bottom of the drawing area where one sees read numbers, grid coordinates, etc.  The figure below illustrates it.  A mouse click below the Screen Shot 2016-06-25 at 5.15.31 PMruler line causes the display to zoom in horizontally by a factor of 1.4, where the point clicked will be at the center of the screen when the display is updated.  A shift-mouse click below the ruler line causes the display to zoom out horizontally by a factor of .7, where the point clicked will be at the center of the screen the display is updated.

Hovering over an alignment bar causes it, and any alignment segments it is chained to, to be hilighted in the color specified in the Basic tab of the Palette Dialog.  The example immediately below illustrates a chain with two segmeScreen Shot 2016-06-25 at 3.04.15 PMnts hilighted in cyan where the mouse is over the rightmost segment.  If the mouse is clicked on an alignment segment, then a popup menu appears as further illustrated in the example. On the first two lines, the popup menu shows the A- and B-end coordinates of each alignment segment in the hilighted chain with the gap or overlap distances shown between segment coordinates.  If B is reverse complemented then B-coordinates decrease (as in the example).

The third line of the popup is actually a command and releasing the mouse when it is over this item, i.e. selecting “Color”, causes a color dialog to appear.  The color that is picked then hilights every alignment segment that involves the same B-read as the one from selected segment.  In the example, the B-read is 11346 and the rose color hilight is shown in the screen shot below.  We call this a custom hilight.

Screen Shot 2016-06-25 at 3.04.40 PMAlso in the screen shot above, a mouse click on the A-read has caused a one line popup to appear giving the read number and its length as an interval that always begins with 0.  Clicking on any displayed mask intervalScreen Shot 2016-06-25 at 3.04.51 PM causes a one line popup to appear giving the mask name and the coordinates of the mask interval as in the screen shot immediately above.  Finally, one can turn off a custom hilight, by selecting the “Uncolor” item that appears in the popup menu when any alignment segment with the custom hilight color is selected.  The screen shot below illustrates the modified popup menu.

Screen Shot 2016-06-25 at 3.04.29 PMLastly, one can grab and drag the drawing area by clicking and holding down the mouse at any point that is part of the display background.  The drag takes effect in both the horizontal and vertical dimensions.

Queries:

The query pane, if currently visible, is at the bottom of the Daviewer window and consists of a Query button at left and a expanding double line edit box at right.  A query can be typed into the top line edit and pressing either return or pressing the Query button performs the search.  If there is a syntax error in the query, a message appears in red in the second line with a carat symbol pointing to the location of the error as shown in the illustration below.Screen Shot 2016-06-25 at 10.26.05 PMCurrently, queries are limited to either giving an integer read number or two integer read numbers with a – between them.  In response, daviewer adjusts the horizontal zoom and scroll so that the given read, or range of reads appears in the display area.  In the example, reads 1-10 occupy the field of view.

Views:

A view is simply a specific setting of all the Palette controls.  A view has a name, and selecting a view’s name in the popup menu of the combo-box labelled “Screen Shot 2016-06-17 at 3.22.15 PMViews:” at the bottom of the Open dialog or the Palette dialog has the effect of setting all the Palette controls to those for the view.  One can create, modify, and delete views with the controls at the bottom of the Palette dialog shown in the screen shot at right.  The current view is the one shown in the Views combo box, and by default is “Preferences” which is the settings saved at the end of your last session.

Clicking the “Add” button opens a small dialog that asks you to enter the name you would like to give to a new view.  The name will be added to the popup menu of the Views combo box, becomes the current view, and its settings are those of the Palette dialog at the moment the view is added.  Clicking the “Update” button modifies the settings associated of the current view to those of the Palette.  Clicking the “Delete” button will delete the current view from the list of possible views after first asking you in a modal dialog if you are sure you want to do so.  Obviously, updating or deleting “Preferences” has no effect.