GS Amplicon Variant Analyzer Application Interface Overview

1.1.3

The top of the main AVA window shows the name and path of the Amplicon Project being displayed; and a set of seven main buttons are located along the right-hand side of the window. The rest of the AVA window is occupied by a selection of tabs, described in the sections below.

•

Make sure to set the resolution of your computer screen to at least 1024x768 pixels (1280x1024 recommended), or the AVA application may not be able to display all the features described below. If the resolution is too low (or if the application window or one of its constituent tabbed panels are resized too small), the software attempts to prioritize which feature to omit. For example, the Global Align tab may not show the color code legend on its lower-left corner; or the button column to the left of the Variation Frequency Plot on the top panel of the Global Align or the Consensus Align tabs may not show the “Save plot data to spreadsheet file” and/or the “Save plot snapshot to image file” buttons. While program features may be omitted in this way, scrollbars are used as needed to ensure that all data is viewable regardless of the screen resolution or window size.

•

The AVA software also features a Command Line Interface (CLI) that may be more appropriate for large Projects, especially when large amounts of data need to be imported into, exported from, or automated within a Project. See section 3 for a full description of the CLI, the language that was developed for it, and all the commands it includes.

1.1.3.1

Main Buttons

Seven main buttons are always visible, along the right-hand side of the GS Amplicon Variant Analyzer window (Save and Back are grayed-out when their function is not applicable, e.g. no Project changes to save):

Icon	Description
	The Exit button closes the AVA application.
	The New button opens a “New Amplicon Project” window in which you can provide a name for a new Project, as well as a file-system location where to save it and a free-text description (Figure 1‑2). Clicking “OK” in the “New Amplicon Project” window initializes the Project and takes you to the Project Tab of your new Project. For more details on Project initialization, see section 4.4. (See section 2.2.2 for more details on ways to create a new Project, especially synchronizing the Project and Location names, and navigating your file-system using the “folder” icon to the right of the ‘Location’ field.)
	The Open button allows you to browse your file-system to find an existing Amplicon Project and open it in the AVA application.
	The Save button saves the current state of the Project to the disk, i.e. all the primary elements and their associations.
	The Back button takes you back to the previous AVA view. (Note that this button does not carry an “undo” function; see Note, below.)
	The About button opens a splash screen providing some information about the AVA application. (Click the “Close” button to close it).
	The Help button opens an electronic version of the user manual.

The AVA software does not offer the possibility to “undo” an action such as a computation, an element definition entry, a display selection in a multi-alignment view, etc. In some cases, the opposite action or a “clear” action may be available. You can also revert to the last saved state of the Project by re-opening the Project without first clicking the “Save” button.

Saving vs. computing a project: Saving a Project does NOT update the results displayed in the Variants, Global Align, Consensus Align or Flowgrams tabs. To update these displays after making changes in a Project, you must re-compute it. Conversely, these results do not require that you save the Project to persist in the Project.

Figure 1‑2: The New Amplicon Project window, with fields to enter a Project’s name, file-system location, and textual description. If the “Generate location based on name” box is checked, typing a Project’s name in the Name field also enters it at the end of the path in the Location field. Be aware that later changing the name of the Project from within the application will NOT change the name of the folder that contains it, causing a mismatch between the two; a mismatch would also occur if the “Generate location based on name” box is not checked, and you type different names for the Project (in the Name field) and the folder (at the end of the path). If there is a problem with the selected location, the OK button will be disabled, the location field will be highlighted in red, and, if you position the mouse over the location field, a screen tip will appear indicating the nature of the problem. The button to the right of the Location field allows you to browse your file-system to set a location path. See section 2.2.2 for an example and additional details on ways to create a new Project in the AVA software.

1.1.3.2

The Tabs and Sub-Tabs

The AVA application displays the various aspects of the Amplicon Project in a series of 7 tabs, with the Project tab separated into two panels (themselves comprising 4 and 7 sub-tabs, respectively). When a tab has no content, its name is grayed out and the tab is unavailable. When a tab does have content, a green square icon appears next to its name; clicking on an available tab or sub-tab name brings the information it contains to the front for viewing, as listed below. If the size of your screen does not allow you to view all the tabs, a pair of arrow buttons in each panel allows you to scroll the set of tabs to bring hidden ones into view. The contents and usage of the information included in the tabs are described in full detail in sections 1.2 through 1.8.

•	The Overview tab provides a basic summary of the Amplicon Project.

•	The Project tab is used to set up the Project (define all the elements that compose it and their associations) and to navigate it and select particular Sample-Amplicon pairs to view in the Global Align tab. The Project tab contains two panels:

◦	The left panel comprises 4 sub-tabs that show various representations of the Project in “tree” form, thus displaying the associations between the various elements that compose it.

◦	The right panel comprises 7 sub-tabs that list and show all the characteristics of the various “elements” defined in the Project, in tabular form.

