From 07a7dd60af822bfc02e57ddfe62a03ee311cf192 Mon Sep 17 00:00:00 2001 From: Daniel Blankenberg Date: Mon, 30 Jul 2007 19:22:24 +0000 Subject: [PATCH] Update GMAJ to latest version. Also have help link to the local copy of the supplied help documents. --- static/gmaj/docs/gmaj.css | 6 +- static/gmaj/docs/gmaj_bugs.html | 31 +- static/gmaj/docs/gmaj_help.html | 464 +++++++++++++++++--------- static/gmaj/docs/gmaj_input.html | 509 +++++++++++++++++++++++------ static/gmaj/docs/gmaj_install.html | 13 +- static/gmaj/docs/gmaj_news.html | 147 +++++++-- static/gmaj/docs/gmaj_readme.html | 32 +- static/gmaj/docs/sample.gmaj | 166 +++++++--- static/gmaj/gmaj.jar | Bin 226931 -> 228409 bytes tools/visualization/GMAJ.xml | 7 +- 10 files changed, 1010 insertions(+), 365 deletions(-) diff --git a/static/gmaj/docs/gmaj.css b/static/gmaj/docs/gmaj.css index 7e41038d761..e517f559f0f 100644 --- a/static/gmaj/docs/gmaj.css +++ b/static/gmaj/docs/gmaj.css @@ -1,17 +1,19 @@ -body { color: black; background-color: white; background-repeat: no-repeat } /* pre { font-family: monospace; } */ /* recommended at http://www.w3.org/MarkUp/Guide/Style, */ /* but confuses Mozilla */ +body { color: black; background-color: white; background-repeat: no-repeat } p.vvlarge { margin-top: 6ex; margin-bottom: 0 } p.vlarge { margin-top: 4ex; margin-bottom: 0 } p.large { margin-top: 3ex; margin-bottom: 0 } p { margin-top: 2ex; margin-bottom: 0 } p.small { margin-top: 1ex; margin-bottom: 0 } p.tiny { margin-top: 0.5ex; margin-bottom: 0 } +p.hdr { margin-top: 3ex; margin-bottom: 0 } +p.subhdr { margin-top: 2.5ex; margin-bottom: 0 } p.right { text-align: right; margin-right: 1ex } p.scrollspace { margin-top: 100em; margin-bottom: 0 } /* tbody { text-align: left; vertical-align: baseline } */ ul.lessindent { padding-left: 4ex } -img.lower { vertical-align: -4ex } +img.lower { vertical-align: -3ex } code { padding-left: 0.5ex; padding-right: 0.5ex } .baseline { vertical-align: baseline } .notop { margin-top: 0 } diff --git a/static/gmaj/docs/gmaj_bugs.html b/static/gmaj/docs/gmaj_bugs.html index a0fd1bb1d43..2a2f221c44e 100644 --- a/static/gmaj/docs/gmaj_bugs.html +++ b/static/gmaj/docs/gmaj_bugs.html @@ -13,7 +13,8 @@

The following anomalies in Gmaj's display and behavior have been observed, but not yet resolved. Some of these are intermittent, -and some may depend on your platform and/or version of Java. +and some may depend on your computer platform and/or version of +Java.

If you experience any of these (or similar) problems, it may help to switch to a different version of Java. For example, the first @@ -60,6 +61,32 @@ around the problem in future releases of Gmaj. pasting elsewhere. This is apparently due to a bug in Java; hopefully Sun will fix it eventually.

+

  • Patchy rendering of mark circle and/or red segments.  + When using the Large Fonts option with Mark Color Varies, + the red circle and plot segments may not appear as solid + as they should. This is because Mark Color Varies is + implemented using Java's XOR drawing mode, and the thick + lines are built up from several thin ones, so whenever two + red pixels overlap they turn white again. Fixing this will + likely involve a custom implementation of Mark Color Varies + that doesn't use XOR. In the meantime, switching to Mark + Always Red when using Large Fonts should solve the problem + (except that it will be invisible against red underlays). +

    + +

    Mouse Controls

    You can select a particular alignment block by clicking on one -of its segments in any of the pips with the left mouse button. -(Actually you don't have to click exactly on it, because -Gmaj will automatically jump to the nearest point if you miss.) -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 -pips (each block typically spans several gap-free segments). -Also, the corresponding text view for that block will appear in -the bottom panel with the selected 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 (see Menus and Buttons). Note that there is only one mark at a -time in each window, so the previous one, if any, will be -unmarked. +of its segments in any of the plots (pips or dotplots) with the +left mouse button. (Actually you don't have to click exactly on +it, because Gmaj will automatically jump to the nearest point if +you miss.) 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 (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 pip segments; if you click in a gap, the nearest +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 @@ -311,12 +421,12 @@ 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, links, exons, repeats, or pip). All of these 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 Buttons). Note that selecting +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). @@ -329,7 +439,8 @@ effect by applying the Shift key when initially pressing the mouse button.

    -

    Menus and Buttons

    +

    +

    Menus and Widgets

    File - Open: @@ -367,27 +478,32 @@ Exits from Gmaj. In stand-alone mode, also exits from Java.
    This menu controls some of the aesthetic aspects of Gmaj. You can choose between two sizes of fonts, which will also affect -some other visibility settings, such as 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 pip segments always red, instead of -changing with the background color (this is easier to explain in -a figure legend, but makes them invisible against red underlays). -Lastly, the Show item opens a dialog where you can choose which -individual panels to display or hide (currently it does not -affect which text rows are displayed, however). The choices on -this menu affect all of the windows, not just the current one. +some other visibility 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 always red, instead of changing with the background +color (this is easier to explain in a figure legend, but makes +them invisible against red underlays). Lastly, the Show item +opens a dialog where you can choose which individual panels to +display or hide (the sequence selections here also affect which +text rows and dotplot windows are shown), and whether the +underlays should be painted on dotplots. The choices on this +menu affect all of the windows, not just the current one.

    -

    RefSequence: +
    Reference:
    This menu allows you to select a different reference sequence (unless the parameters file indicates that the alignment has a -fixed, intrinsic reference sequence). A new 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, but the zoom will not. Thereafter, the -windows will operate independently. You can have one window -open for each sequence in the data. +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. 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.

    Zoom - Back:
    @@ -401,15 +517,17 @@ affect the mark.

    Zoom - Unzoom:
    -Sets the zoom region to the widest, unzoomed view, i.e., the -full range for this reference sequence as specified in the -.maf file. Has the same effect as entering the -"valid range" endpoints in Set Zoom. Does not affect the mark. +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 file. Has the same effect as entering the "valid range" +endpoints in Set Zoom. Does not affect the mark.

    Zoom - Set Zoom:
    Presents a dialog box that allows you to enter arbitrary zoom -endpoints (within the valid range for this reference sequence). +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 @@ -430,60 +548,98 @@ via copy-and-paste.

    Help - Keys:
    -Displays a message window listing Gmaj's keyboard shortcuts. No -Alt key is needed, since Gmaj doesn't use the -keyboard for much else. +Displays a message window listing Gmaj's keyboard shortcuts. +No Alt key is needed, since Gmaj doesn't use the +keyboard for much else. The shortcuts will not work if the +keyboard focus is in a text box (e.g. the one for % Identity); +in this case press Esc first to cancel the text +entry and restore the focus to the active window's menu bar. +Esc will also cancel dialog and message boxes. +

    +

    % Identity Box: +
    +Allows you to set a threshold for limiting 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. Blocks below the +threshold are not drawn or clickable in the plots, but still +exist otherwise (e.g. in the position indicator's block list for +pips; also a block already displayed in the text panel will not +disappear). 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 (this is either the marked one, +or if a dotplot has a different secondary sequence, the +corresponding projection from the same MAF block).

    Arrow Buttons:
    -These two buttons are located to the right of the zoom indicator. -Clicking on one of them will slide the zoom region to the left or -right, respectively, by half of its width. The new region is +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. 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.

    Block Buttons:
    -When a block is selected by clicking on a pip, a row of buttons -will appear to the right of the mark indicator showing all of the -block numbers covering the marked position. -(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 draggable.) Clicking on one of the buttons causes -the mark to move to that block (in the same pip), and the pip -segment colors, text alignment, and mark indicator will be -updated accordingly. The new marked position (red 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. +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 +all of the block numbers covering 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 draggable.) +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 (red 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. +

    +

    Dotplot Buttons: +
    +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 The Zoom and the Mark). If you already have a window for +that dotplot, it will just be brought to the front unchanged.

    +

    Footnotes

    [1]  -The circular mark and the selected block's pip segments are red +The circular mark and the selected block's plot segments are red when the background is white, but by default are displayed in -different colors against other backgrounds to ensure good -contrast. A setting on the Options menu can make them always -red if desired. The selected pip segments are drawn last, so +different colors against other backgrounds for improved contrast. +A setting on the Options menu can make them always red if +desired. The selected block's plot segments are drawn last, so they will not be obscured by other blocks.

    [2]  -An alignment block is considered to cover a pip position if it -contains rows for both of the pip's sequences and the position -falls within the endpoints of the reference sequence's row; there -are no "holes" due to gaps. Blocks in the .maf file -are numbered consecutively, starting with 0. +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. +Blocks in the MAF file are numbered consecutively, starting +with 0.

    -Cathy Riemer, June 2006 +Cathy Riemer, July 2007

    diff --git a/static/gmaj/docs/gmaj_input.html b/static/gmaj/docs/gmaj_input.html index b20cb80e159..09082bdb679 100644 --- a/static/gmaj/docs/gmaj_input.html +++ b/static/gmaj/docs/gmaj_input.html @@ -21,13 +21,15 @@ TABLE OF CONTENTS

  • Alignments
  • Exons
  • Repeats -
  • Annotation Links +
  • Linkbars
  • Underlays
  • Highlights
  • Color List +
  • Generic Annotation Formats

    +

    Introduction

    This page describes the input files supported by Gmaj, and their @@ -36,14 +38,30 @@ required; the others are optional. Except where noted, all information applies to both the stand-alone and applet modes of Gmaj.

    -The annotation formats (exons, etc.) are essentially the same as -those used by Laj -and PipMaker, -and you may find that PipMaker's associated utilities, such as -PipHelper and the -PipTools, -can greatly facilitate the preparation of your files. +For annotations, Gmaj supports two broad categories of file +formats. The original set of formats is essentially the same as +those used by PipMaker and Laj, where each destination for the data (exons panel, color +underlays, etc.) has its own file format tailored for the needs of +that display. These files can be cumbersome to prepare manually, +though PipMaker's associated utilities, such as +PipHelper and +the PipTools, can significantly reduce the burden.

    +However, since sequence annotations are increasingly becoming +available in standardized formats from on-line resources such as +the UCSC Table +Browser, Gmaj can now accept some of these formats as well. +These are referred to here as "generic" formats because they are +not restricted to a particular biological data type or Gmaj +display panel. +

    +The PipMaker-style formats are described below in the sections for +each panel, while the generic ones are discussed in a separate +section, Generic Annotation Formats. +

    @@ -52,10 +70,14 @@ can greatly facilitate the preparation of your files. at http://www.clipart.co.uk/ --> @@ -63,6 +85,7 @@ can greatly facilitate the preparation of your files.

    +

    Parameters File

    The annotation files are optional, but because in some alignments @@ -84,6 +107,7 @@ It contains detailed comments at the bottom explaining the syntax and meaning of the parameters.

    +

    Compression and Bundling

    Gmaj supports a "bundle" option, which allows you to collect and @@ -100,17 +124,20 @@ stand-alone mode. A few tips: mention the parameters file on the command line or in the applet tags; just specify the bundle. But if the parameters file is not in the bundle, specify both. +

  • Data files in the bundle should be referred to within the - parameters file using their plain filenames, without paths. - Any data files outside the bundle should be referred to - normally, using the rules described in + parameters file using their plain filenames, without paths, + and these must be unique. Any data files outside the bundle + should be referred to normally, using the rules described in sample.gmaj. -
  • Do not use filenames containing "/", - "\", or ":" in the bundle. Gmaj +

    +

  • Do not use filenames containing /, + \, or : in the bundle. Gmaj needs to remove the path that may have been added to each name by the zip or jar program, and since it doesn't know what platform that program was run on, it treats all of these characters as path separators. +

  • If you are not using a parameters file (i.e., you want to specify the alignment file directly, without any annotations or other data-related options), @@ -128,53 +155,62 @@ corresponding extension for the compression format to be recognized.

    +

    Coordinate Systems

    -If you supply any exons, -underlays, or other annotations for Gmaj to -display, these files must all use position coordinates that refer -to the same original sequences identified in the .maf -alignment file (ignoring any display offsets -specified in the parameters file). However, -even though the .maf coordinates are 0-based, the -annotation files use a 1-based coordinate system (i.e., the first -nucleotide in the sequence is called "1"). This is for consistency -with PipMaker, which uses virtually the same annotation formats. -Gmaj adjusts the .maf coordinates to convert -everything to a 1-based system for display. +If you supply any annotations for Gmaj to display, these files +must all use position coordinates that refer to the same original +sequences identified in the MAF alignment file +(ignoring any display offsets specified in the parameters file). However, even though the MAF coordinates +are 0-based, the PipMaker-style annotation files all use a +1-based, closed-interval coordinate system (i.e., the first +nucleotide in the sequence is called "1", and specified ranges +include both endpoints). This is for consistency with PipMaker, +so the same files can be used with both programs, and the same +tools can be used to prepare them. Coordinates for generic +annotations may be either 1-based or 0-based and closed or +half-open, depending on the format, but Gmaj always adjusts +them as needed (including the ones in the MAF file) to convert +everything to a 1-based, closed-interval system for display.

    +

    Alignments

    Gmaj is designed to display multiple alignments in -.maf -format. It is especially suited for sequence-symmetric alignments -from programs such as TBA, but can also display .maf files that have -a fixed reference sequence. (In the latter case it is a good idea -to set the refseq field in your parameters file, to avoid displaying the alignments with an -inappropriate reference sequence.) Gmaj displays only one +MAF format. +It is especially suited for sequence-symmetric alignments from +programs such as TBA, but can also display MAF files that have a fixed +reference sequence. (In the latter case it is a good idea to +set the refseq field in your parameters file, to prevent displaying the alignments with +an inappropriate reference sequence.) Gmaj displays only one alignment file at a time.

    +

    Exons

    Each of these files lists the locations of genes, exons, and -coding regions in a particular reference sequence. The -directionality of a gene (">", "<", -or "|"), its start and end positions, and name should -be on one line, followed by an optional line beginning with a -"+" character that indicates the first and last -nucleotides of the translated region (including the initiation -codon, Met, and the stop codon). These are followed by -lines specifying the start and end positions of each exon, which -must be listed in order of increasing address even if the gene -is on the reverse strand ("<"). By default Gmaj -will supply exon numbers, but you can override this by specifying -your own name or number for individual exons. Blank lines are -ignored, and you can put an optional title line at the top. -Thus, the file might begin as follows: +coding regions in a particular reference sequence. The exons +and UTRs are displayed as black and gray boxes in a separate +panel above the alignment plots. +

    +In the PipMaker-style exons format, the directionality of a gene +(>, <, or |), its +start and end positions, and name should be on one line, followed +by an optional line beginning with a + character that +indicates the first and last nucleotides of the translated region +(including the initiation codon, Met, and the stop codon). +These are followed by lines specifying the start and end positions +of each exon, which must be listed in order of increasing address +even if the gene is on the reverse strand (<). By +default Gmaj will supply exon numbers, but you can override this +by specifying your own name or number for individual exons. Blank +lines are ignored, and you can put an optional title line at the +top. Thus, the file might begin as follows: 

          My favorite genomic region
 
@@ -192,14 +228,19 @@ Thus, the file might begin as follows:

    +

    Repeats

    -Each of these files lists interspersed repeats and other features -in a particular reference sequence. The first line identifies -this as a simplified repeats file (as opposed to RepeatMasker -output); it is ignored by Gmaj, which only accepts this simplified -format. Each subsequent line specifies the start, end, direction, -and type of an individual feature. +Each of these files lists interspersed repeats (and possibly other +features such as CpG islands) in a particular reference sequence. +These are displayed in a separate panel just below the exons, +using the same shapes and shading as PipMaker if possible. +

    +In the PipMaker-style repeats format, the first line identifies +this as a simplified repeats file (as opposed to +RepeatMasker output, +which Gmaj does not yet support). Each subsequent line specifies +the start, end, direction, and type of an individual feature. 

          %:repeats
 
@@ -207,7 +248,7 @@ and type of an individual feature.
      1365 1405 Simple
      ... etc.
    -The allowed types are: +The allowed PipMaker types are: Alu, B1, B2, SINE, LINE1, LINE2, MIR, LTR, DNA, @@ -217,21 +258,24 @@ The allowed types are: require a direction (Right or Left).

    -

    Annotation Links

    +

    +

    Linkbars

    -Each of these files contains reference annotations, i.e., links -to web sites providing information about noteworthy regions in a -particular reference sequence, which are drawn as colored bars. -In applet mode Gmaj opens a new browser window to visit the -linked site when the user clicks on a bar. In stand-alone mode -Gmaj is not running within a web browser, so it just displays the -URL for the user to visit manually via cut-and-paste. +Each of these files contains reference annotations, i.e., +noteworthy regions in a particular reference sequence, which are +drawn in a separate panel as colored bars. Typically each bar +has an associated URL pointing to a web site with more information +about the region, but this is not required. In applet mode Gmaj +opens a new browser window to visit the linked site when the user +clicks on a bar; in stand-alone mode Gmaj is not running within +a web browser, so it just displays the URL for the user to visit +manually via copy-and-paste.

    -The format first defines various types of hyperlinks and -associates a color with each of them, then specifies the type, +The PipMaker-style format first defines various types of links +and associates a color with each of them, then specifies the type, position, description, and URL for each annotated region. 

    -     # annotations for part of the mouse MHC class II region
+     # linkbars for part of the mouse MHC class II region
 
      %define type
      %name PubMed
@@ -259,10 +303,10 @@ The name must be a single word, perhaps containing underline
 characters (e.g., Entry_in_GenBank), and the color
 must come from Gmaj's color list.
 
    
-The third stanza associates a PubMed annotation with positions
+The third stanza associates a PubMed link with positions
 1-2000 in this sequence.  The label should be kept fairly
 short, as it will be displayed on Gmaj's position indicator line
-when the user points at this annotation.  The summary is optional;
+when the user points at this linkbar.  The summary is optional;
 it is used only by PipMaker and will be ignored by Gmaj.  Also,
 while PipMaker allows several summary/URL pairs within a single
 annotation, Gmaj expects each field to occur at most once.  If
@@ -277,18 +321,28 @@ to separate it from the last word of the previous line, while
 a URL continuation does not.
 
    
 Also note that stanzas should be separated by blank lines, and
-lines beginning with a "#" character are comments
-that will be ignored.  The annotations can appear in the file in
+lines beginning with a # character are comments
+that will be ignored.  The linkbars can appear in the file in
 any order, and several can overlap at the same position with no
 problem, since Gmaj will display them in multiple rows if
-necessary.
+necessary.  In PipMaker this format is called "annotations with
+hyperlinks".
 
    
 
+
    
 
    Underlays
    
 
    
-Each of these files specifies color underlays (i.e., colored
-bands) to be painted on a particular pairwise pip.  The format
-supported by Gmaj looks like this:
+Each of these files specifies underlays (colored bands) to be
+painted on a particular pairwise pip and its corresponding
+dotplot.  The bands are specified as regions in the reference
+sequence and are normally drawn vertically; however for a dotplot,
+Gmaj will also look to see if you have specified an underlay file
+for the transposed situation where the reference and secondary
+sequences are swapped, and if so, will draw those underlays as
+horizontal bands in the secondary sequence.
+
    
+The PipMaker-style underlay format supported by Gmaj looks like
+this:
 
          # partial underlays for the BTK region
 
@@ -312,50 +366,54 @@ displayed on Gmaj's position indicator line when the user points
 the mouse at that band.  The parentheses must be present if the
 label is, and the label itself cannot contain any additional
 parentheses.  (The label is an extra feature not supported by
-PipMaker.)  A "+" or "-" character at
+PipMaker.)  A + or - character at
 the end of a location line will paint just the upper or lower
-half of the band, respectively.  This allows you to differentiate
-between the two strands, or to plot potentially overlapping
-features like gene predictions and database matches.
+half of the band on the pip (but is ignored for dotplots).  This
+allows you to differentiate between the two strands, or to plot
+potentially overlapping features like gene predictions and
+database matches.
 
    
 Note that if two bands overlap, the one that was specified last
 in the file appears "on top" and obscures the earlier one (except
 for the special Hatch color).
 Thus in this example, the green exons and red strongly conserved
 regions cover up parts of the long yellow band representing the
-gene.  As in the links file, lines beginning with a
-"#" character are comments that will be ignored.
+gene.  As in the links file, lines beginning with a #
+character are comments that will be ignored.
 
    
 
+
    
 
    Highlights
    
 
    
-These files are analogous to the underlay
+Highlight files are analogous to the underlay
 files, but each of these specifies colored regions for a
-particular sequence in the text view rather than for a pip.
-They use the same format as the underlay files, except that any
-"+" or "-" indicators will be ignored,
-and the Hatch color is not supported for highlights.
-Just as with underlays, labels can be included which will be
-displayed when the user points at the highlight, and highlights
-that are listed later in the file will cover up those that appear
-earlier.
-
    
+particular sequence in the text view, rather than for a plot.
 If you do not specify a highlight file for a particular sequence,
 Gmaj will automatically provide default highlights based on the
 exons file (if you provided one).  These will
-use different colors to indicate the forward vs. reverse strand.
-If the exons file specifies a gene's translated region, then the
-5´ and 3´ UTRs will be shaded using lighter colors.
-These default highlights make it easy to examine the putative
-start/stop codons and splice junctions, as well as providing a
-visual connection between the graphical and text views.  But if
-for some reason you do not want any text highlights, you can
-suppress them by specifying an empty highlight file.
+use one color for whole genes, overlaid with different colors to
+indicate exons on the forward vs. reverse strand.  If the exons
+file specifies a gene's translated region, then the 5´ and
+3´ UTRs will be shaded using lighter colors.  These default
+highlights make it easy to examine the putative start/stop codons
+and splice junctions, as well as providing a visual connection
+between the graphical and text views.  But if for some reason you
+do not want any text highlights, you can suppress them by
+specifying an empty highlight file.
+
    
+The PipMaker-style format for highlights is the same as for
+underlays, except that any + or -
+indicators will be ignored, and the Hatch color is
+not supported for highlights.  Just as with underlays, labels can
+be included which will be displayed when the user points at the
+highlight, and highlights that are listed later in the file will
+cover up those that appear earlier.
 
    
 
+
    
 
    Color List
    
 
    
-For Gmaj, the available colors are:
+For Gmaj's PipMaker-style annotations, the available colors are:
 
         Black   White        Clear
     Gray    LightGray    DarkGray
@@ -373,7 +431,7 @@ These names are case-sensitive (i.e., capitalization matters).
 Not all of these are supported by PipMaker.  Also, be aware that
 the appearance of the colors may vary between PipMaker and Gmaj,
 and from one printer or monitor to the next.
-
    
+
    
 Hatch
 
    
 In addition to the regular colors listed above, Gmaj supports a
@@ -385,13 +443,252 @@ appears "on top" and obscures the earlier one.  However,
 are always drawn after the other colors, and since the space
 between the diagonal lines is transparent, they allow the other
 colors to show through.  Currently Hatch is only
-supported for underlays, not for highlights or hyperlink
-annotations.
+supported for underlays, not for highlights or linkbars.
+
    
+
+
    
+
    Generic Annotation Formats
    
+
    
+The standardized generic formats currently supported by Gmaj
+include
+GFF (v1 & v2),
+GTF, and various flavors of
+BED (including the full BED12 format, a.k.a. "gene BED").
+For details on these formats, please see the specifications at
+the above links; this document will mainly discuss their use
+by Gmaj.
+
    
+These formats are all tab-separated, and despite their
+differences are similar enough that Gmaj can extract comparable
+fields and treat them more or less the same.  Note that Gmaj is
+not intended as a format validator: parsing is more lenient in
+some respects than the official format specifications, and Gmaj
+will ignore fields it has no use for.  Also, interpretation of
+these open-ended formats depends partly on what type of annotation
+is expected; e.g. if Gmaj is trying to read exons from a GFF v1
+file, it will assume that the group field is the gene name.  It
+will generally show warning messages to keep the user apprised
+of any such assumptions it is making (if these become too annoying
+they can be individually suppressed in the parameters file; see sample.gmaj for details).  Because one of the main
+reasons for supporting these formats is to enable the use of
+annotation files obtained from public sources, Gmaj tries not to
+balk at anomalies that are probably not the user's fault, and
+when practical will simply skip questionable items with a warning
+message.  Each type of message will generally be displayed only
+once, and not repeated for every item with the same problem.
+
    
+
    
+Filename Extensions
+
    
+In order to distinguish generic files from PipMaker-style ones
+and handle them appropriately, Gmaj requires that files in
+generic formats have names ending with any of certain extensions.
+The default list is .gff, .gtf,
+.bed, .ct, and .trk, but
+this can be customized (see sample.gmaj).
+
    
+
    
+Quoting
+
    
+Some of the generic formats require text values to be enclosed
+in double quotes (" ").  Even when not strictly
+required it is usually a good idea to do so, especially if the
+value contains spaces.  The official specifications generally
+don't say what to do if a value contains embedded quote
+characters, but Gmaj supports a rudimentary mechanism for
+escaping them with a backslash (\).  However it
+does not provide for escaping the backslash: quoted values
+should not end with \ (insert a space before the
+final quote if necessary).
+
    
+
    
+Coordinates
+
    
+The GFF and GTF formats use 1-based, closed-interval coordinates
+(i.e., sequence numbering starts with "1", and specified ranges
+include both endpoints), while BED uses a 0-based, half-open
+system (the first nucleotide of the sequence is numbered "0",
+and the ending position is not included in the region).  For all
+of these formats, positions are given relative to the beginning
+of the named sequence regardless of which strand the feature is
+on (unlike MAF), and start must be less than or
+equal to end.
+
    
+
    
+GFF Conventions
+
    
+BED format is relatively fixed in how its fields are used, but
+GFF and GTF are more variable and require additional conventions
+for most effective use with Gmaj.  In particular, the values of
+the "feature" field and the optional "attributes" affect how Gmaj
+will interpret and display an item.
+
    
+Values of the feature field that are recognized for special
+treatment include:
+
    
+
      
+
    • 	gene or values starting with gene_
+
    • 	exon or values starting with exon_
+
    • 	start_codon, str_codon,
+	stop_codon, stp_codon, or
+	cds
+
    • 	repeatmasker or any of the 
+	PipMaker repeat or CpG types
+
    
+
    
+Of these, only the PipMaker types are case-sensitive.
+
    
+For GFF v2 and GTF, the currently recognized attribute tags are:
+
    
+
      
+
    • 	gene or gene_id: the name of the
+	gene, e.g. for grouping exons (transcript_id is
+	ignored)
+
    • 	name: an optional name for this individual item,
+	e.g. for an exon label
+
    • 	sequence (when feature is
+	repeatmasker): the name/class/family of the
+	repeat, e.g. AluJb/SINE/Alu
+
    • 	color: a color
+	specification in UCSC format, e.g. 0,0,255
+
    • 	url or ucsc_id: the URL for
+	linkbars; $$ will be replaced with the value of
+	name
+
    
+
    
+These keywords are not case-sensitive, but they cannot have
+multiple values.
+
    
+
    
+Custom Tracks
+
    
+Along with the basic formats listed above, Gmaj also supports UCSC
+custom track headers.
+Track lines can specify certain settings for an entire
+track; currently color,
+itemRgb, offset,
+and url are supported.  They also allow several
+tracks (even in mixed formats) to be combined in a single file.
+Gmaj does not currently provide a way to use just one particular
+track from such a file (it will be treated as one big bag of
+annotations), but lines in unsupported formats such as
+WIG are gracefully skipped.
+Browser lines are also skipped; Gmaj's initial zoom position
+is controlled by command-line or applet parameters rather than by
+individual annotation files.
+
    
+
    
+Multiple Sequences
+
    
+Generic files can also contain annotations for several sequences,
+because unlike the PipMaker-style formats, they all have a
+"seqname" or "chrom" field that Gmaj can use to select the
+appropriate lines.  Ideally Gmaj expects this field to match
+the sequence name from the alignment file,
+but has two ways to deal with exceptions.  If there is only one
+seqname in the annotation file, then Gmaj will go ahead and use
+it, but will display a warning (unless the mismatch can be fixed
+by prepending the organism name, or the organism name plus
+chr, to the annotation seqname).  But if the file
+has annotations for several sequences and some don't match the
+alignment file, you need to tell Gmaj which is which by adding
+an alias in the parameters file (see
+sample.gmaj).
+
    
+
    
+Reusing Files
+
    
+One of the advantages of using generic formats is that files can
+be reused in multiple panels without reformatting, e.g. as both
+exons and underlays.  Normally linkbars, underlays, and text
+highlights are simply handled as arbitrary regions of a specified
+color, since they could represent any type of biological feature.
+However, you can ask Gmaj to interpret them as exons or repeats
+by adding a type hint in the parameters file
+(see sample.gmaj).  Note
+that currently this will also cause any specified colors in that file to be overridden with Gmaj's
+defaults.
+
    
+Combining several biological types of annotations (e.g. exons
+and repeats) in one file is possible, but not recommended.  Gmaj
+will try to skip lines that are not appropriate for the type it
+is seeking, but it may draw more than you want.
+
    
+
    
+Coding Sequence
+
    
+Currently Gmaj has no special support for multiple transcripts.
+When inferring UTRs, all of the CDS-related items for a single
+gene name are combined, and the interval from the lowest
+coordinate to the highest is used as the CDS.  Also, some of the
+formats' rules specify whether or not the initiation and stop
+codons should be included in the CDS, but Gmaj does not make
+adjustments to compensate for that; instead it simply includes
+all of the given endpoints in the CDS.
+
+
    
