[mussa.git] / doc / manual / mussagl_manual.rst

==============
Mussagl Manual
==============
------------------
By Brandon W. King
------------------

Last updated: May 18th, 2006

Updated to Mussagl build: 141 (Update to 200 in progress)


.. contents::

Introduction
============


What is Mussagl?
----------------


Short History of Mussa
----------------------


Mussa Python/PMW Prototype
~~~~~~~~~~~~~~~~~~~~~~~~~~


Mussa C++/FLTK
~~~~~~~~~~~~~~


Mussagl C++/Qt/OpenGL
~~~~~~~~~~~~~~~~~~~~~


Getting Mussagl
===============

License
-------

Mussagl has been released open source under the `GPL v2
license`__. 

__ GPL_

Platforms
---------

You have the option of building from source or downloading prebuilt
binaries. Most people will want the prebuilt versions.

Supported Platforms:
 
 * Mac OS X (binary or source)
 * Windows XP (binary or source)
 * Linux (source)

Download
--------

Mussagl in binary form for OS X and Windows and/or source can be
downloaded from http://mussa.caltech.edu/.

Install
-------

Mac OS X
~~~~~~~~
Once you have downloaded the .dmg file, dubble click on it and follow
the install instructions. 

FIXME: Mention how to launch the program.


Windows XP
~~~~~~~~~~
Once you have downloaded the Mussagl installer, double click on the
installer and follow the install instructions.

To start mussagl, launch the program from Start > Programs > Mussagl >
Mussgl.


Linux
~~~~~
Currently we do not have a binary installer for Linux. You will have
to build from source. See the 'build from source' section below.


Build from Source
~~~~~~~~~~~~~~~~~

Instructions for building from source can be found `build page
<http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild>`_ on the
`Mussa wiki`__.

__ wiki_


Using Mussagl
=============


Launch Mussagl
--------------
Launch Mussagl... It should look similar to the screen shot below.

.. image:: images/opened.png
   :alt: Launch Mussa
   :align: center



Create/Load Analysis
----------------------

Currently there are three ways to load a mussa experiment.

 1. `Create a new analysis`_
 2. `Load a mussa parameter file`_ (.mupa)
 3. `Load an analysis`_

.. _createnew:

Create a new analysis
~~~~~~~~~~~~~~~~~~~~~

To create a new analysis select 'Define analysis' from the 'File'
menu. You should see a dialog box similar to the one below. For this
demo we will use the example sequences that come with Mussagl.

.. image:: images/define_analysis.png
   :alt: Define Analysis
   :align: center

Instructions:

 1. **Give the experiement a name**, for this demo, we'll use
    'demo_w30_t20'. Mussa will create a folder with this name to store
    the analysis files in once it has been run.

 2. Choose a `window size`_. For this demo **choose 30**.

 3. Choose a threshold_... for this demo **choose 20**. See the
    Threshold_ section for more detailed information.

 4. Choose the number of sequences_ you would like. For this demo
    **choose 3**.

.. image:: images/define_analysis_step1a.png
   :alt: Steps 1-4
   :align: center

Now click on the 'Browse' button next to the sequence input box and
then select /examples/seq/human_mck_pro.fa file. Do the same in the
next two sequence input boxes selecting mouse_mck_pro.fa and
rabbit_mck_pro.fa as shown below. Note that you can create annotation
files using the mussa `Annotation File Format` to add annotations to
your sequence.

.. image:: images/define_analysis_step2.png
   :alt: Choose sequences
   :align: center

Click the **create** button and in a few moments you should see
something similar to the following screen shot.

.. image:: images/demo.png
   :alt: Mussagl Demo
   :align: center

This analysis is now saved in a directory called **demo_w30_t20** in
the current working directory. If you close and reopen Mussagl, you
can reload the saved analysis. See `Load an analysis`_ section below
for details.


Load a mussa parameter file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you prefer, you can define your Mussa analysis using the Mussa
parameter file. See the `Parameter File Format`_ section for details
on creating a .mupa file.

