TABLE OF CONTENTS
Gmaj can be run in two different modes: as an applet over the world-wide web (for viewing data delivered from a server), or as a stand-alone application (for viewing data stored on your own computer). These modes are mostly similar but have a few minor differences, as noted below.
If you are using Gmaj in applet mode, it will be started for you when you visit the applicable web page or submit a query to the server. If the Gmaj window does not appear automatically, just click on the labeled button to view the indicated data. Then skip the rest of this section.
If you are using Gmaj in stand-alone mode, you need to start it yourself. The Java runtime environment does not have its own GUI, so you generally need to run Gmaj from a command line (e.g., in the Command Prompt window on Windows XP). The basic command to type in looks like this:
[path1]java -jar [path2]gmaj.jar
where [path1] is the location of your
java program file (perhaps
c:\windows\system32\ on WinXP, or
/usr/bin/java/ on a Unix system), and
[path2] is the location where the
gmaj.jar file was installed. Note that you can
leave off [path1] if you have set up your system
command path to include the location of the java
program. Depending on how your system is set up, it may also be
possible to run the jar file directly by just typing its name or
double-clicking on it.
Since you haven't yet specified any data to display, Gmaj will begin by presenting a dialog box to prompt you for the name of your input file (see Input Files for Gmaj). If the file is located in the current directory you can just type its name, otherwise you'll need to supply a complete path. When you click the OK button, a window will appear displaying the loaded data.
As an alternative to using the dialog box, you can specify the input file (plus additional parameters) on the command line. As of this writing, the command syntax is:
[path1]java -jar [path2]gmaj.jar
[-version] [-help] [-debug] [-urlpause <millisec>]
[-initzoom <refseqname> <start> <end>]
[-bundle <zipfile>] [<paramfile>|<alignfile>]
This has been wrapped here for easier readability, but should be
typed all on one line. Arguments shown in square brackets
[] are optional, while a vertical bar |
indicates a choice between alternatives. Angle brackets
<> signify meta-syntactic variables that
should be replaced with your names or numbers. Don't type any
of the brackets or the bar.
These parameters do the following:
-version:
-help:
-debug:
-urlpause:
-initzoom:
<refseqname> must
match one of the sequence names from the alignment file(s),
and the endpoints must include the offset (if any) for that
sequence from the parameters file. To specify the reference
sequence without a zoom region, use -1 for both
endpoints.
-bundle:
.zip or
.jar file containing some or all of the data
files. This option is mostly used with Gmaj's applet mode
to streamline the data download, but it is also supported
in stand-alone mode. It is described in
Input Files for Gmaj.
<paramfile>:
sample.gmaj.
<alignfile>:
If the dataset you want to view is large, Gmaj may run out of
memory, in which case Java will report an
OutOfMemoryError. This message will appear in the
command window where you started Gmaj (for stand-alone mode) or
in the Java Console window of your web browser (for applet mode).
If the Java Console window does not appear when you run the Gmaj
applet, open the Java Plug-in Control Panel on your computer and
click the setting for Show Console so you can see this and other
Java messages.
The OutOfMemoryError is not uncommon, because the
default amount of memory that Java allocates is rather small.
You can give it more memory using the -Xmx switch
(at least with Sun's Java; this option may not be supported by
all vendors). For example, when using stand-alone mode the
command line
[path1]java -Xmx1024m -jar [path2]gmaj.jar
runs Gmaj with a heap memory allowance of ~1 gigabyte. For the
applet, you can do this by opening the Java Plug-in Control Panel
on your computer and entering -Xmx1024m in the Java
Runtime Parameters box (this will affect all applets you run via
the Java Plug-in, not just Gmaj).
Gmaj has two kinds of windows. The main one displays a number
of pips (percent identity plots) showing the pairwise alignments,
projected from the multiple alignments, of a particular reference
sequence against each of the other sequences. A pip is similar
to a dotplot, with the horizontal x-axis
representing positions in the reference sequence, but the
vertical y-axis represents the percentage of
matching nucleotides in each gap-free segment of the pairwise
alignment, instead of its position in the second sequence. The
window you see first when Gmaj opens is usually of this type, and
if the alignments are reference-independent, you can open more of
these with other sequences as the reference.
The second type of window focuses exclusively on a particular pair of sequences, and displays one pip together with its corresponding dotplot representation (similar to Gmaj's predecessor, Laj). These windows are opened upon request, by clicking on a button in the header for a particular pip in the multi-pip window. Conceptually the dotplot windows are like children of their parent multi-pip window: they have the same reference sequence, and if you close a dotplot only that one window closes, but if you close the parent all of its children close too.
For the special case where the alignment files have only two sequences, the main window is redundant so Gmaj automatically hides it and shows the dotplot window directly.
Gmaj has two main elements of user state that reflect the user's interactive manipulation of the display. The first is the zoom region, i.e. the portion of the reference and secondary sequences that is currently displayed; this is one-dimensional for multi-pip windows and two-dimensional for dotplots. As the zoom is changed, the previous regions are remembered in a history list, so you can go back and forward through it similar to a web browser. Each Gmaj window has its own separate zoom and history; when opening a new window the current zoom region is translated initially, but then they are independent. As a convenience, each new window begins with several zoom regions already in the history: the fully unzoomed sequence length(s), as specified in the MAF files; the aligning portion of the applicable sequence(s); and an approximate translation of the previous window's current zoom (or in the case of the very first window, the initial zoom specified in the command-line or applet parameters, if any). The boundaries of the current region are displayed in a status indicator in the upper right corner of the window, below the menu bar.
The second state element is called the "mark", and it represents a particular selected point in a particular pairwise pip+dotplot and a particular MAF block. It is typically selected by clicking in a pip, dotplot, or text alignment, and is drawn as a small red circle in the plots, and also as a red highlight in the text alignment. Unlike the zoom regions, the mark is shared among several windows: there is at most one mark for each reference sequence, and it appears in both the multi-pip window for that sequence and the dotplot corresponding to whichever pip the mark is currently in (the other dotplots, with different secondary sequences, will show some indirect information about the mark, but not the mark itself). Thus, moving the mark in a dotplot window will also move it in the parent multi-pip and vice-versa, but the mark for a different reference sequence is independent. Information about the current mark and plot block is displayed in one of the status indicators below the menu bar.
Each Gmaj window is divided into several sections. Across the top you will see a menu bar (including text boxes for setting display thresholds), and below that two lines containing status indicators with information about the position of the mouse pointer, the boundaries of the currently displayed zoom region, and the location of the mark (red circle), along with buttons for sliding the zoom region and selecting alternative blocks at the marked position. Several of the dividers between these items are draggable, so you can adjust the relative space they occupy. Below these is a row of category checkboxes, which by default will only appear when there is more than one alignment file or if you have used the tagging feature. The menus, threshold boxes, buttons, and checkboxes are discussed individually in the Menus and Widgets section of this document.
Ruler:
The first graphical panel is a horizontal ruler that displays
tick marks corresponding to positions in the currently selected
reference sequence. These are intended to give you an immediate
general feel for the location and scale of the region being
displayed. Precise locations can be determined via the position
indicator, which displays the exact coordinate of the mouse
pointer.
Reconstruction scores:
For ancestral reconstruction alignments, the MAF files may
contain scores indicating the confidence that 1) a particular
inferred ancestral nucleotide is correct, and that 2) it was
present at all. The next two panels display bar graphs of these
scores when the ancestral sequence is the reference. The scores
are binned according to the current zoom region and panel width,
and the mean score for each bin is graphed on a scale of 0 - 1
(note that the scores are transformed via simple linear scaling,
and should not be interpreted as probabilities). For this to
work, the parameters file must specify which organism the scores
apply to. Otherwise, or if there are no scores in the file, or
if a different sequence is currently the reference, these panels
will not appear. The position indicator displays the horizontal
coordinate and vertical score position of the mouse pointer,
along with the score for the bar at that location (if any).
Linkbars:
Next is a panel that can display links to additional information
about various regions in the current reference sequence. Each
annotation is represented by a color-coded bar spanning the
region's position in the sequence. (The bars' vertical positions
are not meaningful; they are only placed in rows for convenience,
to keep them from overlapping.) Pointing to a particular bar
will cause the position indicator to display the x
coordinate of the pointer, and also the type and description of
that bar's annotation; otherwise only the x
coordinate will be shown. In applet mode, clicking on a bar will
open a separate browser window to visit the corresponding web
site. In stand-alone mode Gmaj is not working within a web
browser, so instead it displays the URL for you to visit manually
via copy-and-paste. If no links file is provided for the current
sequence, this panel will not appear.
Sequence features:
The next two panels contain schematic diagrams of the known
exons and interspersed repeats in the current reference sequence,
respectively (if these files are provided). Any additional
features such as CpG islands are included with the repeats (which
is why the label says "repeats+"). The diagram for repeats uses
the same symbols as PipMaker to indicate the various repeat categories (Alu, MIR,
etc.), but only if either the PipMaker category or the
RepeatMasker name and
class/family are available. For example, BED and GTF repeat
files from the UCSC Table Browser include the RepeatMasker name but not the
class/family, so Gmaj cannot determine the PipMaker category and
draws all of them as "Other". As usual, the position indicator
displays the x coordinate of the mouse pointer, and
also identifies any features at that position.
Plots:
The following panels display the alignment plots according to the
window type: either a scrollable stack of pips (for the reference sequence against each of the others)
or a single pip and its corresponding dotplot. For pips, only
the top half of each plot is shown, since segments matching less
than 50% are usually not very interesting. Plot segments from
the primary alignment file are drawn with thin black lines, while
those from subsequent files are drawn with thicker brown lines.
Tagged blocks are green, and the marked block is red (or orange
if it is also tagged), though these may vary
on colored backgrounds. When plot segments overlap, the marked
and tagged ones are drawn "on top" so they won't be obscured,
followed by other blocks from the primary alignment file and then
the remaining files. Plots that are completely empty (i.e. if
that pair of sequences never occurs together in any of the
alignment blocks) will be painted gray. An additional feature of
these panels is that colored backgrounds, or "underlays", can be
used to highlight regions of interest (if files with this
information are provided); dotplots can display these for both
the reference and secondary sequences. Vertical blue bars at the
edges of the plots represent the boundaries of the current zoom
region, whose endpoints are displayed in the zoom indicator. For
a pip, the position indicator displays the horizontal coordinate
and vertical percentage position of the mouse pointer, along with
a list of block numbers covering that location. For a dotplot, it displays the
horizontal and vertical coordinates in the reference and secondary
sequences, respectively. It will also display labels for the
colored regions in both types of plots, if these are included in
the underlay files.
Text view:
The bottom panel displays a nucleotide-level view of a single
selected alignment block: the one containing the mark
(red circle). Initially it is empty, since
you haven't set the mark yet. The top row of this display shows
the current reference sequence, while the rows for the other
sequences show a dot (.) wherever they match the
reference sequence, and only explicitly list the nucleotides that
don't match. (This matching is case-insensitive to deal with
soft masking, but non-nucleotide characters such as
X or N never match anything, even
themselves.) All of the sequences will likely have had gaps
(-) inserted by the alignment program. Note that
most of the blocks will be much too long to fit across this
window, so a scrollbar is provided; the relative size of the
scrollbar's slider indicates what fraction of the alignment is
shown in the window. Colored "highlights" (analogous to the plot
underlays) can also be specified for each sequence; otherwise
Gmaj will provide default highlights based on the exons files
(if any). Whenever the mouse pointer is in this bottom panel,
the position indicator displays its location in the format
n(x), where n is the column position
in this aligned block (starting with 0), and x is
the sequence position in the individual row (i.e., in that entire
chromosome or contig, starting with 1). Note that x
does not include the gaps, but n does. Labels for
any highlights at that position are also displayed.
With the exception of the text view, all of these data panels use the same horizontal coordinate scale (i.e., position in the current reference sequence), and they are always kept vertically aligned so they can be compared easily. Note that in the multi-pip window the partition between the graphical panels and the text view is draggable, so you can adjust the relative amount of space they occupy. Also, individual panels can be hidden if desired, using the Options - Show dialog (see Menus and Widgets).
As discussed in more detail above, pointing with the mouse in the plots or other panels causes the position indicator below the menu bar to display information about that location and/or data item.
You can select a particular alignment block by clicking on one of its segments in any of the plots (pips or dotplots) with the left mouse button. (You don't have to click exactly on it, because Gmaj will automatically jump to the nearest point if you miss; however proximity is measured in bases, not pixels, which can lead to non-intuitive results if the dotplot's zoom scale is highly skewed.) The spot will be marked with a small red circle, and the entire alignment block containing the mark will change color from black to red in all of the plots for that reference sequence (each block typically spans several gap-free segments). Also, the corresponding text view for that block will appear in the bottom panel with the marked position highlighted. Lastly, the mark indicator will be filled in with information about the marked block and position, and a row of buttons will appear next to it showing the block numbers covering the marked location. These buttons allow convenient selection of a different block at the same position in the reference sequence, from the same or a different alignment file (see Menus and Widgets). Note that there is only one mark at a time for each reference sequence, so the previous one, if any, will be unmarked.
In a similar fashion, clicking the left mouse button in the text view will move the mark (both the highlight and the red circle) to that position. However, gap positions cannot be selected in this manner because they do not correspond to plot segments; if you click in a gap, the nearest gap-free position is selected instead. Also, if you click on a position in the reference sequence (which has no corresponding pip), the mark will move to the new column but will remain in the same pip as before.
You can "zoom in" on a particular region by dragging out a rectangle with the left mouse button in any of the white panels (ruler, annotations, pip, or dotplot). All of these panels will always zoom together, to keep them lined up. This can be repeated until the maximum resolution is reached; after that Gmaj will display an error message. Additional zoom features are available via the Zoom menu and arrow buttons (see Menus and Widgets). Note that selecting a new region will cause any entries in your zoom history that are forward of the current point to be discarded, similar to a web browser. If your rectangle is very tiny it will be treated as a click instead, to avoid unintended zooming.
Holding down the right mouse button over any of the white
panels adds crosshairs at the mouse pointer's location, which
is convenient for determining whether two regions really line
up. If you have a one-button mouse, you can achieve the same
effect by applying the Shift key when initially
pressing the mouse button.
Note that these controls only work in the active window (usually indicated in the operating system by a differently colored title bar). If a window is not the active one, then your first click in it just activates the window; you will need to click again to set the mark, select a region, open a menu, etc.
Alt key is needed. The shortcuts will not work if
the keyboard focus is in a text area (threshold boxes, status
indicators, text alignment, panel headers, etc., as indicated by
a purple border or highlight); in this case press Esc
first to cancel any text operation and restore the focus to the
active window's menu bar. Esc will also cancel
dialog and message boxes.
0
(which is sometimes used to mean "no score") will not be changed,
since Gmaj cannot distinguish this from a score that is really
zero. As with the % Identity box, the same threshold applies
across all windows, and keyboard shortcuts make it easy to adjust
it up and down. Also, pointing to a particular underlay or
highlight will show that annotation's score in the position
indicator.
Gmaj supports copy/paste via the system clipboard from most of
its text panels and dialog boxes, using mouse selection followed
by the standard keystrokes
(Ctrl-C/Ctrl-V on Windows and Linux,
Cmd-C/Cmd-V on Mac). Some labels are
not copyable, but their values generally are. (Exception: with
some versions of Java, all dialog text may be uncopyable in
applet mode due to a bug.)
In Gmaj's multi-pip and dotplot windows the text alignment, panel
headers, and status indicators are copyable. Clicking in any of
these components (e.g. to sweep out a selection with the mouse)
will transfer the keyboard focus to that component, as indicated
by purple lines around it. This is necessary for the Copy
keystroke to work; however it means that Gmaj's other keyboard
shortcuts will be disabled until the focus is restored, either by
clicking somewhere else or by pressing the Esc key.
Note that the mouse selection in the text alignment is
rectangular (unlike the usual line-wrapped stream), and all of
these components can be scrolled if necessary by dragging the
mouse just outside their borders.
Gmaj does not currently have its own print capability. The recommended way to record a particular Gmaj view is to use your operating system's "screenshot", "print screen", or "grab" facility to save an image of the window to a file, then adjust it as needed using image-editing software. (Be careful with rescaling and format conversions, as these may degrade the image.)
To prevent the position indicator from changing when you move the
mouse, hold down the Ctrl key. This is useful both
for copying the position indicator's contents and for taking
screenshots.
[1] By default the circular mark and the selected block's plot segments are always red (or orange), regardless of the background color behind them, and similarly tagged blocks are always green. A setting on the Options menu can make these colors vary with the background (so they are not invisible against like-colored underlays), however this causes patchy rendering when used with Large Fonts. These special blocks are drawn last, so they will not be obscured by ordinary ones.
[2]
Blocks in the MAF files are numbered consecutively, starting
with 0. MAF files are also numbered starting with 0, in the
order they are listed in the parameters file. If there are
several MAF files, they are catenated into one big list of
blocks, and the block numbers for the second file continue where
the first left off. However, Gmaj also records the relative
block numbers within each file, and displays this information
in the mark indicator and certain error messages in the form
maf#.block#.
[3] An alignment block is considered to cover a plot position if it contains rows for both of the plot's sequences and the position falls within the endpoints of the reference sequence's row (not necessarily the row for the other sequence, as this is a pip-oriented computation); there are no "holes" due to gaps. In order to appear in the row of block buttons for the mark or in the position indicator's block list for pips, a block must also be in a visible category (according to the category checkboxes) and meet the % identity threshold (in the applicable plot).