•	The Computations tab allows the user to compute (or re-compute) the Project, and lists the progress and state of each computation step.

•

The Variants tab provides summary results of the GS Amplicon Variant Analyzer, listing the observed frequency of each defined Variant in each relevant Sample. A Sample is relevant to a Variant when the Read Data Set(s) with which it is associated contain reads that cover all the Reference Sequence positions specified in the Variant’s definition.

•

The Global Align tab is populated with the multiple alignment (against the appropriate Reference Sequence) of the reads corresponding to one or more selected Sample-Amplicon pair(s). Such a selection is done by right-clicking on an appropriate object in any of the Project Trees or in the Variants Tab (only one Sample-Amplicon pair can be selected this way), or by using a navigation dialog found within the Global Align tab itself (multiple pairs selection possible). The reads displayed may be Individual reads, corresponding to sequence reads directly extracted from the Read Data Set(s), or Consensus reads, corresponding to sets of Individual reads that were collapsed into a single representative read (in order to simplify the display and eliminate noise from the data). In either case, the tab comprises two data panels:

◦

The top panel is a stacked histogram indicating the frequency of all the variations observed between the selected reads and the Reference Sequence associated with the Amplicon(s) from which the reads were derived. The histogram is based on a gapped multiple alignment and, thus, may contain data for positions of the alignment that occur between positions of the Reference Sequence itself. This graph also shows depth of coverage for each position of the alignment.

◦

The bottom panel displays the (gapped) sequence multi-alignment of the reads, aligned below the Reference Sequence. Color codes help to highlight variations in the reads in comparison with the Reference Sequence; the reads (Individual or Consensus) can be filtered for display to help identify specific variations and potentially discover haplotypes.

•

The Consensus Align tab displays the same information as the Global Align tab, but for the set of individual reads that were collapsed into a consensus on the Global Align tab. A line highlighting the differences between that consensus sequence and the Reference Sequence is displayed directly below the Reference Sequence in the alignment.

•

The Flowgrams tab, finally, displays a tri-flowgram view of an individual read, selected from either the Global Align or the Consensus Align tab. This display is designed to help evaluate the significance of differences between an individual read and a Reference Sequence. As such, the read flowgram displayed is not the raw flowgram of the read, but is a computationally processed version designed to facilitate the comparison of the read flowgram with an idealized flowgram for the Reference Sequence. In particular, flow cycle-shifts may be introduced into one or both flowgrams in order to optimize their alignment, and the flowgram of the read may be computationally reverse-complemented in order that the display always be in the 5’-->3’ orientation of the Reference Sequence. Finally, the flowgram only displays the subset of flows relevant to the read’s sequence alignment as displayed in the Global Align or Consensus Align tabs. The display is divided into three panels:

◦	The top panel shows an aligned, idealized flowgram for the Reference Sequence.

◦	The middle panel shows the aligned, (possibly reverse-complemented) flowgram of the read.

◦

The bottom panel shows a difference flowgram (read minus reference), where any variation from the Reference Sequence is seen as a non-zero value. Specifically, extra signals in the read, relative to the Reference Sequence, are displayed as positive differences in this panel; and missing signals in the read, relative to the Reference Sequence, are displayed as negative differences.

When a tab is divided into panels, the panels can be resized by dragging the separator. Also, when the panels are stacked vertically (as in the case of the Global Align, the Consensus Align and the Flowgrams tabs), two small buttons are present at the left edge of the separator(s); these buttons allow you to collapse one of the panels, leaving the entire height of the window to the other one(s). This action is reversible (use the other button to re-expand the panel).

1.1.3.3

Buttons and Plots

The plots, multi-alignment views and data tables displayed in the various tabs of the AVA application are scrollable and/or zoomable graphical elements. They share certain common buttons and functions, e.g. to perform the scrolling and zooming. When they do appear, these graphic elements have some or all of the following features (see in Figure 1‑3, an example for a Global Align window which has many of these elements):

•	Scroll bars for horizontal and/or vertical scrolling (appearing below and to the right of the element, if necessary).

•	A column of buttons along the upper left edge of the graphic elements, used for navigation (including various zooming functions) and/or to save snapshot images or text files of the displayed data.

•

Additional functional buttons, also in the column at the left of graphic elements, to carry out actions such as applying a selection filter on the reads currently displayed, defining novel Variants, assembling consistent reads (which might span overlapping Amplicons) into consensi, running a computation of the Project, adding or removing Project elements or associations, etc.

•	“Mousing” functions (pointing, clicking or dragging the mouse, touchpad, pen, etc. over the graphical element) to view data values and adjust the zoom level.

