8 Last updated: May 23th, 2006
10 Updated to Mussagl build: 141 (Update to 200 in progress)
23 Short History of Mussa
24 ----------------------
27 Mussa Python/PMW Prototype
28 ~~~~~~~~~~~~~~~~~~~~~~~~~~
45 Mussagl has been released open source under the `GPL v2
53 You have the option of building from source or downloading prebuilt
54 binaries. Most people will want the prebuilt versions.
58 * Mac OS X (binary or source)
59 * Windows XP (binary or source)
65 Mussagl in binary form for OS X and Windows and/or source can be
66 downloaded from http://mussa.caltech.edu/.
73 Once you have downloaded the .dmg file, double click on it and follow
74 the install instructions.
76 FIXME: Mention how to launch the program.
81 Once you have downloaded the Mussagl installer, double click on the
82 installer and follow the install instructions.
84 To start Mussagl, launch the program from Start > Programs > Mussagl >
90 Currently we do not have a binary installer for Linux. You will have
91 to build from source. See the 'build from source' section below.
97 Instructions for building from source can be found `build page
98 <http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild>`_ on the
110 Launch Mussagl... It should look similar to the screen shot below.
112 .. image:: images/opened.png
119 ----------------------
121 Currently there are three ways to load a Mussa experiment.
123 1. `Create a new analysis`_
124 2. `Load a mussa parameter file`_ (.mupa)
125 3. `Load an analysis`_
129 Create a new analysis
130 ~~~~~~~~~~~~~~~~~~~~~
132 To create a new analysis select 'Define analysis' from the 'File'
133 menu. You should see a dialog box similar to the one below. For this
134 demo we will use the example sequences that come with Mussagl.
136 .. image:: images/define_analysis.png
137 :alt: Define Analysis
142 1. **Give the experiment a name**, for this demo, we'll use
143 'demo_w30_t20'. Mussa will create a folder with this name to store
144 the analysis files in once it has been run.
146 2. Choose a `window size`_. For this demo **choose 30**.
148 3. Choose a threshold_... for this demo **choose 20**. See the
149 Threshold_ section for more detailed information.
151 4. Choose the number of sequences_ you would like. For this demo
154 .. image:: images/define_analysis_step1a.png
158 Now click on the 'Browse' button next to the sequence input box and
159 then select /examples/seq/human_mck_pro.fa file. Do the same in the
160 next two sequence input boxes selecting mouse_mck_pro.fa and
161 rabbit_mck_pro.fa as shown below. Note that you can create annotation
162 files using the mussa `Annotation File Format`_ to add annotations to
165 .. image:: images/define_analysis_step2.png
166 :alt: Choose sequences
169 Click the **create** button and in a few moments you should see
170 something similar to the following screen shot.
172 .. image:: images/demo.png
176 This analysis is now saved in a directory called **demo_w30_t20** in
177 the current working directory. If you close and reopen Mussagl, you
178 can reload the saved analysis. See `Load an analysis`_ section below
182 Load a mussa parameter file
183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
185 If you prefer, you can define your Mussa analysis using the Mussa
186 parameter file. See the `Parameter File Format`_ section for details
187 on creating a .mupa file.
189 Once you have a .mupa file created, load Mussagl and select the **File >
190 Load Mussa Parameters** menu option. Select the .mupa file and click
193 .. image:: images/load_mupa_menu.png
194 :alt: Load Mussa Parameters
197 If you would like to see an example, you can load the
198 **mck3test.mupa** file in the examples directory that comes with
201 .. image:: images/load_mupa_dialog.png
202 :alt: Load Mussa Parameters Dialog
209 To load a previously run analysis open Mussagl and select the **File >
210 Load Analysis** menu option. Select an analysis **directory** and
213 .. image:: images/load_analysis_menu.png
214 :alt: Load Analysis Menu
223 .. Screen-shot with numbers showing features.
225 .. image:: images/window_overview.png
231 1. `DNA Sequence (Black bars)`_
237 4. `Conservation tracks`_
241 6. `Zoom Factor`_ (Base pairs per pixel)
243 7. `Dynamic Threshold`_
245 8. `Sequence Information Bar`_
247 9. `Sequence Scroll Bar`_
250 DNA Sequence (black bars)
251 ~~~~~~~~~~~~~~~~~~~~~~~~~
253 .. image:: images/sequence_bar.png
257 Each of the black bars represents one of the loaded sequences, in this
258 case the sequence around the gene 'MCK' in human, mouse, and rabbit.
260 FIXME: Should I mention the repeats here?
266 .. figure:: images/annotation.png
270 Annotation shown in green on sequence bar.
273 Annotations can be included on any of the sequences using the `Load a
274 mussa parameter file`_ method of loading your sequences. You can
275 define annotations by location or using an exact sub-sequence and you
276 may also choose any color for display of the annotation; see the
277 `Annotation File Format`_ section for details.
279 Note: Currently there is no way to add annotations using the GUI (only
280 via the .mupa file). We plan to add this feature in the future, but it
281 likely will not make it into the first release.
287 .. figure:: images/motif.png
291 Motif shown in light blue on sequence bar.
293 The only real difference between an annotation and motif in Mussagl is
294 that you can define motifs from within the GUI. See the `Motifs`_
295 section for more information.
301 .. figure:: images/conservation_tracks.png
302 :alt: Conservation Tracks
305 Conservations tracks shown as red and blue lines between sequence
308 The **red lines** between the sequence bars represent conservation
309 between the sequences and **blue lines** represent **reverse
310 complement** conservation. The amount of sequence conservation shown
311 will depend on the relatedness of your sequences and the `dynamic
312 threshold` you are using. Sequences with lots of repeats will cause
313 major slow downs in calculating the matches.
319 .. image:: images/motif_toggle.png
323 Toggles motifs on and off. This will not turn on and off annotations.
325 Note: As of the current build (#200), this feature hasn't been
332 .. image:: images/zoom_factor.png
336 The zoom factor represents the number of base pairs represented per
337 pixel. When you zoom in far enough the sequence will switch from
338 seeing a black bar, representing the sequence, to the actual sequence
339 (well, ASCII representation of sequence).
345 .. image:: images/dynamic_threshold.png
346 :alt: Dynamic Threshold
349 You can dynamically change the threshold for how strong of match you
350 consider the conservation to be with one of two options:
352 1. Number of base pair matches out of window size.
354 2. Percent base pair conservation.
356 See the Threshold_ section for more information.
359 Sequence Information Bar
360 ~~~~~~~~~~~~~~~~~~~~~~~~
362 .. image:: images/seq_info_bar.png
363 :alt: Sequence Information Bar
366 The sequence information bars can be found to the left and right sides
367 of Mussagl. Next to each sequence you will find the following
370 1. Species (If it has been defined)
371 2. Total Size of Sequence
372 3. Current base pair position
378 .. image:: images/scroll_bar.png
379 :alt: Sequence Scroll Bar
382 The scroll bar allows you to scroll through the sequence which is
383 useful when you have zoomed in using the `zoom factor`_.
392 Currently annotations can be added to a sequence using the mussa
393 `annotation file format`_ and can be loaded by selecting the
394 annotation file when defining a new analysis (see `Create a new
395 analysis`_ section) or by defining a .mupa file pointing to your
396 annotation file (see `Load a mussa parameter file`_ section).
401 Load Motifs from File
402 *********************
404 It is possible to load motifs from a file which was saved from a
405 previous run or by defining your own motif file. See the `Motif File
406 Format`_ section for details.
408 To load a motif file, select **Load Motif List** item from the
409 **File** menu and select a motif list file.
411 .. image:: images/load_motif.png
412 :alt: Load Motif List
419 Note: Currently not implemented
425 Mussa has the ability to find lab motifs using the `IUPAC Nucleotide
426 Code`_ for defining a motif. To define a motif, select **View > Edit
427 Motifs** menu item as shown below.
429 .. image:: images/view_edit_motifs.png
430 :alt: "View > Edit Motifs" Menu
433 You will see a dialog box appear with a "set motifs" button and 10
434 rows for defining motifs and the color that will be displayed on the
435 sequence. By default all 10 motifs start off as with white as the
436 color. In the image below, I changed the color from white to blue to
437 make it easier to see.
439 .. image:: images/motif_dialog_start.png
443 Now lets make a motif **'AT[C or G]CT'**. Using the `IUPAC Nucleotide
444 Code`_, type in **'ATSCT'** into the first box as shown below.
446 .. image:: images/motif_dialog_enter_motif.png
450 Now choose a color for your motif by clicking on the colored area to
451 the left of the motif. In the image above, you would click on the blue
452 square, but by default the squares will be white. Remember to choose a
453 color that will show up well with a black bar as the background.
455 .. image:: images/color_chooser.png
459 Once you have selected the color for your motif, click on the 'set
460 motifs' button. Notice that if Mussa finds matches to your motif will
461 now show up in the main Mussagl window.
465 .. image:: images/motif_dialog_bar_before.png
466 :alt: Sequence bar before motif
471 .. image:: images/motif_dialog_bar_after.png
472 :alt: Sequence bar after motif
476 View Mussa Alignements
477 ----------------------
479 Mussagl allows you to zoom in on Mussa alignments by selecting the set
480 of alignment(s) of interest. To do this, move the mouse near the
481 alignment you are interested in viewing and then **PRESS** and
482 **HOLD** the **LEFT mouse button** and **drag the mouse** to the other
483 side of the conservation track so that you see a bounding box
484 overlaping the alienment(s) of interest and then **let go** of the
487 In the example below, I started by left clicking on the area marked by
488 a red dot (upper left corner of bounding box) and draging the mouse to
489 the area marked by a blue dot (lower right corner of the bounding box)
490 and letting go of the left mouse button.
492 .. image:: images/select_sequence.png
493 :alt: Select Sequence
496 All of the lines which were not selected should be washed out as shown
499 .. image:: images/washed_out.png
500 :alt: Tracks washed out
503 With a selection made, goto the **View** menu and select **View mussa alignment**.
505 .. image:: images/view_mussa_alignment.png
506 :alt: View mussa alignment
509 You should see the alignment at the base-pair level as shown below.
511 .. image:: images/mussa_alignment.png
512 :alt: Mussa alignment
519 ---------------------------------
521 FIXME: Need to write this section
530 The threshold of an analysis is in minimum number of base pair matches
531 must be meet to in order to be kept as a match. Note that you can vary
532 the threshold from within Mussagl. For example, if you choose a
533 `window size`_ of **30** and a **threshold** of **20** the mussa nway
534 transitive algorithm will store all matches that are 20 out of 30 bp
535 matches or better and pass it on to Mussagl. Mussagl will then allow
536 you to dynamically choose a threshold from 20 to 30 base pairs. A
537 threshold of 30 bps would only show 30 out of 30 bp matches. A
538 threshold of 20 bps would show all matches of 20 out of 30 bps or
539 better. If you would like to see results for matches lower than 20 out
540 of 30, you will need to rerun the analysis with a lower threshold.
545 The typical sizes people tend to choose are between 20 and 30. You
546 will likely need to experiment with this setting depending on your
547 needs and input sequence.
553 Mussa reads in sequences which are formatted in the fasta_
554 format. Mussa may take a long time to run (>10 minutes) if the total
555 bp length near 280Kb. Once mussa has run once, you can reload
556 previously run analyzes.
558 FIXME: We have learned more about how much sequence and how many to
559 put in Mussagl, this information should be documented here.
567 Parameter File Format
568 ~~~~~~~~~~~~~~~~~~~~~
570 **File Format (.mupa):**
574 # name of analysis directory and stem for associated files
575 ANA_NAME <analysis_name>
577 # if APPEND vars true, a _wXX and/or _tYY added to analysis name
578 # where XX = WINDOW and YY = THRESHOLD
579 # Highly recommeded with use of command line override of WINDOW or THRESHOLD
580 APPEND_WIN <true/false>
581 APPEND_THRES <true/false>
583 # how many sequences are being analyzed
586 # first sequence info
587 SEQUENCE <fasta_file_path>
588 ANNOTATION <annotation_file_path>
589 SEQ_START <sequence_start>
591 # the second sequence info
592 SEQUENCE <fasta_file_path>
593 # ANNOTATION <annotation_file_path>
594 SEQ_START <sequence_start>
595 # SEQ_END <sequence_end>
597 # third sequence info
598 SEQUENCE <fasta_file_path>
599 # ANNOTATION <annotation_file_path>
601 # analyzes parameters: command line args -w -t will override these
605 .. csv-table:: Parameter File Options:
606 :header: "Option Name", "Value", "Default", "Required", "Description"
607 :widths: 30 30 30 30 60
609 "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
610 name of directory where analysis will be saved."
611 "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
612 "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
613 "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
615 "SEQUENCE", "/fasta/filepath.fa", "N/A", "true", "Must define one
616 sequence per SEQUENCE_NUM."
617 "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
618 annotation file. See `annotation file format`_ section for more
620 "SEQ_START", "integer", "1", "false", "Optional index into fasta file"
621 "SEQ_END", "integer", "1", "false", "Optional index into fasta file"
622 "WINDOW", "integer", "N/A", "true", "`Window Size`_"
623 "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
627 Annotation File Format
628 ~~~~~~~~~~~~~~~~~~~~~~
630 The first line in the file is the sequence name. Each line there after
631 is a **space** separated annotation.
635 * The annotation format now supports fasta sequences embedded in the
636 annotation file as shown in the format example below. Mussagl will
637 take this sequence and look for an exact match of this sequence in
638 your sequences. If a match is found, it will label it with the name
639 of from the fasta header.
645 <species/sequence_name>
646 <start> <stop> <annotation_name> <annotation_type>
647 <start> <stop> <annotation_name> <annotation_type>
648 <start> <stop> <annotation_name> <annotation_type>
649 <start> <stop> <annotation_name> <annotation_type>
651 ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
652 ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
653 TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
654 ACGTACGGCAGTACGCGGTCAGA
655 <start> <stop> <annotation_name> <annotation_type>
663 251 500 Glorp Glorptype
664 751 1000 Glorp Glorptype
665 1251 1500 Glorp Glorptype
666 >My favorite DNA sequence
668 1751 2000 Glorp Glorptype
671 .. _motif_file_format:
678 <motif> <red> <green> <blue>
686 IUPAC Nucleotide Code
687 ~~~~~~~~~~~~~~~~~~~~~~
689 For your convenience, below is a table of the IUPAC Nucleotide Code.
691 The following table is table 1 from "Nomenclature for Incompletely
692 Specified Bases in Nucleic Acid Sequences" which can be found at
693 http://www.chem.qmul.ac.uk/iubmb/misc/naseq.html.
695 ====== ================= ===================================
696 Symbol Meaning Origin of designation
697 ====== ================= ===================================
706 S G or C Strong interaction (3 H bonds)
707 W A or T Weak interaction (2 H bonds)
708 H A or C or T not-G, H follows G in the alphabet
709 B G or T or C not-A, B follows A
710 V G or C or A not-T (not-U), V follows U
711 D G or A or T not-C, D follows C
712 N G or A or T or C aNy
713 ====== ================= ===================================
716 .. Define links below
719 .. _GPL: http://www.opensource.org/licenses/gpl-license.php
720 .. _wiki: http://mussa.caltech.edu
721 .. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
722 .. _fasta: http://en.wikipedia.org/wiki/FASTA_format
723 .. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif