RALEE -- RNA alignment editor in Emacs
--------------------------------------

Version 0.2 -- 2004-06-08


What have we here then?
-----------------------

RALEE is a major mode for the emacs editor that adds functionality to
aid the viewing and editing of alignments of structured RNAs.  It was
written primarily by and for curators of the Rfam database
(http://www.sanger.ac.uk/Software/Rfam/), who are always wanting to do
things that available multiple sequence alignment editors don't allow!


Requirements
------------

   - ralee-mode.tar.gz
	- http://www.sanger.ac.uk/Users/sgj/code/ralee-mode.tar.gz
   - Emacs 21
	- http://www.gnu.org/software/emacs/emacs.html
	- tested with GNU Emacs 21.2 on OSF1/alpha, GNU/Linux and
	  Windows XP
	- minimally tested with XEmacs 21.5 on OSF1/alpha
   - some Stockholm format RNA alignments that you need to view/edit
        - http://www.sanger.ac.uk/Software/Rfam/
	- http://www.cgr.ki.se/cgb/groups/sonnhammer/Stockholm.html


Installation
------------

1. Copy the .el files into a directory of your choice; somewhere in
   your home area if you are the only person who will use it, or
   somewhere more central if other people may want to (and if you have
   root access).

   (The following example uses the location ~/site-lisp/ which
   may or may not be a great place!)

2. Add this location to your emacs load-path by adding the following
   line to your .emacs file:

   -------
   (add-to-list 'load-path "~/site-lisp")
   -------

3. Add some stuff to .emacs to auto-load the RALEE mode on demand:

   -------
   ;; ralee mode is good for RNA alignment editing
   (autoload 'ralee-mode "ralee-mode" "Yay! RNA things" t)
   (setq auto-mode-alist (cons '("\\.stk$" . ralee-mode) auto-mode-alist))
   -------

   And you're good to go!

4. Optional useful .emacs additions:

   -------
   ;; Show current line and column number
   (column-number-mode t)
   (line-number-mode t)

   ;; Show parenthesis pairs
   (show-paren-mode)

   ;; Always end a file with a newline
   (setq require-final-newline t)
   -------


Running RALEE
-------------

1. Format your input alignment to be unblocked stockholm format.  You
   could use the sreformat tool from Sean Eddy's HMMER package
   (http://hmmer.wustl.edu):

   $ sreformat --pfam stockholm [alignfile] > [infile]

   Stockholm format includes secondary structure markup in a line with
   the tag "#=GC SS_cons".  The format of the line uses parentheses to
   show nested base pairs so:

	0123456789012345678901234
	.<<<<<...>>.<<...>>..>>>.
	
   Column 1 pairs with 23
          2 with 22
	  3 with 21
	  4 with 10
	  5 with 9
	 12 with 18
	 13 with 17

   Note that the column numbers are not part of the Stockholm format
   -- they are just shown here to aid explanation.  You will also
   note that this doesn't allow markup of pseudoknot interactions --
   there are ways of showing these, but RALEE doesn't yet support
   them.


2. Open the alignment in emacs:

   $ emacs [infile]

   If your infile name ends with .stk then you should see "(Ralee)" in
   the bottom bar of emacs.  If it doesn't, you can load ralee-mode
   with:

   M-x ralee-mode


3. Get editing!


Commands and shortcuts
----------------------

In addition to the standard emacs editing commands (C-x C-s to save
etc), RALEE includes some commands to edit and markup alignments of
structured RNAs.  M-x means "hold down Alt and press x" or "press Esc
then x" if your setup is vaguely normal.  C-c means "hold down Ctrl
and press c".  The full command is on the left with the shortcut on
the right.  Hopefully most are pretty self-explanatory -- try 'em and
see!


    Movement commands
    -----------------

    M-x jump-right				C-f
    M-x jump-left				C-b
    M-x jump-up					C-p
    M-x jump-down				C-n
    M-x jump-to-pair				C-c C-p
    M-x jump-to-pair-in-other-window		C-c C-[

    Editing commands
    ----------------

    M-x insert-gap				.
    M-x delete-gap				C-d
    M-x insert-gap-column			C-c C-i
    M-x delete-gap-column			C-c C-d
    M-x delete-all-gap-columns
    M-x unblock-alignment
    M-x make-flush-alignment

    (M-x unblock-alignment takes a blocked Stockholm alignment file
    and unblocks it, saving the original file with a .bak extension.
    This function is not well tested -- beware that your data may get
    corrupted.)

    Painting commands
    -----------------

    M-x paint-buffer-by-ss			C-c C-b
    M-x paint-buffer-by-cons			C-c C-c
    M-x paint-buffer-by-base			C-c C-v
    M-x paint-buffer-by-current-ss-line		C-c C-n

    Helper commands
    ---------------

    M-x fold-sequence				C-c C-f
    M-x fold-all-sequences
    M-x show-structure-ps

    (show-structure-ps and fold-sequence assume that you have
    ViennaRNA (http://www.tbi.univie.ac.at/~ivo/RNA/) installed, and
    that RNAfold (along with gv) is on your path.  Both should be more
    configurable at some point!)


Bugs
----

C-d (and C-c C-d) will only let you delete gaps, but backspace and
delete will merrily let you delete sequence from your alignment.  Some
kind of protection from this may be along sometime.  Very little of
the code has been rigorously tested with alignments formats other than
an unblocked version of the Rfam database
(http://www.sanger.ac.uk/Software/Rfam/) format.  You are unlikely to
get informative error messages if you try and open other alignment
formats.  Full Stockholm compatability is by no means guarenteed.


Contact
-------

We're using RALEE in anger to improve alignments in the Rfam database
(http://www.sanger.ac.uk/Software/Rfam/).  But it is *very*
preliminary code.  I'd appreciate a mail if you find it useful, and am
actively interested in improving and developing this, so any
bugs/requests/abuse should be directed at:

sgj@sanger.ac.uk


Legal things
------------

RALEE is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your
option) any later version.

RALEE is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License
along with RALEE; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.



History
-------

0.2     2004-06-08

	- Added menus for both GNU Emacs and XEmacs
	- A couple of minimal examples included
	- Fold sequences to add "#=GR SS" lines, and allow colouring
	  of buffer based on alternative structures
	- paint-buffer-by-cons and paint-buffer-by-base do different
	  things

0.1	2004-05-31 

	First effort at something that will be useful, at least for
	Rfam internal use.  Colour bases in an alignment based on the
	base pairing.



-------------------------------
2004-06-08  Sam Griffiths-Jones
