root/galaxy-central/static/gmaj/docs/gmaj_help.html

リビジョン 2, 40.2 KB (コミッタ: hatakeyama, 14 年 前)

import galaxy-central

行番号 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2        "http://www.w3.org/TR/html4/loose.dtd">
3<html>
4<head>
5<title>Starting and Running Gmaj</title>
6<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
7<meta http-equiv="Content-Style-Type" content="text/css">
8<link rel="stylesheet" type="text/css" href="gmaj.css">
9</head>
10<body>
11<p class=vvlarge>
12<h2>Starting and Running Gmaj</h2>
13<p class=vvlarge>
14TABLE OF CONTENTS
15<p class=small>
16<ul class=notop>
17<li><a href="#intro">Introduction</a>
18<li><a href="#start">Starting Gmaj</a>
19<li><a href="#memory">Memory Allocation</a>
20<li><a href="#windows">Multi-Pip and Dotplot Windows</a>
21<li><a href="#state">The Zoom and the Mark</a>
22<li><a href="#layout">Window Layout</a>
23<li><a href="#mouse">Mouse Controls</a>
24<li><a href="#menu">Menus and Widgets</a>
25<li><a href="#copy">Copying and Printing</a>
26<li><a href="#notes">Footnotes</a>
27</ul>
28<p class=vlarge>
29
30<p class=hdr>
31<h3><a name="intro">Introduction</a></h3>
32<p>
33Gmaj can be run in two different modes: as an applet over the
34world-wide web (for viewing data delivered from a server), or as
35a stand-alone application (for viewing data stored on your own
36computer).  These modes are mostly similar but have a few minor
37differences, as noted below.
38<p>
39
40<p class=hdr>
41<h3><a name="start">Starting Gmaj</a></h3>
42<p>
43If you are using Gmaj in applet mode, it will be started for you
44when you visit the applicable web page or submit a query to the
45server.  If the Gmaj window does not appear automatically, just
46click on the labeled button to view the indicated data.  Then
47skip the rest of this section.
48<p>
49If you are using Gmaj in stand-alone mode, you need to start it
50yourself.  The Java runtime environment does not have its own
51GUI, so you generally need to run Gmaj from a command line (e.g.,
52in the Command Prompt window on Windows XP).  The basic command
53to type in looks like this:
54<pre>
55    [path1]java -jar [path2]gmaj.jar
56</pre>
57where <code>[path1]</code> is the location of your
58<code>java</code> program file (perhaps
59<code>c:\windows\system32\</code> on WinXP, or
60<code>/usr/bin/java/</code> on a Unix system), and
61<code>[path2]</code> is the location where the
62<code>gmaj.jar</code> file was installed.  Note that you can
63leave off <code>[path1]</code> if you have set up your system
64command path to include the location of the <code>java</code>
65program.  Depending on how your system is set up, it may also be
66possible to run the jar file directly by just typing its name or
67double-clicking on it.
68<p>
69Since you haven't yet specified any data to display, Gmaj will
70begin by presenting a dialog box to prompt you for the name of
71your input file (see <a href="gmaj_input.html"
72>Input Files for Gmaj</a>).  If the file is located in the
73current directory you can just type its name, otherwise you'll
74need to supply a complete path.  When you click the OK button,
75a window will appear displaying the loaded data.
76<p>
77As an alternative to using the dialog box, you can specify the
78input file (plus additional parameters) on the command line.
79As of this writing, the command syntax is:
80<pre>
81    [path1]java -jar [path2]gmaj.jar
82        [-version] [-help] [-debug] [-urlpause &lt;millisec&gt;]
83        [-initzoom &lt;refseqname&gt; &lt;start&gt; &lt;end&gt;]
84        [-bundle &lt;zipfile&gt;] [&lt;paramfile&gt;|&lt;alignfile&gt;]
85</pre>
86<p>
87This has been wrapped here for easier readability, but should be
88typed all on one line.  Arguments shown in square brackets
89<code>[]</code> are optional, while a vertical bar <code>|</code>
90indicates a choice between alternatives.  Angle brackets
91<code>&lt;&gt;</code> signify meta-syntactic variables that
92should be replaced with your names or numbers.  Don't type any
93of the brackets or the bar.
94<p>
95These parameters do the following:
96<dl>
97<dt>    <code>-version</code>:
98<dd>    Prints a message with information about Gmaj, including
99        version, author, etc.; then exits.
100<dt>    <code>-help</code>:
101<dd>    Prints a brief help message with up-to-date syntax; then
102        exits.
103<dt>    <code>-debug</code>:
104<dd>    Instructs Gmaj to print extra warning messages in
105        your terminal window if certain problems occur.  Normally
106        you won't need this, as it is mainly for development
107        purposes.
108<dt>    <code>-urlpause</code>:
109<dd>    Specifies how many milliseconds the program should pause
110        before retrieving each file from a URL, in order to avoid
111        overloading the server.
112<dt>    <code>-initzoom</code>:
113<dd>    Specifies an initial zoom setting to be applied when the
114        window opens.  You will still be able to invoke the Unzoom
115        or Set Zoom features interactively to see the entire
116        sequence range.  The <code>&lt;refseqname&gt;</code> must
117        match one of the sequence names from the alignment file(s),
118        and the endpoints must include the offset (if any) for that
119        sequence from the parameters file.  To specify the reference
120        sequence without a zoom region, use <code>-1</code> for both
121        endpoints.
122<dt>    <code>-bundle</code>:
123<dd>    Specifies the name of a <code>.zip</code> or
124        <code>.jar</code> file containing some or all of the data
125        files.  This option is mostly used with Gmaj's applet mode
126        to streamline the data download, but it is also supported
127        in stand-alone mode.  It is described in
128        <a href="gmaj_input.html">Input Files for Gmaj</a>.
129<dt>    <code>&lt;paramfile&gt;</code>:
130<dd>    This is the meta-data parameters file that lists the names
131        of all the data files, plus a few related parameters such as
132        display offsets and any intrinsic reference sequence.  For
133        more information about the contents and format of this file,
134        please see <a href="gmaj_input.html">Input Files for Gmaj</a>
135        and <code><a href="sample.gmaj">sample.gmaj</a></code>.
136<dt>    <code>&lt;alignfile&gt;</code>:
137<dd>    If you don't want to use any annotations or other
138        data-related options, you can specify a single alignment
139        file directly, instead of creating a parameters file.
140        This must be in MAF format; see <a href="gmaj_input.html"
141        >Input Files for Gmaj</a> for more details.
142</dl>
143<p>
144
145<p class=hdr>
146<h3><a name="memory">Memory Allocation</a></h3>
147<p>
148If the dataset you want to view is large, Gmaj may run out of
149memory, in which case Java will report an
150<code>OutOfMemoryError</code>.  This message will appear in the
151command window where you started Gmaj (for stand-alone mode) or
152in the Java Console window of your web browser (for applet mode).
153If the Java Console window does not appear when you run the Gmaj
154applet, open the Java Plug-in Control Panel on your computer and
155click the setting for Show Console so you can see this and other
156Java messages.
157<p>
158The <code>OutOfMemoryError</code> is not uncommon, because the
159default amount of memory that Java allocates is rather small.
160You can give it more memory using the <code>-Xmx</code> switch
161(at least with Sun's Java; this option may not be supported by
162all vendors).  For example, when using stand-alone mode the
163command line
164<pre>
165    [path1]java -Xmx1024m -jar [path2]gmaj.jar
166</pre>
167runs Gmaj with a heap memory allowance of ~1 gigabyte.  For the
168applet, you can do this by opening the Java Plug-in Control Panel
169on your computer and entering <code>-Xmx1024m</code> in the Java
170Runtime Parameters box (this will affect all applets you run via
171the Java Plug-in, not just Gmaj).
172<p>
173
174<p class=hdr>
175<h3><a name="windows">Multi-Pip and Dotplot Windows</a></h3>
176<p>
177Gmaj has two kinds of windows.  The main one displays a number
178of pips (percent identity plots) showing the pairwise alignments,
179projected from the multiple alignments, of a particular reference
180sequence against each of the other sequences.  A pip is similar
181to a dotplot, with the horizontal <code>x</code>-axis
182representing positions in the reference sequence, but the
183vertical <code>y</code>-axis represents the percentage of
184matching nucleotides in each gap-free segment of the pairwise
185alignment, instead of its position in the second sequence.  The
186window you see first when Gmaj opens is usually of this type, and
187if the alignments are reference-independent, you can open more of
188these with other sequences as the reference.
189<p>
190The second type of window focuses exclusively on a particular
191pair of sequences, and displays one pip together with its
192corresponding dotplot representation (similar to Gmaj's
193predecessor, <a href="http://globin.bx.psu.edu/dist/laj/"
194>Laj</a>).  These windows are opened upon request, by clicking
195on a button in the header for a particular pip in the multi-pip
196window.  Conceptually the dotplot windows are like children of
197their parent multi-pip window: they have the same reference
198sequence, and if you close a dotplot only that one window closes,
199but if you close the parent all of its children close too.
200<p>
201For the special case where the alignment files have only two
202sequences, the main window is redundant so Gmaj automatically
203hides it and shows the dotplot window directly.
204<p>
205
206<p class=hdr>
207<h3><a name="state">The Zoom and the Mark</a></h3>
208<p>
209Gmaj has two main elements of user state that reflect the user's
210interactive manipulation of the display.  The first is the zoom
211region, i.e. the portion of the reference and secondary sequences
212that is currently displayed; this is one-dimensional for
213multi-pip windows and two-dimensional for dotplots.  As the zoom
214is changed, the previous regions are remembered in a history
215list, so you can go back and forward through it similar to a web
216browser.  Each Gmaj window has its own separate zoom and history;
217when opening a new window the current zoom region is translated
218initially, but then they are independent.  As a convenience,
219each new window begins with several zoom regions already in the
220history: the fully unzoomed sequence length(s), as specified in
221the MAF files; the aligning portion of the applicable sequence(s);
222and an approximate translation of the previous window's current
223zoom (or in the case of the very first window, the initial zoom
224specified in the command-line or applet parameters, if any).
225The boundaries of the current region are displayed in a status
226indicator in the upper right corner of the window, below the
227menu bar.
228<p>
229The second state element is called the "mark", and it represents
230a particular selected point in a particular pairwise pip+dotplot
231and a particular MAF block.  It is typically selected by clicking
232in a pip, dotplot, or text alignment, and is drawn as a small
233<a href="#red">red</a> circle in the plots, and also as a red
234highlight in the text alignment.  Unlike the zoom regions, the
235mark is shared among several windows: there is at most one mark
236for each reference sequence, and it appears in both the multi-pip
237window for that sequence and the dotplot corresponding to
238whichever pip the mark is currently in (the other dotplots, with
239different secondary sequences, will show some indirect information
240about the mark, but not the mark itself).  Thus, moving the mark
241in a dotplot window will also move it in the parent multi-pip and
242vice-versa, but the mark for a different reference sequence is
243independent.  Information about the current mark and plot block
244is displayed in one of the status indicators below the menu bar.
245<p>
246
247<p class=hdr>
248<h3><a name="layout">Window Layout</a></h3>
249<p>
250Each Gmaj window is divided into several sections.  Across the
251top you will see a menu bar (including text boxes for setting
252display thresholds), and below that two lines containing
253status indicators with information about the position of the
254mouse pointer, the boundaries of the currently displayed zoom
255region, and the location of the mark (<a href="#red">red</a>
256circle), along with buttons for sliding the zoom region and
257selecting alternative blocks at the marked position.  Several
258of the dividers between these items are <a href="#dividers"
259>draggable</a>, so you can adjust the relative space they
260occupy.  Below these is a row of category checkboxes, which by
261default will only appear when there is more than one alignment
262file or if you have used the tagging feature.  The menus,
263threshold boxes, buttons, and checkboxes are discussed
264individually in the <a href="#menu">Menus and Widgets</a>
265section of this document.
266<p>
267<i>Ruler:</i><br>
268The first graphical panel is a horizontal ruler that displays
269tick marks corresponding to positions in the currently selected
270reference sequence.  These are intended to give you an immediate
271general feel for the location and scale of the region being
272displayed.  Precise locations can be determined via the position
273indicator, which displays the exact coordinate of the mouse
274pointer.
275<p>
276<i>Reconstruction scores:</i><br>
277For ancestral reconstruction alignments, the MAF files may
278contain scores indicating the confidence that 1) a particular
279inferred ancestral nucleotide is correct, and that 2) it was
280present at all.  The next two panels display bar graphs of these
281scores when the ancestral sequence is the reference.  The scores
282are binned according to the current zoom region and panel width,
283and the mean score for each bin is graphed on a scale of 0 - 1
284(note that the scores are transformed via simple linear scaling,
285and should not be interpreted as probabilities).  For this to
286work, the parameters file must specify which organism the scores
287apply to.  Otherwise, or if there are no scores in the file, or
288if a different sequence is currently the reference, these panels
289will not appear.  The position indicator displays the horizontal
290coordinate and vertical score position of the mouse pointer,
291along with the score for the bar at that location (if any).
292<p>
293<i>Linkbars:</i><br>
294Next is a panel that can display links to additional information
295about various regions in the current reference sequence.  Each
296annotation is represented by a color-coded bar spanning the
297region's position in the sequence.  (The bars' vertical positions
298are not meaningful; they are only placed in rows for convenience,
299to keep them from overlapping.)  Pointing to a particular bar
300will cause the position indicator to display the <code>x</code>
301coordinate of the pointer, and also the type and description of
302that bar's annotation; otherwise only the <code>x</code>
303coordinate will be shown.  In applet mode, clicking on a bar will
304open a separate browser window to visit the corresponding web
305site.  In stand-alone mode Gmaj is not working within a web
306browser, so instead it displays the URL for you to visit manually
307via copy-and-paste.  If no links file is provided for the current
308sequence, this panel will not appear.
309<p>
310<i>Sequence features:</i><br>
311The next two panels contain schematic diagrams of the known
312exons and interspersed repeats in the current reference sequence,
313respectively (if these files are provided).  Any additional
314features such as CpG islands are included with the repeats (which
315is why the label says "repeats+").  The diagram for repeats uses
316the same symbols as <a href="http://pipmaker.bx.psu.edu/pipmaker/"
317>PipMaker</a> to indicate the various repeat categories (Alu, MIR,
318etc.), but only if either the PipMaker category or the
319<a href="http://www.repeatmasker.org/">RepeatMasker</a> name and
320class/family are available.  For example, BED and GTF repeat
321files from the <a href="http://genome.ucsc.edu/cgi-bin/hgTables"
322>UCSC Table Browser</a> include the RepeatMasker name but not the
323class/family, so Gmaj cannot determine the PipMaker category and
324draws all of them as "Other".  As usual, the position indicator
325displays the <code>x</code> coordinate of the mouse pointer, and
326also identifies any features at that position.
327<p>
328<i>Plots:</i><br>
329The following panels display the alignment plots according to the
330window type: either a scrollable stack of <a href="#windows"
331>pips</a> (for the reference sequence against each of the others)
332or a single pip and its corresponding dotplot.  For pips, only
333the top half of each plot is shown, since segments matching less
334than 50% are usually not very interesting.  Plot segments from
335the primary alignment file are drawn with thin black lines, while
336those from subsequent files are drawn with thicker brown lines.
337Tagged blocks are green, and the marked block is red (or orange
338if it is also tagged), though these may <a href="#red">vary</a>
339on colored backgrounds.  When plot segments overlap, the marked
340and tagged ones are drawn "on top" so they won't be obscured,
341followed by other blocks from the primary alignment file and then
342the remaining files.  Plots that are completely empty (i.e. if
343that pair of sequences never occurs together in any of the
344alignment blocks) will be painted gray.  An additional feature of
345these panels is that colored backgrounds, or "underlays", can be
346used to highlight regions of interest (if files with this
347information are provided); dotplots can display these for both
348the reference and secondary sequences.  Vertical blue bars at the
349edges of the plots represent the boundaries of the current zoom
350region, whose endpoints are displayed in the zoom indicator.  For
351a pip, the position indicator displays the horizontal coordinate
352and vertical percentage position of the mouse pointer, along with
353a list of <a href="#numbering">block numbers</a> <a href="#cover"
354>covering</a> that location.  For a dotplot, it displays the
355horizontal and vertical coordinates in the reference and secondary
356sequences, respectively.  It will also display labels for the
357colored regions in both types of plots, if these are included in
358the underlay files.
359<p>
360<i>Text view:</i><br>
361The bottom panel displays a nucleotide-level view of a single
362selected alignment block: the one containing the mark
363(<a href="#red">red</a> circle).  Initially it is empty, since
364you haven't set the mark yet.  The top row of this display shows
365the current reference sequence, while the rows for the other
366sequences show a dot (<code>.</code>) wherever they match the
367reference sequence, and only explicitly list the nucleotides that
368don't match.  (This matching is case-insensitive to deal with
369soft masking, but non-nucleotide characters such as
370<code>X</code> or <code>N</code> never match anything, even
371themselves.)  All of the sequences will likely have had gaps
372(<code>-</code>) inserted by the alignment program.  Note that
373most of the blocks will be much too long to fit across this
374window, so a scrollbar is provided; the relative size of the
375scrollbar's slider indicates what fraction of the alignment is
376shown in the window.  Colored "highlights" (analogous to the plot
377underlays) can also be specified for each sequence; otherwise
378Gmaj will provide default highlights based on the exons files
379(if any).  Whenever the mouse pointer is in this bottom panel,
380the position indicator displays its location in the format
381<code>n(x)</code>, where <code>n</code> is the column position
382in this aligned block (starting with 0), and <code>x</code> is
383the sequence position in the individual row (i.e., in that entire
384chromosome or contig, starting with 1).  Note that <code>x</code>
385does not include the gaps, but <code>n</code> does.  Labels for
386any highlights at that position are also displayed.
387<p>
388With the exception of the text view, all of these data panels use
389the same horizontal coordinate scale (i.e., position in the
390current reference sequence), and they are always kept vertically
391aligned so they can be compared easily.  Note that in the
392multi-pip window the partition between the graphical panels and
393the text view is <a href="#dividers">draggable</a>, so you can
394adjust the relative amount of space they occupy.  Also, individual
395panels can be hidden if desired, using the Options - Show dialog
396(see <a href="#menu">Menus and Widgets</a>).
397<p>
398<!--
399<i>Dotplot:</i><br>
400The large middle panel displays a dotplot view of the alignments,
401with the reference sequence along the horizontal
402<code>x</code>-axis and the secondary sequence along the vertical
403<code>y</code>-axis.  If the second sequence contains multiple
404contigs, they will appear as separate horizontal bands across the
405plot, each with its own <code>y</code>-axis coordinate system.
406Whenever the mouse pointer is in this panel, the position
407indicator displays its location in the format <code>x,y</code>,
408where <code>x</code> is the position in the horizontal sequence
409and <code>y</code> is the position in the vertical sequence.  If
410there are multiple contigs, then the contig name will be
411displayed as well (actually only the first word is displayed, to
412prevent long names from crowding out the other information).
413<p>
414-->
415
416<p class=hdr>
417<h3><a name="mouse">Mouse Controls</a></h3>
418<p>
419As discussed in more detail <a href="#layout">above</a>,
420pointing with the mouse in the plots or other panels causes the
421position indicator below the menu bar to display information
422about that location and/or data item.
423<p>
424You can select a particular alignment block by clicking on one
425of its segments in any of the plots (pips or dotplots) with the
426left mouse button.  (You don't have to click exactly on it,
427because Gmaj will automatically jump to the nearest point if you
428miss; however proximity is measured in bases, not pixels, which
429can lead to non-intuitive results if the dotplot's zoom scale is
430highly skewed.)  The spot will be marked with a small
431<a href="#red">red</a> circle, and the entire alignment block
432containing the mark will change color from black to
433<a href="#red">red</a> in all of the plots for that reference
434sequence (each block typically spans several gap-free segments).
435Also, the corresponding text view for that block will appear in
436the bottom panel with the marked position highlighted.  Lastly,
437the mark indicator will be filled in with information about the
438marked block and position, and a row of buttons will appear next
439to it showing the <a href="#numbering">block numbers</a>
440<a href="#cover">covering</a> the marked location.  These buttons
441allow convenient selection of a different block at the same
442position in the reference sequence, from the same or a different
443alignment file (see <a href="#menu">Menus and Widgets</a>).
444Note that there is only one mark at a time for each reference
445sequence, so the previous one, if any, will be unmarked.
446<p>
447In a similar fashion, clicking the left mouse button in the
448text view will move the mark (both the highlight and the
449<a href="#red">red</a> circle) to that position.  However, gap
450positions cannot be selected in this manner because they do not
451correspond to plot segments; if you click in a gap, the nearest
452gap-free position is selected instead.  Also, if you click on a
453position in the reference sequence (which has no corresponding
454pip), the mark will move to the new column but will remain in
455the same pip as before.
456<p>
457You can "zoom in" on a particular region by dragging out a
458rectangle with the left mouse button in any of the white panels
459(ruler, annotations, pip, or dotplot).  All of these panels
460will always zoom together, to keep them lined up.  This can be
461repeated until the maximum resolution is reached; after that
462Gmaj will display an error message.  Additional zoom features
463are available via the Zoom menu and arrow buttons (see
464<a href="#menu">Menus and Widgets</a>).  Note that selecting
465a new region will cause any entries in your zoom history that
466are forward of the current point to be discarded, similar to
467a web browser.  If your rectangle is very tiny it will be
468treated as a click instead, to avoid unintended zooming.
469<p>
470Holding down the right mouse button over any of the white
471panels adds crosshairs at the mouse pointer's location, which
472is convenient for determining whether two regions really line
473up.  If you have a one-button mouse, you can achieve the same
474effect by applying the <code>Shift</code> key when initially
475pressing the mouse button.
476<p>
477Note that these controls only work in the active window (usually
478indicated in the operating system by a differently colored title
479bar).  If a window is not the active one, then your first click
480in it just activates the window; you will need to click again
481to set the mark, select a region, open a menu, etc.
482<p>
483
484<p class=hdr>
485<h3><a name="menu">Menus and Widgets</a></h3>
486<p>
487<dl>
488<dt>File - Open:
489<dd>
490Loads a new set of data files into Gmaj, replacing the currently
491displayed data.  A dialog box is presented for you to specify the
492new input file.  (See discussion under <a href="#start"
493>Starting Gmaj</a>, above.)  This menu item does not appear in
494applet mode, because the user is unlikely to know the locations
495of other data files on the server; instead the webmaster should
496set up separate access for each dataset.
497<p>
498<dt>File - Export:
499<dd>
500Opens a dialog box that allows you to save alignment blocks in
501MAF format or as FastA sequence files.  A variety of options are
502available re: which blocks to export, whether they should be
503clipped and/or cleaned up, whether to omit certain sequences,
504etc.  Note that all-gap rows are always skipped, and so are
505blocks that have no rows left.  When exporting in MAF format,
506if the alignment has a fixed, intrinsic reference sequence and
507that row is all gaps, the entire block will be skipped.  When
508exporting FastA sequences, a separate file is created for each
509sequence name (i.e. species or contig), and there is an option
510to restore sequences that align in reverse complement to their
511original orientation (which will also swap the order of the
512endpoint coordinates in the FastA header).  By default export is
513not available in applet mode, because security restrictions make
514it very awkward to save files on the client computer.  However,
515the applet administrator can <a href="gmaj_install.html#page"
516>specify a URL</a> where the output can be sent instead (in this
517case only MAF format is supported).
518<p>
519<dt>File - Close:
520<dd>
521Closes the current window, and if it is a multi-pip window, all
522of its dotplot children are closed as well.  When no windows are
523left, Gmaj will exit.
524<p>
525<dt>File - Exit:
526<dd>
527Exits from Gmaj.  In stand-alone mode, also exits from Java.
528<p>
529<dt>Options:
530<dd>
531This menu controls some of the aesthetic aspects of Gmaj.  You
532can choose between two sizes of fonts, which will also affect
533some other viewability settings, such as the thickness of the
534plot segments, the radius and thickness of the mark circle, the
535blackness of the ruler numbers, and the height of the pips.  You
536can also choose to make the mark circle and the selected block's
537plot segments change color with the background instead of always
538being red (this makes them visible against red underlays, but is
539more complicated to explain in a figure legend and causes
540<a href="gmaj_bugs.html#xor">patchy rendering</a> when used with
541Large Fonts).  Lastly, the Show item opens a dialog where you can
542choose which panels to display or hide, and whether the underlays
543should be painted on dotplots.  The sequence selections here
544control which pips, dotplot windows, and text rows are displayed
545(except where that sequence is the reference).  They can also
546serve to omit sequences from exports if desired; in this case
547they apply even to the reference sequence, but if the alignments
548have a fixed, intrinsic reference it will be grayed out to avoid
549exporting "orphaned" blocks.  The choices on this menu affect all
550of the windows, not just the current one.
551<p>
552<dt>Reference:
553<dd>
554This menu allows you to select a different reference sequence
555(unless the parameters file indicates that the alignments have a
556fixed, intrinsic reference sequence).  A new multi-pip window
557will open, showing the same data from the perspective of the
558sequence you chose.  The mark (if any) will be copied to the new
559window as closely as possible, and the current zoom region will
560be translated to a roughly equivalent one showing the same blocks.
561Thereafter, the windows will operate independently.  The text
562alignments will be rearranged to put the reference row at the top,
563but the rows are always shown in their MAF orientation.  Thus if
564the reference row is on the '-' strand, its coordinates will
565<i>decrease</i> from left to right in the text panel.  You can
566have one multi-pip window for each sequence in the data; if you
567already have one for the newly-chosen reference sequence, it will
568just be brought to the front unchanged.
569<p>
570<dt>Zoom - Back:
571<dd>
572Moves backward in your zoom history for this window, returning
573to previous regions.  Does not affect the mark.
574<p>
575<dt>Zoom - Forward:
576<dd>
577Moves forward in your zoom history for this window.  Does not
578affect the mark.
579<p>
580<dt>Zoom - Unzoom:
581<dd>
582Sets the zoom region for this window to the widest, unzoomed
583view, i.e., the full length of this entire reference sequence
584(and also this secondary sequence, for a dotplot) as specified in
585the MAF files.  Has the same effect as entering the "valid range"
586endpoints in Set Zoom.  Does not affect the mark.
587<p>
588<dt>Zoom - Set Zoom:
589<dd>
590Presents a dialog box that allows you to enter arbitrary zoom
591endpoints (within the valid ranges for the applicable sequences).
592Any left empty will be interpreted to mean "leave unchanged".
593The new region, if different from the current one, is added to
594your zoom history for this window.  Any regions forward of the
595current point in your history are discarded (similar to a web
596browser).  Does not affect the mark.
597<p>
598<dt>Tags - Tag/Untag Block:
599<dd>
600The tagging feature allows you to build an arbitrary subset of
601the alignment blocks for differential viewing or export (see
602<a href="#category">Category Checkboxes</a>).  There is only one
603tagged subset in each invocation of Gmaj, and it pertains to
604all windows.  This menu item toggles the status of the currently
605marked block (the one containing the <a href="#red">red</a>
606circle), tagging it if it's not already in the set, and removing
607the tag if it is. 
608<p>
609<dt>Tags - Clear All Tags:
610<dd>
611Empties the tagged subset by removing the tags from all blocks.
612Also hides the category checkboxes if they are no longer useful.
613<p>
614<dt>Help - About:
615<dd>
616Displays a message window with information about Gmaj, including
617version, author, etc.  Also reports the version of Java you are
618currently using.
619<p>
620<dt>Help - Manual:
621<dd>
622In applet mode, opens a new browser window to view this help
623page.  In stand-alone mode Gmaj is not working within a web
624browser, so instead it displays the URL for you to visit manually
625via copy-and-paste.
626<p>
627<dt>Help - Keys:
628<dd>
629Displays a message window listing Gmaj's keyboard shortcuts.  No
630<code>Alt</code> key is needed.  The shortcuts will not work if
631the keyboard focus is in a text area (threshold boxes, status
632indicators, text alignment, panel headers, etc., as indicated by
633a purple border or highlight); in this case press <code>Esc</code>
634first to cancel any text operation and restore the focus to the
635active window's menu bar.  <code>Esc</code> will also cancel
636dialog and message boxes.
637<p>
638<dt>Help - Sequence Summary:
639<dd>
640Displays the aligning extents for all sequences (i.e., the
641smallest range in each sequence that includes all of its aligning
642regions).  This is useful when fetching annotations from the UCSC
643Table Browser or other databases, or for identifying the relevant
644parts of already-in-hand annotation files so they can be trimmed
645down to size.
646<p>
647<dt>% Identity Box:
648<dd>
649Allows you to set a threshold for filtering the displayed
650alignments by the percent identity of the plot blocks (which are
651pairwise projections of the MAF blocks).  The percent identity
652of each plot block is computed as the length-weighted average
653percent identity of its gap-free segments, with no penalty for
654gaps.  A plot block below the threshold is not drawn or clickable
655in the plots, and the row for its secondary sequence is omitted
656in the text alignment panel; additionally it is excluded from
657the position indicator's block list and from the row of block
658buttons for the mark.  However, these plot blocks are only hidden
659and still exist otherwise (e.g., for export).  Setting the
660threshold will not move the mark, even if the marked position
661becomes hidden.  The same threshold applies across all windows,
662and keyboard shortcuts make it easy to adjust it up and down.
663Also, the percent identity of the current plot block is shown in
664the mark indicator when applicable (the current plot block is
665either the marked one, or if a dotplot has a different secondary
666sequence, the corresponding projection from the same MAF block).
667<p>
668<dt>Underlays Box:
669<dd>
670Allows you to set a threshold for filtering the displayed
671underlays and highlights based on the optional score values you
672have assigned in the annotation files.  The GFF, GTF, and BED
673formats already include a score field, and the PipMaker-style
674underlay format has been extended to include one as well (see
675<a href="gmaj_input.html">Input Files for Gmaj</a>).  Some of
676these formats allow floating-point score values, but they will
677be rounded off to integers for comparison with the threshold.
678Missing scores are treated as the maximum possible value, so
679they will never be filtered out; however note that <code>0</code>
680(which is sometimes used to mean "no score") will not be changed,
681since Gmaj cannot distinguish this from a score that is really
682zero.  As with the % Identity box, the same threshold applies
683across all windows, and keyboard shortcuts make it easy to adjust
684it up and down.  Also, pointing to a particular underlay or
685highlight will show that annotation's score in the position
686indicator.
687<p>
688<dt>Arrow Buttons:
689<dd>
690These buttons are located to the right of the zoom indicator.
691Clicking on one of them will move the zoom region in the
692indicated direction by half of its width or height.  The new
693region is added to your zoom history like any other zoom
694selection, so the Zoom - Back command will return to where you
695were as usual.
696<p>
697<dt>Block Buttons:
698<dd>
699When a mark is set (e.g. by clicking in a pip or dotplot), a row
700of buttons will appear to the right of the mark indicator showing
701the <a href="#numbering">block numbers</a> <a href="#cover"
702>covering</a> the marked position in the pip.  (If there is not
703enough room for all of the buttons, a scrollbar will appear;
704also the partition between this panel and the mark indicator is
705<a href="#dividers">draggable</a>.)  Clicking on one of the
706buttons causes the mark to move to that block (in the same pip),
707and the segment colors, text alignment, and mark indicator will
708be updated accordingly in all applicable windows.  The new marked
709position (<a href="#red">red</a> circle) will be as close as
710possible to the same coordinate in the reference sequence, but
711it may have to move slightly to avoid gaps.  This makes it
712theoretically possible, though rare, that the resulting block
713list (and therefore the row of buttons) may change.
714<p>
715<a name="category"></a>
716<dt>Category Checkboxes:
717<dd>
718These controls are located in a separate panel below the mark
719indicator, and allow you to show or hide several groups of
720alignment blocks en masse.  There is one checkbox for each of
721the alignment files in the input, and an extra one for the tagged
722blocks (whose label shows how many blocks are tagged); the colors
723of the labels correspond to the plot segments they control.  The
724tagged blocks are considered to be withdrawn from their files
725for this purpose, so all of the categories are disjoint.
726These settings apply across all windows, and as with the
727% identity threshold, hidden blocks are omitted from the plots
728and certain lists, but still exist otherwise.
729<!--
730in Gmaj's parlance they define the term <i>visible block</i>:
731a block is "visible" if it is not hidden by these checkboxes,
732even if it is not actually showing on the screen for some other
733reason (e.g. not in zoom region, below % identity threshold,
734in bottom half of pip, etc.).
735-->
736By default this panel only appears when it is
737relevant (i.e. if there is more than one alignment file, or you
738have used the tagging feature), but you can also show or hide it
739temporarily from the Options - Show dialog.
740<p>
741<dt>Dotplot Buttons:
742<dd>
743These buttons are located to the right of each pip's sequence
744label in the multi-pip window.  Clicking on one of them will
745open a dotplot window for that pair of reference and secondary
746sequences.  The zoom region will initially be translated from the
747current one to show the same blocks, and will thereafter operate
748independently.  The mark, however, is shared between the
749multi-pip window and all of its dotplots (see <a href="#state"
750>The Zoom and the Mark</a>).  If you already have a window for
751that dotplot, it will just be brought to the front unchanged.
752<p>
753<a name="dividers"></a>
754<dt>Draggable Dividers:
755<dd>
756Several of the panel dividers can be moved by dragging them with
757the mouse to adjust the amount of space allocated to the items
758on each side.  These include the vertical bars separating the
759left and right sides of the status indicator panels, and the
760horizontal bar separating the pips from the text alignment in a
761multi-pip window.  On most platforms Java draws these dividers
762with a pattern of little bumps to suggest a grip.  In Gmaj
763they also have a sticky feature that remembers if you moved
764them manually and keeps them at that position (until they are
765rebuilt due to a font change, etc.).  In sticky mode the divider
766appears pushed in, like a button; if you want to return to the
767default floating mode (where the divider is repositioned
768automatically as the panel content changes), just click on the
769pushed-in divider to release it.
770</dl>
771<p>
772
773<p class=hdr>
774<h3><a name="copy">Copying and Printing</a></h3>
775<p>
776Gmaj supports copy/paste via the system clipboard from most of
777its text panels and dialog boxes, using mouse selection followed
778by the standard keystrokes
779(<code>Ctrl-C</code>/<code>Ctrl-V</code> on Windows and Linux,
780<code>Cmd-C</code>/<code>Cmd-V</code> on Mac).  Some labels are
781not copyable, but their values generally are.  (Exception: with
782some versions of Java, all dialog text may be uncopyable in
783applet mode due to a <a href="gmaj_bugs.html#dialogcopy">bug</a>.)
784<p>
785In Gmaj's multi-pip and dotplot windows the text alignment, panel
786headers, and status indicators are copyable.  Clicking in any of
787these components (e.g. to sweep out a selection with the mouse)
788will transfer the keyboard focus to that component, as indicated
789by purple lines around it.  This is necessary for the Copy
790keystroke to work; however it means that Gmaj's other keyboard
791shortcuts will be disabled until the focus is restored, either by
792clicking somewhere else or by pressing the <code>Esc</code> key.
793Note that the mouse selection in the text alignment is
794rectangular (unlike the usual line-wrapped stream), and all of
795these components can be scrolled if necessary by dragging the
796mouse just outside their borders.
797<p>
798Gmaj does not currently have its own print capability.  The
799recommended way to record a particular Gmaj view is to use your
800operating system's "screenshot", "print screen", or "grab"
801facility to save an image of the window to a file, then adjust
802it as needed using image-editing software.  (Be careful with
803rescaling and format conversions, as these may degrade the
804image.)
805<p>
806To prevent the position indicator from changing when you move the
807mouse, hold down the <code>Ctrl</code> key.  This is useful both
808for copying the position indicator's contents and for taking
809screenshots.
810<p>
811
812<!-- <hr align=left noshade size=1 width="20%" color=black> -->
813<p class=hdr>
814<h3><a name="notes">Footnotes</a></h3>
815<p>
816<a name="red"></a>
817[1]&nbsp;
818By default the circular mark and the selected block's plot
819segments are always red (or orange), regardless of the background
820color behind them, and similarly tagged blocks are always green.
821A setting on the Options menu can make these colors vary with
822the background (so they are not invisible against like-colored
823underlays), however this causes <a href="gmaj_bugs.html#xor"
824>patchy rendering</a> when used with Large Fonts.  These special
825blocks are drawn last, so they will not be obscured by ordinary
826ones.
827<p>
828<a name="numbering"></a>
829[2]&nbsp;
830Blocks in the MAF files are numbered consecutively, starting
831with 0.  MAF files are also numbered starting with 0, in the
832order they are listed in the parameters file.  If there are
833several MAF files, they are catenated into one big list of
834blocks, and the block numbers for the second file continue where
835the first left off.  However, Gmaj also records the relative
836block numbers within each file, and displays this information
837in the mark indicator and certain error messages in the form
838<code>maf#.block#</code>.
839<p>
840<a name="cover"></a>
841[3]&nbsp;
842An alignment block is considered to cover a plot position if it
843contains rows for both of the plot's sequences and the position
844falls within the endpoints of the <b>reference</b> sequence's
845row (not necessarily the row for the other sequence, as this is
846a pip-oriented computation); there are no "holes" due to gaps.
847In order to appear in the row of block buttons for the mark or in
848the position indicator's block list for pips, a block must also
849be in a visible category (according to the <a href="#category"
850>category checkboxes</a>) and meet the % identity threshold (in
851the applicable plot).
852<p>
853
854<p class=vvlarge>
855<hr>
856<i>Cathy Riemer, June 2008</i>
857
858<p class=scrollspace>
859</body>
860</html>
Note: リポジトリブラウザについてのヘルプは TracBrowser を参照してください。