•	When a plot with DNA sequence information is present (Variation Frequency Plot and Flowgrams), a legend is shown, giving the color code for the nucleotides [as well as gaps (“-”) and depth of coverage (“#”), if appropriate].

Figure 1‑3: An example Global Align tab showing many of the common graphical element functions

1.1.3.3.1

Scroll Bars

The scroll bars have the standard functions, and appear when the data in either direction is too large to be shown in the viewable area. In Figure 1‑3, for example, the horizontal scrollbar appears in the multi-alignment pane, and the vertical one appears in the plot pane; others are not displayed because axes scales are set such that the full breadth of the data can be seen.

1.1.3.3.2

Navigation Buttons

Many of the buttons appearing to the left of an element are used for navigation on the element, and have the following general functions:

Button	Name – Description
	Fit – Fit means to scale out to the limits of the data. The y‑axis is rounded to an attractive-looking number rather than stopping at the exact data limit.
	Zoom in – Zoom in by a factor of 1.5. This button zooms only the primary (left) y-axis scale; use the Zoom to labels and Freehand zooming functions described below to zoom the x-axis.
	Zoom out – Zoom out by a factor of 1.5. This button will zoom only the primary y-axis scale and, unlike other zoom operations, this will zoom out past the data limits (to allow you to get a better perspective of the data, especially when attempting to visually separate data on the primary and secondary y-axes).
	Zoom to labels – This button zooms the x-axis of the flowgram so that the nucleotide/flow characters can fit below the axis.
	Snapshot – Save a snapshot image of the current view to disk. This will open a dialog asking for the location and filename to save a PNG format snapshot image. The saved image contains only the currently visible region of the element: in particular, if the element is displayed in the context of a scrollbar, only the current, scrolled view is saved.
	Text file – Save a text-formatted version of the element. This will open a dialog asking for the location and filename to save the text file. It then saves the data, along with summary information describing the data source. In most cases the user has the option of exporting a tab or comma-separated text file of the underlying data element. For plots, the text file includes data that may be outside of the current view (due to scrollbars). For a flowgram view (see section 1.8), the data for all three plots are saved to one file, with some white space between the three sections of plot data. For summary data tables, the file contains the tabular data, also including data that may be beyond the current scroll region. For multiple-alignment displays, seven output formats are supported: FASTA, Clustal, Ace, SAM, BAM, and Table (csv and tsv). For the Variants Table, finally, the text file includes an extra column (Variant Status), as compared to the Table visible in the GUI, placed between the Variant Name and Max Value columns (i.e. at column 3 in the text output); note that although the GUI lacks an explicit column for this, the Variant Status data is accessible via the tooltips as you pause the mouse over Variants).

1.1.3.3.3

Mousing Functions

When the mouse cursor is located over a graphical element, additional functions can be performed by moving, clicking or dragging the mouse:

•

Mouse Tracker – Whenever the cursor is located over a position in a plot or a multi-alignment display, detailed data values for that position are shown in a related Mouse Tracker area, at the bottom left of the window. This allows you to see the specific numerical value for any data point as well as other detailed data associated with the display position.

•

Freehand Zoom In – The mouse can be used to zoom in on specific regions of a plot. To zoom in, hold the left mouse button down and drag a box around the area of interest (see Figure 1‑4). Releasing the button zooms to the area circumscribed by the box. If the plot has both primary and secondary Y-axes, only the primary axis data is zoomed.

↓

Figure 1‑4: Freehand zoom in to a flowgram region

•	Freehand zoom out – For plots only, right-clicking the plot will cause the plot to zoom out by a factor of 1.5 in both the X and (primary) Y directions, centered on the middle of the current view. This zoom will not zoom farther than the limits of the data.

•

Screen tips – When you hover the mouse over a button or other display control, over an element definition data, or over most of the Variants or multi-alignment results, a screen tip appears providing some information about the object under the pointer. Some of the most useful examples of this are specified in the tab sections, below.

1.1.3.3.4

Progress bars

When an operation takes more than a few seconds, a Progress bar appears temporarily in the upper-right corner of the application window, to display the progress of the operation (Figure 1‑5A). Double-clicking on this progress bar opens the Progress window, which contains individual progress bars for the operation or any of its sub-processes (Figure 1‑5B). In certain contexts, you can cancel an operation by clicking the “Cancel” button that appears to the right of a progress bar in the Progress Window (when cancelling is not possible, such as when new data is being loaded, the Cancel button is present, but grayed out). The Progress window stays open, even after the entire operation completes, until you close it manually.

Figure 1‑5: (A) A Progress bar (B) The Progress window

1.1.3.3.5

Special Action Buttons

Another functional category of buttons appears to the left of some graphic elements or in the display options area of certain tabs. Since these are tab-specific, these buttons are described in the corresponding tab sections, below.

1.1.3.4

File Browsing in Linux

The Linux File Brower used for opening Projects, finding Read Data Sets, and creating New Projects lacks some of the usually expected controls. For example, there are no buttons for going up a directory, creating a new folder, etc. However, these functions can be found by right-clicking in the browser window and choosing from the options presented in the contextual menu that will open (Go up, Go Home, View Details/List, Refresh, and New Folder).