Once you have a .mupa file created, load Mussgl and select the **File >
Load Mussa Parameters** menu option. Select the .mupa file and click
open. 

.. image:: images/load_mupa_menu.png
   :alt: Load Mussa Parameters
   :align: center

If you would like to see an example, you can load the
**mck3test.mupa** file in the examples directory that comes with
Mussagl.

.. image:: images/load_mupa_dialog.png
   :alt: Load Mussa Parameters Dialog
   :align: center


Load an analysis
~~~~~~~~~~~~~~~~

To load a previously run analysis open Mussagl and select the **File >
Load Analysis** menu option. Select an analysis **directory** and
click open.

.. image:: images/load_analysis_menu.png
   :alt: Load Analysis Menu
   :align: center


Main Window
-----------

Overview
~~~~~~~~
.. Screenshot with numbers showing features.

.. image:: images/window_overview.png
   :alt: Mussa Window
   :align: center

Legend:

 1. `DNA Sequence (Black bars)`_
 
 2. Annotation_

 3. Motif_

 4. `Conservation tracks`_

 5. `Motif Toggle`_

 6. `Zoom Factor`_ (Base pairs per pixel)

 7. `Dynamic Threshold`_

 8. `Sequence Information Bar`_

 9. `Sequence Scroll Bar`_


DNA Sequence (black bars)
~~~~~~~~~~~~~~~~~~~~~~~~~

.. image:: images/sequence_bar.png
   :alt: Sequence Bar
   :align: center

Each of the black bars represents one of the loaded sequences, in this
case the sequence around the gene 'MCK' in human, mouse, and rabit.

FIXME: Should I mention the repeats here?


Annotation
~~~~~~~~~~

.. figure:: images/annotation.png
   :alt: Annotation
   :align: center
   
   Annotation shown in green on sequence bar.


Annotations can be included on any of the sequences using the `Load a
mussa parameter file`_ method of loading your sequences. You can
define annotations by location or using an exact subsequence and you
may also choose any color for display of the annoation; see the
`Annotation File Format`_ section for details.

Note: Currently there is no way to add annotations using the GUI (only
via the .mupa file). We plan to add this feature in the future, but it
likely will not make it into the first release.


Motif
~~~~~

.. figure:: images/motif.png
   :alt: Motif
   :align: center

   Motif shown in light blue on sequence bar.

The only real difference between an annotation and motif in mussagl is
that you can define motifs from within the GUI. See the `Motifs`_
section for more information.


Conservation tracks
~~~~~~~~~~~~~~~~~~~

.. figure:: images/conservation_tracks.png
   :alt: Conservation Tracks
   :align: center
   
   Conservations tracks shown as red and blue lines between sequence
   bars.

The **red lines** between the sequence bars represent conservation
between the sequences and **blue lines** represent **reverse
complement** conservation. The amount of sequence conservation shown
will depend on the relatedness of your sequences and the `dynamic
threshold` you are using. Sequences with lots of repeats will cause
major slow downs in calculating the matches.


Motif Toggle
~~~~~~~~~~~~

.. image:: images/motif_toggle.png
   :alt: Motif Toggle
   :align: center

Toggles motifs on and off. This will not turn on and off annotations.

