galaxy/static/gmaj/docs/gmaj_help.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Starting and Running Gmaj</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" type="text/css" href="gmaj.css">
</head>
<body>
<p class=vvlarge>
<h2>Starting and Running Gmaj</h2>
<p class=vvlarge>
TABLE OF CONTENTS
<p class=small>
<ul class=notop>
<li><a href="#intro">Introduction</a>
<li><a href="#start">Starting Gmaj</a>
<li><a href="#memory">Memory Allocation</a>
<li><a href="#windows">Multi-Pip and Dotplot Windows</a>
<li><a href="#state">The Zoom and the Mark</a>
<li><a href="#layout">Window Layout</a>
<li><a href="#mouse">Mouse Controls</a>
<li><a href="#menu">Menus and Widgets</a>
<li><a href="#copy">Copying and Printing</a>
<li><a href="#notes">Footnotes</a>
</ul>
<p class=vlarge>

<p class=hdr>
<h3><a name="intro">Introduction</a></h3>
<p>
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.
<p>

<p class=hdr>
<h3><a name="start">Starting Gmaj</a></h3>
<p>
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.
<p>
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:
<pre>
    [path1]java -jar [path2]gmaj.jar
</pre>
where <code>[path1]</code> is the location of your
<code>java</code> program file (perhaps
<code>c:\windows\system32\</code> on WinXP, or
<code>/usr/bin/java/</code> on a Unix system), and
<code>[path2]</code> is the location where the
<code>gmaj.jar</code> file was installed.  Note that you can
leave off <code>[path1]</code> if you have set up your system
command path to include the location of the <code>java</code>
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.
<p>
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 <a href="gmaj_input.html"
>Input Files for Gmaj</a>).  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.
<p>
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:
<pre>
    [path1]java -jar [path2]gmaj.jar
        [-version] [-help] [-debug] [-urlpause &lt;millisec&gt;]
        [-initzoom &lt;refseqname&gt; &lt;start&gt; &lt;end&gt;]
        [-bundle &lt;zipfile&gt;] [&lt;paramfile&gt;|&lt;alignfile&gt;]
</pre>
<p>
This has been wrapped here for easier readability, but should be
typed all on one line.  Arguments shown in square brackets
<code>[]</code> are optional, while a vertical bar <code>|</code>
indicates a choice between alternatives.  Angle brackets
<code>&lt;&gt;</code> signify meta-syntactic variables that
should be replaced with your names or numbers.  Don't type any
of the brackets or the bar.
<p>
These parameters do the following:
<dl>
<dt>	<code>-version</code>:
<dd>	Prints a message with information about Gmaj, including
	version, author, etc.; then exits.
<dt>	<code>-help</code>:
<dd>	Prints a brief help message with up-to-date syntax; then
	exits.
<dt>	<code>-debug</code>:
<dd>	Instructs Gmaj to print extra warning messages in
	your terminal window if certain problems occur.  Normally
	you won't need this, as it is mainly for development
	purposes.
<dt>	<code>-urlpause</code>:
<dd>	Specifies how many milliseconds the program should pause
	before retrieving each file from a URL, in order to avoid
	overloading the server.
<dt>	<code>-initzoom</code>:
<dd>	Specifies an initial zoom setting to be applied when the
	window opens.  You will still be able to invoke the Unzoom
	or Set Zoom features interactively to see the entire
	sequence range.  The <code>&lt;refseqname&gt;</code> 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 <code>-1</code> for both
	endpoints.
<dt>	<code>-bundle</code>:
<dd>	Specifies the name of a <code>.zip</code> or
	<code>.jar</code> 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
	<a href="gmaj_input.html">Input Files for Gmaj</a>.
<dt>	<code>&lt;paramfile&gt;</code>:
<dd>	This is the meta-data parameters file that lists the names
	of all the data files, plus a few related parameters such as
	display offsets and any intrinsic reference sequence.  For
	more information about the contents and format of this file,
	please see <a href="gmaj_input.html">Input Files for Gmaj</a>
	and <code><a href="sample.gmaj">sample.gmaj</a></code>.
<dt>	<code>&lt;alignfile&gt;</code>:
<dd>	If you don't want to use any annotations or other
	data-related options, you can specify a single alignment
	file directly, instead of creating a parameters file.
	This must be in MAF format; see <a href="gmaj_input.html"
	>Input Files for Gmaj</a> for more details.
</dl>
<p>