+
    
+Colors
+
    
+Colors can be specified for individual annotation lines via the
+itemRgb field (for BED) or a color
+attribute (for GFF v2 or GTF).  However, for custom tracks, these are governed by the track line's
+itemRgb attribute, which defaults to off per the
+UCSC specification.  Thus if you have track lines and want to
+use the per-item colors, you need to include
+itemRgb=On in the track attributes.
+
    
+Track lines can also have a color attribute for
+the entire track, which will be used if itemRgb is
+off, or if an individual item does not have its own color.
+However in a rare break from the UCSC specification, Gmaj does
+not use black as the default if the track color is unspecified
+(black underlays and highlights just don't work with black plots
+and text).  Instead it uses its own default colors, which for
+genes/exons are the same as the colors for default highlights, or light gray for other annotations.
+Note that these defaults will also override your colors when
+type hints are used.
+
    
+All of the above-mentioned color values are specified in UCSC
+format, which consists of three comma-separated RGB values from
+0-255 (e.g. 0,0,255).
+
    
+
    
+Sorting
+
    
+The order of the lines is not supposed to matter in these generic
+formats, but for most of the Gmaj panels it does matter:  exons
+need to be grouped by gene and ordered by position so UTRs can be
+inferred and exon numbers assigned, early underlays are covered
+up by later ones, etc.  Gmaj solves this problem by sorting the
+data before it is displayed.  Exons are sorted first by gene name
+in ascending order, and then within each gene by start position
+(ascending) and lastly in case of a tie, by end position
+(descending).  All other annotation types are sorted first by
+length in descending order, and then in case of a tie by start
+position (ascending).  This usually produces a reasonable display,
+but if you need direct control of the order, you can use the
+PipMaker-style formats instead.
 
    
 
 
    
 
    
-Cathy Riemer, June 2006
+Cathy Riemer, July 2007
 
 
    
 
diff --git a/static/gmaj/docs/gmaj_install.html b/static/gmaj/docs/gmaj_install.html
index 10b2a4bf9e5..c6c0e870e6c 100644
--- a/static/gmaj/docs/gmaj_install.html
+++ b/static/gmaj/docs/gmaj_install.html
@@ -71,11 +71,12 @@ page apply only to applet setup.
 
 
    Data Files
    
 
    
-Gmaj can display several kinds of data, including alignments,
-exons, repeats, annotation links, color underlays, and text
-highlights, with a meta-data parameters file to tie them all
-together.  For detailed descriptions of these files and their
-format requirements, please see Input Files for Gmaj.
 
    
 When setting up Gmaj as an applet, the data files must be
@@ -158,6 +159,6 @@ file URLs, button label, etc.  A few things to note:
 
 
    
 
    
-Cathy Riemer, June 2006
+Cathy Riemer, July 2007
 
 
diff --git a/static/gmaj/docs/gmaj_news.html b/static/gmaj/docs/gmaj_news.html
index 9f76febfd3e..b6ac880562f 100644
--- a/static/gmaj/docs/gmaj_news.html
+++ b/static/gmaj/docs/gmaj_news.html
@@ -12,13 +12,121 @@
 
    What's New in Gmaj
    
 
    
 
    
+
    2007-Jul-26
    
+
    	
      
+	
    • 	Gmaj can now display dotplots in addition to the main multi-pip views,
+		with color underlays for both sequences.
+		
        
+		
      • 	Dotplots are opened by clicking on buttons in the pip headers.
+		
      • 	Each dotplot opens in a separate window, similar to the multi-pip
+			view except it has pip, dotplot, and text panels for two sequences
+			only.
+		
      • 	Dotplot windows share the same reference sequence and mark with
+			their parent multi-pip window but have independent zoom, and close
+			automatically when the parent does.
+		
      • 	There is only one mark for each reference sequence, so the circle
+			will not appear in dotplots having a different secondary sequence
+			than the mark.
+		
      
+	
    • 	Gmaj can now read annotation data in
+		GFF (v1 & v2),
+		GTF, and
+		BED formats in addition to its previous PipMaker-style formats.
+		
        
+		
      • 	UCSC
+			custom track headers are supported, with multiple tracks and
+			sequence names allowed in a single file.
+		
      • 	There is currently no way to use just one particular track from a
+			file, but lines in
+			WIG or other unrecognized formats are skipped.
+		
      • 	Files in these generic formats can be reused in multiple panels
+			(e.g. as both exons and underlays).
+		
      • 	A new tabext field and file specification modifiers
+			(seqname alias and type hint) in the parameters file facilitate
+			interpretation of these formats.
+		
      • 	Colors can be specified using UCSC-style RGB triplets (either
+			per-line or per-track), or Gmaj provides defaults.
+		
      • 	Currently there is no special support for multiple transcripts;
+			when inferring UTRs, the largest bounding range of given CDS data
+			is used.
+		
      
+	
    • 	A new control in the menu bar allows the user to limit the displayed
+		alignments by their average % identity.
+		
        
+		
      • 	Keyboard shortcuts make it easy to move the threshold up and down.
+		
      • 	The value for the current plot block is displayed with the mark
+			information when applicable.
+		
      
+	
    • 	If the alignment file contains per-nucleotide reconstruction scores
+		for an inferred ancestral sequence, they can be displayed as a pair of
+		bar graphs, binned according to the current zoom region and panel size.
+		
        
+		
      • 	The scores are transformed via simple linear scaling, and should
+			not be interpreted as probabilities.
+		
      • 	A new reconseq field in the parameters file
+			identifies the organism for the scores.
+		
      
+	
    • 	Miscellaneous:
+		
        
+		
      • 	"Unsupported MAF version" is now a warning instead of a fatal
+			error.
+		
      • 	A new nowarn field in the parameters file suppresses
+			certain warnings/errors using a keyword shown in the message.
+		
      • 	When opening a new window, the current zoom is translated to a
+			roughly equivalent one in the new sequence(s).
+		
      • 	Sequence choices in the Show dialog affect text rows and dotplots
+			in addition to pips.
+		
      • 	The default highlights built from exons now include the genes
+			(light yellow).
+		
      • 	The divider between the position indicator and the zoom indicator
+			is draggable.
+		
      • 	Plot segments are drawn thicker in Large Fonts mode.
+		
      • 	Plots that are completely empty have a gray background.
+		
      • 	The Set Zoom dialog accepts a blank box to mean "leave unchanged".
+		
      • 	Tabbing is easier in input dialogs: labels are skipped unless the
+			mouse is pointing at them.
+		
      • 	Note that "=" is now required for settings in the
+			parameters file (except seq N: lines), and
+			lines with empty values (e.g. unused template items) are allowed
+			and skipped.
+		
      
+
+	
    • 	Various minor bug fixes, and improvements in appearance, behavior,
+		messages, efficiency, and robustness.
+	
    • 	Updated documentation.
+		
        
+		
      • 	Terminology: the optional colored clickable bars located above
+			the exons panel were formerly called "annotations", "annotation
+			links", or "hyperlink annotations", but are now referred to as
+			"linkbars" so that "annotation" can be used in the general sense.
+		
      
+	
    
+
    
 
    2006-Jun-17
    
 
    	
      
 	
    • 	Gmaj can now be deployed as a web-based applet, as an alternative to
 		the regular stand-alone mode.
 		 Demo
 		
        
-		
      •  New parameters bundle, initzoom, and
+		
      • 	New parameters bundle, initzoom, and
 			urlpause facilitate applet use, but also work in
 			stand-alone mode.
 		
      • 	Clicking on hyperlinked annotations (colored bars) visits the
@@ -27,14 +135,13 @@
 			stand-alone mode, displays the file location).
 		
      • 	The "File - Export" feature does not work yet for applets.
 		
      
-	
    • 	Better conformance with the official UCSC specs for .maf
-		format.
+	
    • 	Better conformance with the official UCSC specs for MAF format.
 	
    • 	A new refseq field in the parameters file can be used
 		to prevent selection of an inappropriate reference sequence when the
 		alignments are not sequence-symmetric (e.g. from multiz).
-	
    • 	Maximum zoom bounds are now the stated sequence length from the
-		.maf file (not just the extent of the blocks), but the
-		default initial view zooms to the aligned portion.
+	
    • 	Maximum zoom bounds are now the stated sequence length from the MAF
+		file (not just the extent of the blocks), but the default initial
+		view zooms to the aligned portion.
 	
    • 	Search rules for relative filenames have been simplified, and Windows
 		names starting with "\" are now handled better.
 	
    • 	The panel for hyperlinked annotations is now labeled, and it displays
@@ -183,8 +290,8 @@
 		they are the same.  The old underlays.N parameters are
 		still supported as well, and override these new ones.
 	
    • 	The seqfile parameter has been renamed to
-		seqname, in order to reflect .maf semantics
-		(but seqfile is still supported for backward compatibility).
+		seqname, in order to reflect MAF semantics (but
+		seqfile is still supported for backward compatibility).
 	
    • 	Sequence label widths are now computed dynamically, based on the longest
 		name and the current font.
 	
    • 	When the font size is changed, pip heights are also adjusted.
@@ -204,7 +311,7 @@
 	
    • 	The jar manifest and About information have been updated.
 	
    • 	Support for alignment files in .bb format (from the old
 		blockbuilder program) has been discontinued.  The only alignment
-		format currently supported is .maf.
+		format currently supported is MAF.
 	
    • 	Due to a new mechanism for registering keyboard shortcuts, Gmaj now
 		requires Java 1.3 or higher.
 	
    • 	This version should still be considered beta quality; please
@@ -214,8 +321,8 @@
 
      
 
      2005-May-16
    • -
      -
    • All files must consist solely of plain text ASCII characters. -(For example, no Word documents.) -
    • All coordinates for annotations are 1-based. +
        +
      • All files must consist solely of plain text ASCII + characters.  (For example, no Word documents.) +

        +

      • All coordinates for PipMaker-style + annotations are 1-based, closed interval.  Those + for generic annotations may be either 1-based or 0-based + and closed or half-open, depending on the format.