/programs/Editor_AE2 24-APR-1992 ------------------------------------------------------------------ THE AE2 ALIGNMENT EDITOR DEVELOPED BY T. J. MACKE (IN CONJUNCTION WITH THE RDP) ------------------------------------------------------------------ Please report program malfunctions to macke@scripps.edu AE2 is an alignment editor originally developed by T. J. Macke at the University of Illinois at Urbana/Champaign. It was designed around character addressable terminals running under the Unix operating system. AE2 was designed primarily for RNA/DNA sequence alignments, although it can be used successfully with proteins. The editor is written in C, and the source code is available via anonymous ftp at . At present AE2 will run only on SUN Workstations. An alignment is a rectangular array of symbols in which each row is (1:1) colinear representation of a molecular sequence. The sequences in an alignment are homologous; and the columns in an alignment are used to represent homologous positions in the sequence set. In that homologous sequences tend to have different overall lengths, it is necessary to insert spacings (alignment gaps) in the alignment to maintain homology of the columns. Although the ordering of the columns is fixed, the order of the sequences (rows) is arbitrary. Closely related sequence are usually grouped together, but other orderings can be used. An alignment editor is an interactive program used to create, modify, display and analyze alignments. It works by providing one or more rectangular viewports into an alignment. Keystrokes or other commands move these viewports, insert gap characters into sequences, rearrange sequence order, etc. An alignment editor also displays information about the current position in the alignment (sequence, residue number) as well as information describing editor modes, and so on. AE2 partitions the terminal screen into two areas. The top six lines are used as the status area. Alignment position, reference sequence and editor modes are displayed there, as well as line commands and error messages. The remainder of the screen is a work area, used to display the alignment and/or other information in one of several styles selected by the user. The status area is always displayed no matter what the mode of the work area. Function keys which generate escape sequences are used to input commands. One function key invokes a command line prompt, used for the more complex commands. The initial alignment, displayed in the work area, comprises one or more sequences (rows of symbols). For each sequence its name abbreviation occupies a fixed width field on the left side of the screen. The sequence display itself begins after a blank column and extends to the right margin. However, each sequence is preceded by a number that indicates the position of the left-most visible residue in that sequence. The sequence portion of the display may be split vertically into two equal sized areas (separated by a blank column), each containing the sequence alignment; when the editor is in this "split screen" mode, the two areas can be manipulated independently or in some cases, involving the RNA secondary structural tracking mode, move in concert, to keep both strands of a double helix visible. In the editor each sequence is characterized by certain attributes: whether it is DNA, RNA or protein; the chemical sequence direction; the strand "sense" (for nucleic acid). In addition operation attributes are assigned, for example: whether the sequence participates in a given operation; whether it is visible; whether it is to be written to a file; etc. The AE2 screen can be split vertically to show the sequences in one half, their attributes in the other. The attributes can be manipulated to conform with ensuing operations. The screen splitting is done so that the current residue position in the sequence remains visible; i.e., the sequence attribute display may appear as either the left or the right hand display depending on the current alignment position. A third display mode option involves opening a "text" window on the bottom third of the screen. This is used for various purposes, including displaying sequence comments or showing the results of a computation applied to the align- ment. Movement in the text window does not affect the resi- due display and vice versa. Several other specialized displays modes are possible. One provides an expanded display of the non-residue information associated with a sequence. This is a form-style screen that includes areas for the full sequence name, literature refer- ences, important dates etc. Another is a single sequence entry mode that uses the entire residue display for the sequence being entered and includes cues such as residue numbers and spaces after every 10th residue. The final display mode is used to "check enter" a sequence. The selected sequence is displayed with a new initially empty sequence line below it. The user reenters the sequence and the editor stops entry and requires a resolution whenever a conflict occurs between the existing sequence and that being entered. AE2 commands are entered via function keys. Since AE2 has too many commands to assign each one to a function key, two strategies are used. In the first, one function key is reserved as a "prefix" key. This key has no meaning by itself but is used prior to a second function key to amplify or change its meaning. In the second, another function key is used to create a command line that accepts commands typed from the keyboard. The ordinary keys (letters, digits and other characters) are used to insert those characters into a sequence (under restricted conditions). BackSpace and Delete keys are used to remove characters from a sequence (under restricted conditions) while the other control characters are not used; typing them gives in an error message, after which they are ignored. ------------------------------------------------------------------------- GETTING STARTED ------------------------------------------------------------------------- Install AE2 according to the installation instructions given below. The function keys are described in the AE2keys.txt file (included in the tar file). The tar distribution file also includes a "help" file in PostScript, which documents each of AE2's line commands. Type 'ae2 file_name.aln' to activate the program. SCREEN LAYOUT The general initial appearance of the screen has been described above. Status panel (topmost 3 lines): KyBd: Allows mapping of keys (for sequence insertion or modification) reading mapping file named "grtt" Mask: Invokes a binary mask that defines columns used in various operations. Ref : Sequence name of designated reference sequence AND base number in reference sequence. Scrn: Normal or transformed alignment. IS : Insertion status (insert vs overstrike; move vs stay after operation: arrow- left vs rt movement, editing restrictions applied to sequence under cursor Col : Column number in alignment Vis : Display all sequences vs display only those marked "v" Gr/HM : Groups operations On vs Off; helix mirroring On vs Off. TmpGrp: Specifies whether next operation done on all seq (All) or all-but-current (All-But-Cur) or named groups if any (None) Line 4: Reminds user of most commonly used command keys Line 5: Reports command errors and command results Line 6: Where line commands are typed (invoked by R3 key) Sequence panel: The "work area" described above initially comprises the alignment with sequences preceded by sequence short-names and the 5' numbering. The screen can be split in the various ways discussed above. The bottom third of the screen becomes a window under various conditions (see "function keys" description). It can display the results of particular line commands, comments associated with the current sequence, and command aliases (which can be edited). DATA FORMAT, LOADING DATA AE2 input is an ASCII file with all information needed by the editor, as well as most of the annotations offered by GenBank and EMBL. It can be created by the program convp (also offered by RDP), which interconverts GenBank, EMBL, SwissProt, ALMA and AE2 formats; alternatively, it can be created with a text editor. In its simplest form an ae2 file requires an initial line comprising only '#-' and individual sequence entries on following lines, see example below. Each sequence must be broken into lines of residues (uninterrupted by spaces) no longer than 250 characters. Each line in a given sequence must be preceded by a name identifier (maximum 19 characters, no spaces) followed by one or more spaces. For example: #- seq1 aaaaaaaaaaaaaaaaaaaaaa seq1 aaaaaaaaaaaaaaaaaaaaaa seq2 gggggggggggggggggggggg seq2 ggggggggggggggggggggggg seq3 cccccccccccccccccccccc seq3 cccccccccccccccccccccccc To load the data from within the editor use the command 'read ./file_name'. There is no intrinsic limit on the number of sequences or their length. BASIC EDITING When sequences appear in the sequence panel, the cursor is located on the first column of the top sequence; it can then be moved by the arrow keys. The R1 (gold) key amplifies cursor movements (as well as other basic editing operations), and will accept a numeric argument. A number given on the command line places the cursor on the residue in that sequence corresponding to that number. When the number is followed by an "r" the cursor is placed on the residue (in that sequence) that corresponds to that number in the reference sequence; whereas when followed by a "c", the cursor is placed on the residue (in that sequence) corresponding to the column in the alignment with that number. Residues can be added and deleted or slid in either direction (depending on the "lock status" of the sequence). Editing can affect a single sequence, all sequences, all-but-the-cursor sequences or groups of sequences. Groups can be readily defined and saved for later use. Highlighting by reverse video is available. Find functions will search either the short names or sequence for a given pattern. Many function keys on the SUN-4 keyboard (R1-R15 and F1-F9) have been assigned specific actions, see AE2keys.txt for details. LINE COMMANDS More complex editing operations (those requiring parameters, options etc) are invoked by commands on the command line. These are documented in the "help" file (commands.hlp), included in the tar distribution file. Examples are: Check new sequences for inconsistencies, Generate masks, Generate consensus sequences, Generate distance/similarity matrix, Define groups and read group files, Display helices (projected from a given sequence) in reverse video, Remap keys for easy sequence entry while reading gels, Generate simplified (twisted) alignments suited for UNIX grep, Activate helix mirroring, Print alignment in various formats, Save screen snapshots as PostScript file, Find and display unique residues. The user leaves AE2 by typing "exit" on the command line, which will save the alignment (in the original file) if it has been changed; the command quit will terminate the session with no changes saved (after verification). ------------------------------------------------------------------------------ INSTALLATION ------------------------------------------------------------------------------ To install ae2: 0. You will need at least 5MB to install ae2. After installation you can recover about 4MB of this. 1. get the ae2.tar.Z distribution file from the server. 2. uncompress and untar this file: zcat ae2.tar.Z | tar xvof - 3. This will create the ae2 distribution directory, ae2. edit the make file to configure for your system: cd ae2 vi Makefile # define AE2BIN and AE2LIB to hold the binary and # libraries created by make. Remember what directory # you chose for AE2LIB, for reference below 4. make ae2: make 5. install ae2: make install 6. Choose a place to put the Man pages: Do not place them in the standard man directories, you will overwrite other man pages. A good place would be in the AE2LIB directory: cp -r man /usr/local/lib # or whatever directory you # chose in step 3 7. At this point you can recover 4MB of space by removing the distribution file (ae2.tar.Z) and the entire ae2 directory: cd .. rm ae2.tar.Z rm -r ae2 8. Users should edit the .cshrc file to define the symbol AE2LIB, and to make an alias for the man pages: setenv AE2LIB /usr/local/lib # or whatever directory you # chose in step 3. alias ae2man "man -M $AE2LIB/man" # to access the man page for # "helix" (for instance), # type "ae2man helix"