Note: As of the current build (#200), this feature hasn't been
implemented.


Zoom Factor
~~~~~~~~~~~

.. image:: images/zoom_factor.png
   :alt: Zoom Factor
   :align: center

The zoom factor represents the number of base pairs represented per
pixel. When you zoom in far enough the sequence will switch from
seeing a black bar, representing the sequence, to the actual sequence
(well, ASCII representation of sequence).


Dynamic Threshold
~~~~~~~~~~~~~~~~~

.. image:: images/dynamic_threshold.png
   :alt: Dynamic Threshold
   :align: center

You can dynamically change the threshold for how strong of match you
consider the conservation to be with one of two options:

 1. Number of base pair matchs out of window size.
 
 2. Percent base pair conservation.

See the Threshold_ section for more infromation.


Sequence Information Bar
~~~~~~~~~~~~~~~~~~~~~~~~

.. image:: images/seq_info_bar.png
   :alt: Sequence Information Bar
   :align: center

The sequence infomation bars can be found to the left and right sides
of mussagl. Next to each sequence you will find the following
information:

 1. Species (If it has been defined)
 2. Total Size of Sequence
 3. Current base pair position


Sequence Scroll Bar
~~~~~~~~~~~~~~~~~~~

.. image:: images/scroll_bar.png
   :alt: Sequence Scroll Bar
   :align: center

The scroll bar allows you to scroll through the sequence which is
useful when you have zoomed in using the `zoom factor`_.


Annotations / Motifs
--------------------

Annotations
~~~~~~~~~~~

Currently annotations can be added to a sequence using the mussa
`annotation file format`_ and can be loaded by selecting the
annotation file when defining a new analysis (see `Create a new
analysis`_ section) or by defining a .mupa file pointing to your
annotation file (see `Load a mussa parameter file`_ section).

Motifs
~~~~~~

Load Motifs from File
*********************

It is possible to load motifs from a file which was saved from a
previous run or by defining your own motif file. See the `Motif File
Format`_ section for details.

To load a motif file, select **Load Motif List** item from the
**File** menu and select a motif list file.

.. image:: images/load_motif.png
   :alt: Load Motif List
   :align: center


Save Motifs to File
*******************

Note: Currently not implemented


Motif Dialog
************

Mussa has the ability to find lab motifs using the `IUPAC Nucleotide
Code`_ for defining a motif. To define a motif, select **View > Edit
Motifs** menu item as shown below.

.. image:: images/view_edit_motifs.png
   :alt: "View > Edit Motifs" Menu
   :align: center

You will see a dialog box appear with a "set motifs" button and 10
rows for defining motifs and the color that will be displayed on the
sequence. By default all 10 motifs start off as with white as the color.

.. image:: images/motif_dialog_start.png
   :alt: Motif Dialog
   :align: center


Detailed Info
-------------

Threshold
~~~~~~~~~

The threshold of an analysis is in minimum number of base pair matches
must be meet to in order to be kept as a match. Note that you can vary
the threshold from within Mussagl. For example, if you choose a
`window size`_ of **30** and a **threshold** of **20** the mussa nway
transitive algorithm will store all matches that are 20 out of 30 bp
matches or better and pass it on to Mussagl. Mussagl will then allow
you to dynamically choose a threshold from 20 to 30 base pairs. A
threshold of 30 bps would only show 30 out of 30 bp matches. A
threshold of 20 bps would show all matches of 20 out of 30 bps or
better. If you would like to see results for matches lower than 20 out
of 30, you will need to rerun the analysis with a lower threshold.

Window Size
~~~~~~~~~~~

The typical sizes people tend to choose are between 20 and 30. You
will likely need to experiment with this setting depending on your
needs and input sequence.


Sequences
~~~~~~~~~

Mussa reads in sequences which are formated in the fasta_
format. Mussa may take a long time to run (>10 minutes) if the total
bp length near 280Kb. Once mussa has run once, you can reload
previously run analyses.

FIXME: We have learned more about how much sequence and how many to
put in mussagl, this information should be documented here.


Mussa File Formats
------------------

.. _param:

Parameter File Format
~~~~~~~~~~~~~~~~~~~~~

**File Format (.mupa):**

::

  # name of anaylsis directory and stem for associated files
  ANA_NAME <analysis_name>
  
  # if APPEND vars true, a _wXX and/or _tYY added to analysis name
  # where XX = WINDOW and YY = THRESHOLD
  # Highly recommeded with use of command line override of WINDOW or THRESHOLD
  APPEND_WIN <true/false>
  APPEND_THRES <true/false>
  
  # how many sequences are being analyzed
  SEQUENCE_NUM <num>
  
  # first sequence info
  SEQUENCE <fasta_file_path>
  ANNOTATION <annotation_file_path>
  SEQ_START <sequence_start>
  
  # the second sequence info
  SEQUENCE <fasta_file_path>
  # ANNOTATION <annotation_file_path>
  SEQ_START <sequence_start>
  # SEQ_END <sequence_end>

  # third sequence info
  SEQUENCE <fasta_file_path>
  # ANNOTATION <annotation_file_path>
  
  # analyses parameters: command line args -w -t will override these
  WINDOW <num>
  THRESHOLD <num>

.. csv-table:: Parameter File Options:
   :header: "Option Name", "Value", "Default", "Required", "Description"
   :widths: 30 30 30 30 60

   "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
   name of directory where analysis will be saved." 
   "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
   "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
   "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
   to analyse" 
   "SEQUENCE", "/fasta/filepath.fa", "N/A", "true", "Must define one
   sequence per SEQUENCE_NUM." 
   "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
   annotation file. See `annotation file format`_ section for more
   information." 
   "SEQ_START", "integer", "1", "false", "Optional index into fasta file"
   "SEQ_END", "integer", "1", "false", "Optional index into fasta file"
   "WINDOW", "integer", "N/A", "true", "`Window Size`_"
   "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"

.. _annot:

Annotation File Format
~~~~~~~~~~~~~~~~~~~~~~

The first line in the file is the sequence name. Each line there after
is a **space** seperated annotation. 

New as of build 198:
 
 * The annotation format now supports fasta sequences embeded in the
   annotation file as shown in the format example below. Mussagl will
   take this sequence and look for an exact match of this sequence in
   your sequences. If a match is found, it will label it with the name 
   of from the fasta header.

Format:

::
  
  <species/sequence_name>
  <start> <stop> <annotation_name> <annotation_type>
  <start> <stop> <annotation_name> <annotation_type>
  <start> <stop> <annotation_name> <annotation_type>
  <start> <stop> <annotation_name> <annotation_type>
  >Fasta Header
  ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
  ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
  TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
  ACGTACGGCAGTACGCGGTCAGA
  <start> <stop> <annotation_name> <annotation_type>
  ...

Example:

::

  Mouse
  251 500 Glorp Glorptype
  751 1000 Glorp Glorptype
  1251 1500 Glorp Glorptype
  >My favorite DNA sequence
  GATTACA
  1751 2000 Glorp Glorptype


.. _motif_file_format:

Motif File Format
~~~~~~~~~~~~~~~~~

Format:

  <motif> <red> <green> <blue>
  
Example:

  GGCC 0.0 1 1



IUPAC Nucleotide Code
~~~~~~~~~~~~~~~~~~~~~

For your convience, below is a table of the IUPAC Nucleotide Code.

The following table is table 1 from "Nomenclature for Incompletely
Specified Bases in Nucleic Acid Sequences" which can be found at
http://www.chem.qmul.ac.uk/iubmb/misc/naseq.html.

======  =================  ===================================
Symbol  Meaning            Origin of designation
======  =================  ===================================
G       G                  Guanine
A       A                  Adenine
T       T                  Thymine
C       C                  Cytosine
R       G or A             puRine
Y       T or C             pYrimidine
M       A or C             aMino
K       G or T             Keto
S       G or C             Strong interaction (3 H bonds)
W       A or T             Weak interaction (2 H bonds)
H       A or C or T        not-G, H follows G in the alphabet
B       G or T or C        not-A, B follows A
V       G or C or A        not-T (not-U), V follows U
D       G or A or T        not-C, D follows C
N       G or A or T or C   aNy
======  =================  ===================================


.. Define links below
   ------------------

.. _GPL: http://www.opensource.org/licenses/gpl-license.php
.. _wiki: http://mussa.caltech.edu
.. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
.. _fasta: http://en.wikipedia.org/wiki/FASTA_format
.. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif