==============
Mussagl Manual
==============
-------------------
-By Brandon W. King
-------------------
+---------------
+Brandon W. King
+---------------
-Last updated: May 18th, 2006
+Last updated: May 23th, 2006
-Updated to Mussagl build: 141 (Update to 200 in progress)
+Updated to Mussagl build: 200 (Update to 230 in progress)
.. contents::
Mac OS X
~~~~~~~~
-Once you have downloaded the .dmg file, dubble click on it and follow
+Once you have downloaded the .dmg file, double click on it and follow
the install instructions.
FIXME: Mention how to launch the program.
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.
+To start Mussagl, launch the program from Start > Programs > Mussagl >
+Mussagl.
Linux
__ wiki_
+Obtaining Input Data
+====================
+
+If you already have your data, you can skip ahead to the the `Using
+Mussagl`_ section.
+
+Lets say you have a gene of interest called 'SMN1' and you want to
+know how the sequence surrounding the gene in multiple species is
+conserved. Guess what, that's what we are going to do, retrieve the
+DNA sequence for SMN1 and prepare it for using in Mussa.
+
+For more information about SMN1 visit `NCBI's OMIM
+<http://www.ncbi.nlm.nih.gov/entrez/dispomim.cgi?id=609682>`_.
+
+UCSC Genome Browser Method
+--------------------------
+
+There are many methods of retrieving DNA sequence, but for this
+example we will retrieve SMN1 through the UCSC genome broswer located
+at http://genome.ucsc.edu/.
+
+.. image:: images/ucsc_genome_browser_home.png
+ :alt: UCSC Genome Broswer
+ :align: center
+
+Step 1 - Find SMN1
+~~~~~~~~~~~~~~~~~~
+
+The first step in finding SMN1 is to use the **Gene Sorter** menu
+option which I have highlighted in orange below:
+
+.. image:: images/ucsc_menu_bar_gene_sorter.png
+ :alt: Gene Sorter Menu Option
+ :align: center
+
+Gene Sorter page:
+
+.. image:: images/ucsc_gene_sorter.png
+ :alt: Gene Sorter
+ :align: center
+
+We will start by looking for SMN1 in the **Human Genome** and **sorting by name similarity**.
+
+.. image:: images/ucsc_gs_sort_name_sim.png
+ :alt: Gene Sorter - Name Similarity
+ :align: center
+
+After you have selected **Human Genome** and **sorting by name similarity**, type *SMN1* into the search box.
+
+.. image:: images/ucsc_gs_smn1.png
+ :alt: Gene
+ :align: center
+
+Press **Go!** and you should see the following page:
+
+.. image:: images/ucsc_gs_found.png
+ :alt: Found SMN1
+ :align: center
+
+Click on **SMN1** and you will be taking the gene expression atlas
+page.
+
+.. image:: images/ucsc_gs_genome_position.png
+ :alt: Gene expression atlas
+ :align: center
+
+Click on **chr5 70,270,558** found in the **SMN1 row**, **Genome
+position column**.
+
+Now we have found the location of SMN1 on human!
+
+.. image:: images/ucsc_gb_smn1_human.png
+ :alt: Genome Browser - SMN1 (human)
+ :align: center
+
+FIXME: continue here.
+
Using Mussagl
=============
Create/Load Analysis
----------------------
-Currently there are three ways to load a mussa experiment.
+Currently there are three ways to load a Mussa experiment.
1. `Create a new analysis`_
2. `Load a mussa parameter file`_ (.mupa)
Instructions:
- 1. **Give the experiement a name**, for this demo, we'll use
+ 1. **Give the experiment 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.
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
+files using the mussa `Annotation File Format`_ to add annotations to
your sequence.
.. image:: images/define_analysis_step2.png
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 >
+Once you have a .mupa file created, load Mussagl and select the **File >
Load Mussa Parameters** menu option. Select the .mupa file and click
open.
Overview
~~~~~~~~
-.. Screenshot with numbers showing features.
+.. Screen-shot with numbers showing features.
.. image:: images/window_overview.png
:alt: Mussa Window
: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.
+case the sequence around the gene 'MCK' in human, mouse, and rabbit.
FIXME: Should I mention the repeats here?
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
+define annotations by location or using an exact sub-sequence and you
+may also choose any color for display of the annotation; see the
`Annotation File Format`_ section for details.
Note: Currently there is no way to add annotations using the GUI (only
Motif shown in light blue on sequence bar.
-The only real difference between an annotation and motif in mussagl is
+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.
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.
+ 1. Number of base pair matches out of window size.
2. Percent base pair conservation.
-See the Threshold_ section for more infromation.
+See the Threshold_ section for more information.
Sequence Information Bar
: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
+The sequence information 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)
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.
+sequence. By default all 10 motifs start off as with white as the
+color. In the image below, I changed the color from white to blue to
+make it easier to see.
.. image:: images/motif_dialog_start.png
:alt: Motif Dialog
:align: center
+Now lets make a motif **'AT[C or G]CT'**. Using the `IUPAC Nucleotide
+Code`_, type in **'ATSCT'** into the first box as shown below.
-Detailed Info
--------------
+.. image:: images/motif_dialog_enter_motif.png
+ :alt: Enter Motif
+ :align: center
+
+Now choose a color for your motif by clicking on the colored area to
+the left of the motif. In the image above, you would click on the blue
+square, but by default the squares will be white. Remember to choose a
+color that will show up well with a black bar as the background.
+
+.. image:: images/color_chooser.png
+ :alt: Color Chooser
+ :align: center
+
+Once you have selected the color for your motif, click on the 'set
+motifs' button. Notice that if Mussa finds matches to your motif will
+now show up in the main Mussagl window.
+
+Before Motif:
+
+.. image:: images/motif_dialog_bar_before.png
+ :alt: Sequence bar before motif
+ :align: center
+
+After Motif:
+
+.. image:: images/motif_dialog_bar_after.png
+ :alt: Sequence bar after motif
+ :align: center
+
+
+View Mussa Alignements
+----------------------
+
+Mussagl allows you to zoom in on Mussa alignments by selecting the set
+of alignment(s) of interest. To do this, move the mouse near the
+alignment you are interested in viewing and then **PRESS** and
+**HOLD** the **LEFT mouse button** and **drag the mouse** to the other
+side of the conservation track so that you see a bounding box
+overlaping the alienment(s) of interest and then **let go** of the
+*left mouse button*.
+
+In the example below, I started by left clicking on the area marked by
+a red dot (upper left corner of bounding box) and draging the mouse to
+the area marked by a blue dot (lower right corner of the bounding box)
+and letting go of the left mouse button.
+
+.. image:: images/select_sequence.png
+ :alt: Select Sequence
+ :align: center
+
+All of the lines which were not selected should be washed out as shown
+below:
+
+.. image:: images/washed_out.png
+ :alt: Tracks washed out
+ :align: center
+
+With a selection made, goto the **View** menu and select **View mussa alignment**.
+
+.. image:: images/view_mussa_alignment.png
+ :alt: View mussa alignment
+ :align: center
+
+You should see the alignment at the base-pair level as shown below.
+
+.. image:: images/mussa_alignment.png
+ :alt: Mussa alignment
+ :align: center
+
+
+
+
+Saving to an Image
+---------------------------------
+
+FIXME: Need to write this section
+
+
+Detailed Information
+--------------------
Threshold
~~~~~~~~~
Sequences
~~~~~~~~~
-Mussa reads in sequences which are formated in the fasta_
+Mussa reads in sequences which are formatted 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.
+previously run analyzes.
FIXME: We have learned more about how much sequence and how many to
-put in mussagl, this information should be documented here.
+put in Mussagl, this information should be documented here.
Mussa File Formats
::
- # name of anaylsis directory and stem for associated files
+ # name of analysis directory and stem for associated files
ANA_NAME <analysis_name>
# if APPEND vars true, a _wXX and/or _tYY added to analysis name
SEQUENCE <fasta_file_path>
# ANNOTATION <annotation_file_path>
- # analyses parameters: command line args -w -t will override these
+ # analyzes parameters: command line args -w -t will override these
WINDOW <num>
THRESHOLD <num>
"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"
+ to analyze"
"SEQUENCE", "/fasta/filepath.fa", "N/A", "true", "Must define one
sequence per SEQUENCE_NUM."
"ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
~~~~~~~~~~~~~~~~~~~~~~
The first line in the file is the sequence name. Each line there after
-is a **space** seperated annotation.
+is a **space** separated annotation.
New as of build 198:
- * The annotation format now supports fasta sequences embeded in the
+ * The annotation format now supports fasta sequences embedded 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
IUPAC Nucleotide Code
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~
-For your convience, below is a table of the IUPAC Nucleotide Code.
+For your convenience, 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
.. _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
-
+.. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif
\ No newline at end of file