<p class=hdr>
<h3><a name="memory">Memory Allocation</a></h3>
<p>
If the dataset you want to view is large, Gmaj may run out of
memory, in which case Java will report an
<code>OutOfMemoryError</code>.  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.
<p>
The <code>OutOfMemoryError</code> is not uncommon, because the
default amount of memory that Java allocates is rather small.
You can give it more memory using the <code>-Xmx</code> 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
<pre>
    [path1]java -Xmx1024m -jar [path2]gmaj.jar
</pre>
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 <code>-Xmx1024m</code> in the Java
Runtime Parameters box (this will affect all applets you run via
the Java Plug-in, not just Gmaj).
<p>

<p class=hdr>
<h3><a name="windows">Multi-Pip and Dotplot Windows</a></h3>
<p>
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 <code>x</code>-axis
representing positions in the reference sequence, but the
vertical <code>y</code>-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.
<p>
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, <a href="http://globin.bx.psu.edu/dist/laj/"
>Laj</a>).  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.
<p>
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.
<p>

<p class=hdr>
<h3><a name="state">The Zoom and the Mark</a></h3>
<p>
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.
<p>
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
<a href="#red">red</a> 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.
<p>

<p class=hdr>
<h3><a name="layout">Window Layout</a></h3>
<p>
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 (<a href="#red">red</a>
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 <a href="#dividers"
>draggable</a>, 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 <a href="#menu">Menus and Widgets</a>
section of this document.
<p>
<i>Ruler:</i><br>
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.
<p>
<i>Reconstruction scores:</i><br>
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).
<p>
<i>Linkbars:</i><br>
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 <code>x</code>
coordinate of the pointer, and also the type and description of
that bar's annotation; otherwise only the <code>x</code>
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.
<p>
<i>Sequence features:</i><br>
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 <a href="http://pipmaker.bx.psu.edu/pipmaker/"
>PipMaker</a> to indicate the various repeat categories (Alu, MIR,
etc.), but only if either the PipMaker category or the
<a href="http://www.repeatmasker.org/">RepeatMasker</a> name and
class/family are available.  For example, BED and GTF repeat
files from the <a href="http://genome.ucsc.edu/cgi-bin/hgTables"
>UCSC Table Browser</a> 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 <code>x</code> coordinate of the mouse pointer, and
also identifies any features at that position.
<p>
<i>Plots:</i><br>
The following panels display the alignment plots according to the
window type: either a scrollable stack of <a href="#windows"
>pips</a> (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 <a href="#red">vary</a>
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 <a href="#numbering">block numbers</a> <a href="#cover"
>covering</a> 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.
<p>
<i>Text view:</i><br>
The bottom panel displays a nucleotide-level view of a single
selected alignment block: the one containing the mark
(<a href="#red">red</a> 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 (<code>.</code>) 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
<code>X</code> or <code>N</code> never match anything, even
themselves.)  All of the sequences will likely have had gaps
(<code>-</code>) 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
<code>n(x)</code>, where <code>n</code> is the column position
in this aligned block (starting with 0), and <code>x</code> is
the sequence position in the individual row (i.e., in that entire
chromosome or contig, starting with 1).  Note that <code>x</code>
does not include the gaps, but <code>n</code> does.  Labels for
any highlights at that position are also displayed.
<p>
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 <a href="#dividers">draggable</a>, 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 <a href="#menu">Menus and Widgets</a>).
<p>
<!--
<i>Dotplot:</i><br>
The large middle panel displays a dotplot view of the alignments,
with the reference sequence along the horizontal
<code>x</code>-axis and the secondary sequence along the vertical
<code>y</code>-axis.  If the second sequence contains multiple
contigs, they will appear as separate horizontal bands across the
plot, each with its own <code>y</code>-axis coordinate system.
Whenever the mouse pointer is in this panel, the position
indicator displays its location in the format <code>x,y</code>,
where <code>x</code> is the position in the horizontal sequence
and <code>y</code> is the position in the vertical sequence.  If
there are multiple contigs, then the contig name will be
displayed as well (actually only the first word is displayed, to
prevent long names from crowding out the other information).
<p>
-->

<p class=hdr>
<h3><a name="mouse">Mouse Controls</a></h3>
<p>
As discussed in more detail <a href="#layout">above</a>,
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.
<p>
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
<a href="#red">red</a> circle, and the entire alignment block
containing the mark will change color from black to
<a href="#red">red</a> 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 <a href="#numbering">block numbers</a>
<a href="#cover">covering</a> 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 <a href="#menu">Menus and Widgets</a>).
Note that there is only one mark at a time for each reference
sequence, so the previous one, if any, will be unmarked.
<p>
In a similar fashion, clicking the left mouse button in the
text view will move the mark (both the highlight and the
<a href="#red">red</a> 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.
<p>
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
<a href="#menu">Menus and Widgets</a>).  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.
<p>
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 <code>Shift</code> key when initially
pressing the mouse button.
<p>
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.
<p>

<p class=hdr>
<h3><a name="menu">Menus and Widgets</a></h3>
<p>
<dl>
<dt>File - Open:
<dd>
Loads a new set of data files into Gmaj, replacing the currently
displayed data.  A dialog box is presented for you to specify the
new input file.  (See discussion under <a href="#start"
>Starting Gmaj</a>, above.)  This menu item does not appear in
applet mode, because the user is unlikely to know the locations
of other data files on the server; instead the webmaster should
set up separate access for each dataset.
<p>
<dt>File - Export:
<dd>
Opens a dialog box that allows you to save alignment blocks in
MAF format or as FastA sequence files.  A variety of options are
available re: which blocks to export, whether they should be
clipped and/or cleaned up, whether to omit certain sequences,
etc.  Note that all-gap rows are always skipped, and so are
blocks that have no rows left.  When exporting in MAF format,
if the alignment has a fixed, intrinsic reference sequence and
that row is all gaps, the entire block will be skipped.  When
exporting FastA sequences, a separate file is created for each
sequence name (i.e. species or contig), and there is an option
to restore sequences that align in reverse complement to their
original orientation (which will also swap the order of the
endpoint coordinates in the FastA header).  By default export is
not available in applet mode, because security restrictions make
it very awkward to save files on the client computer.  However,
the applet administrator can <a href="gmaj_install.html#page"
>specify a URL</a> where the output can be sent instead (in this
case only MAF format is supported).
<p>
<dt>File - Close:
<dd>
Closes the current window, and if it is a multi-pip window, all
of its dotplot children are closed as well.  When no windows are
left, Gmaj will exit.
<p>
<dt>File - Exit:
<dd>
Exits from Gmaj.  In stand-alone mode, also exits from Java.
<p>
<dt>Options:
<dd>
This menu controls some of the aesthetic aspects of Gmaj.  You
can choose between two sizes of fonts, which will also affect
some other viewability settings, such as the thickness of the
plot segments, the radius and thickness of the mark circle, the
blackness of the ruler numbers, and the height of the pips.  You
can also choose to make the mark circle and the selected block's
plot segments change color with the background instead of always
being red (this makes them visible against red underlays, but is
more complicated to explain in a figure legend and causes
<a href="gmaj_bugs.html#xor">patchy rendering</a> when used with
Large Fonts).  Lastly, the Show item opens a dialog where you can
choose which panels to display or hide, and whether the underlays
should be painted on dotplots.  The sequence selections here
control which pips, dotplot windows, and text rows are displayed
(except where that sequence is the reference).  They can also
serve to omit sequences from exports if desired; in this case
they apply even to the reference sequence, but if the alignments
have a fixed, intrinsic reference it will be grayed out to avoid
exporting "orphaned" blocks.  The choices on this menu affect all
of the windows, not just the current one.
<p>
<dt>Reference:
<dd>
This menu allows you to select a different reference sequence
(unless the parameters file indicates that the alignments have a
fixed, intrinsic reference sequence).  A new multi-pip window
will open, showing the same data from the perspective of the
sequence you chose.  The mark (if any) will be copied to the new
window as closely as possible, and the current zoom region will
be translated to a roughly equivalent one showing the same blocks.
Thereafter, the windows will operate independently.  The text
alignments will be rearranged to put the reference row at the top,
but the rows are always shown in their MAF orientation.  Thus if
the reference row is on the '-' strand, its coordinates will
<i>decrease</i> from left to right in the text panel.  You can
have one multi-pip window for each sequence in the data; if you
already have one for the newly-chosen reference sequence, it will
just be brought to the front unchanged.
<p>
<dt>Zoom - Back:
<dd>
Moves backward in your zoom history for this window, returning
to previous regions.  Does not affect the mark.
<p>
<dt>Zoom - Forward:
<dd>
Moves forward in your zoom history for this window.  Does not
affect the mark.
<p>
<dt>Zoom - Unzoom:
<dd>
Sets the zoom region for this window to the widest, unzoomed
view, i.e., the full length of this entire reference sequence
(and also this secondary sequence, for a dotplot) as specified in
the MAF files.  Has the same effect as entering the "valid range"
endpoints in Set Zoom.  Does not affect the mark.
<p>
<dt>Zoom - Set Zoom:
<dd>
Presents a dialog box that allows you to enter arbitrary zoom
endpoints (within the valid ranges for the applicable sequences).
Any left empty will be interpreted to mean "leave unchanged".
The new region, if different from the current one, is added to
your zoom history for this window.  Any regions forward of the
current point in your history are discarded (similar to a web
browser).  Does not affect the mark.
<p>
<dt>Tags - Tag/Untag Block:
<dd>
The tagging feature allows you to build an arbitrary subset of
the alignment blocks for differential viewing or export (see
<a href="#category">Category Checkboxes</a>).  There is only one
tagged subset in each invocation of Gmaj, and it pertains to
all windows.  This menu item toggles the status of the currently
marked block (the one containing the <a href="#red">red</a>
circle), tagging it if it's not already in the set, and removing
the tag if it is.  
<p>
<dt>Tags - Clear All Tags:
<dd>
Empties the tagged subset by removing the tags from all blocks.
Also hides the category checkboxes if they are no longer useful.
<p>
<dt>Help - About:
<dd>
Displays a message window with information about Gmaj, including
version, author, etc.  Also reports the version of Java you are
currently using.
<p>
<dt>Help - Manual:
<dd>
In applet mode, opens a new browser window to view this help
page.  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.
<p>
<dt>Help - Keys:
<dd>
Displays a message window listing Gmaj's keyboard shortcuts.  No
<code>Alt</code> 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 <code>Esc</code>
first to cancel any text operation and restore the focus to the
active window's menu bar.  <code>Esc</code> will also cancel
dialog and message boxes.
<p>
<dt>Help - Sequence Summary:
<dd>
Displays the aligning extents for all sequences (i.e., the
smallest range in each sequence that includes all of its aligning
regions).  This is useful when fetching annotations from the UCSC
Table Browser or other databases, or for identifying the relevant
parts of already-in-hand annotation files so they can be trimmed
down to size.
<p>
<dt>% Identity Box:
<dd>
Allows you to set a threshold for filtering the displayed
alignments by the percent identity of the plot blocks (which are
pairwise projections of the MAF blocks).  The percent identity
of each plot block is computed as the length-weighted average
percent identity of its gap-free segments, with no penalty for
gaps.  A plot block below the threshold is not drawn or clickable
in the plots, and the row for its secondary sequence is omitted
in the text alignment panel; additionally it is excluded from
the position indicator's block list and from the row of block
buttons for the mark.  However, these plot blocks are only hidden
and still exist otherwise (e.g., for export).  Setting the
threshold will not move the mark, even if the marked position
becomes hidden.  The same threshold applies across all windows,
and keyboard shortcuts make it easy to adjust it up and down.
Also, the percent identity of the current plot block is shown in
the mark indicator when applicable (the current plot block is
either the marked one, or if a dotplot has a different secondary
sequence, the corresponding projection from the same MAF block).
<p>
<dt>Underlays Box:
<dd>
Allows you to set a threshold for filtering the displayed
underlays and highlights based on the optional score values you
have assigned in the annotation files.  The GFF, GTF, and BED
formats already include a score field, and the PipMaker-style
underlay format has been extended to include one as well (see
<a href="gmaj_input.html">Input Files for Gmaj</a>).  Some of
these formats allow floating-point score values, but they will
be rounded off to integers for comparison with the threshold.
Missing scores are treated as the maximum possible value, so
they will never be filtered out; however note that <code>0</code>
(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.
<p>
<dt>Arrow Buttons:
<dd>
These buttons are located to the right of the zoom indicator.
Clicking on one of them will move the zoom region in the
indicated direction by half of its width or height.  The new
region is added to your zoom history like any other zoom
selection, so the Zoom - Back command will return to where you
were as usual.
<p>
<dt>Block Buttons:
<dd>
When a mark is set (e.g. by clicking in a pip or dotplot), a row
of buttons will appear to the right of the mark indicator showing
the <a href="#numbering">block numbers</a> <a href="#cover"
>covering</a> the marked position in the pip.  (If there is not
enough room for all of the buttons, a scrollbar will appear;
also the partition between this panel and the mark indicator is
<a href="#dividers">draggable</a>.)  Clicking on one of the
buttons causes the mark to move to that block (in the same pip),
and the segment colors, text alignment, and mark indicator will
be updated accordingly in all applicable windows.  The new marked
position (<a href="#red">red</a> circle) will be as close as
possible to the same coordinate in the reference sequence, but
it may have to move slightly to avoid gaps.  This makes it
theoretically possible, though rare, that the resulting block
list (and therefore the row of buttons) may change.
<p>
<a name="category"></a>
<dt>Category Checkboxes:
<dd>
These controls are located in a separate panel below the mark
indicator, and allow you to show or hide several groups of
alignment blocks en masse.  There is one checkbox for each of
the alignment files in the input, and an extra one for the tagged
blocks (whose label shows how many blocks are tagged); the colors
of the labels correspond to the plot segments they control.  The
tagged blocks are considered to be withdrawn from their files
for this purpose, so all of the categories are disjoint.
These settings apply across all windows, and as with the
% identity threshold, hidden blocks are omitted from the plots
and certain lists, but still exist otherwise.
<!--
in Gmaj's parlance they define the term <i>visible block</i>:
a block is "visible" if it is not hidden by these checkboxes,
even if it is not actually showing on the screen for some other
reason (e.g. not in zoom region, below % identity threshold,
in bottom half of pip, etc.).
-->
By default this panel only appears when it is
relevant (i.e. if there is more than one alignment file, or you
have used the tagging feature), but you can also show or hide it
temporarily from the Options - Show dialog.
<p>
<dt>Dotplot Buttons:
<dd>
These buttons are located to the right of each pip's sequence
label in the multi-pip window.  Clicking on one of them will
open a dotplot window for that pair of reference and secondary
sequences.  The zoom region will initially be translated from the
current one to show the same blocks, and will thereafter operate
independently.  The mark, however, is shared between the
multi-pip window and all of its dotplots (see <a href="#state"
>The Zoom and the Mark</a>).  If you already have a window for
that dotplot, it will just be brought to the front unchanged.
<p>
<a name="dividers"></a>
<dt>Draggable Dividers:
<dd>
Several of the panel dividers can be moved by dragging them with
the mouse to adjust the amount of space allocated to the items
on each side.  These include the vertical bars separating the
left and right sides of the status indicator panels, and the
horizontal bar separating the pips from the text alignment in a
multi-pip window.  On most platforms Java draws these dividers
with a pattern of little bumps to suggest a grip.  In Gmaj
they also have a sticky feature that remembers if you moved
them manually and keeps them at that position (until they are
rebuilt due to a font change, etc.).  In sticky mode the divider
appears pushed in, like a button; if you want to return to the
default floating mode (where the divider is repositioned
automatically as the panel content changes), just click on the
pushed-in divider to release it.
</dl>
<p>

<p class=hdr>
<h3><a name="copy">Copying and Printing</a></h3>
<p>
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
(<code>Ctrl-C</code>/<code>Ctrl-V</code> on Windows and Linux,
<code>Cmd-C</code>/<code>Cmd-V</code> 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 <a href="gmaj_bugs.html#dialogcopy">bug</a>.)
<p>
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 <code>Esc</code> 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.
<p>
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.)
<p>
To prevent the position indicator from changing when you move the
mouse, hold down the <code>Ctrl</code> key.  This is useful both
for copying the position indicator's contents and for taking
screenshots.
<p>

<!-- <hr align=left noshade size=1 width="20%" color=black> -->
<p class=hdr>
<h3><a name="notes">Footnotes</a></h3>
<p>
<a name="red"></a>
[1]&nbsp;
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 <a href="gmaj_bugs.html#xor"
>patchy rendering</a> when used with Large Fonts.  These special
blocks are drawn last, so they will not be obscured by ordinary
ones.
<p>
<a name="numbering"></a>
[2]&nbsp;
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
<code>maf#.block#</code>.
<p>
<a name="cover"></a>
[3]&nbsp;
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 <b>reference</b> 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 <a href="#category"
>category checkboxes</a>) and meet the % identity threshold (in
the applicable plot).
<p>

<p class=vvlarge>
<hr>
<i>Cathy Riemer, June 2008</i>

<p class=scrollspace>
</body>
</html>