8 Last updated: May 18th, 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, dubble 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 experiement 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 Mussgl 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 .. Screenshot 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 rabit.
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 subsequence and you
276 may also choose any color for display of the annoation; 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 lines between sequence bars.
307 The red lines between the sequence bars represent conservation between
308 the sequences. The amount of sequence conservation shown will depend
309 on the relatedness of your sequences and the `dynamic threshold` you
310 are using. Sequences with lots of repeats will cause major slow downs
311 in calculating the matches.
317 .. image:: images/motif_toggle.png
321 Toggles motifs on and off. This will not turn on and off annotations.
323 Note: As of the current build (#200), this feature hasn't been
330 .. image:: images/zoom_factor.png
334 The zoom factor represents the number of base pairs represented per
335 pixel. When you zoom in far enough the sequence will switch from
336 seeing a black bar, representing the sequence, to the actual sequence
337 (well, ASCII representation of sequence).
343 .. image:: images/dynamic_threshold.png
344 :alt: Dynamic Threshold
347 You can dynamically change the threshold for how strong of match you
348 consider the conservation to be with one of two options:
350 1. Number of base pair matchs out of window size.
352 2. Percent base pair conservation.
354 See the Threshold_ section for more infromation.
357 Sequence Information Bar
358 ~~~~~~~~~~~~~~~~~~~~~~~~
360 .. image:: images/seq_info_bar.png
361 :alt: Sequence Information Bar
364 The sequence infomation bars can be found to the left and right sides
365 of mussagl. Next to each sequence you will find the following
368 1. Species (If it has been defined)
369 2. Total Size of Sequence
370 3. Current base pair position
376 .. image:: images/scroll_bar.png
377 :alt: Sequence Scroll Bar
380 The scroll bar allows you to scroll through the sequence which is
381 useful when you have zoomed in using the `zoom factor`_.
390 Currently annotations can be added to a sequence using the mussa
391 `annotation file format`_ and can be loaded by selecting the
392 annotation file when defining a new analysis (see `Create a new
393 analysis`_ section) or by defining a .mupa file pointing to your
394 annotation file (see `Load a mussa parameter file`_ section).
399 Load Motifs from File
400 *********************
402 It is possible to load motifs from a file which was saved from a
403 previous run or by defining your own motif file. See the `Motif File
404 Format`_ section for details.
406 To load a motif file, select **Load Motif List** item from the
407 **File** menu and select a motif list file.
409 .. image:: images/load_motif.png
410 :alt: Load Motif List
417 Note: Currently not implemented
423 FIXME: Continue here.
431 The threshold of an analysis is in minimum number of base pair matches
432 must be meet to in order to be kept as a match. Note that you can vary
433 the threshold from within Mussagl. For example, if you choose a
434 `window size`_ of **30** and a **threshold** of **20** the mussa nway
435 transitive algorithm will store all matches that are 20 out of 30 bp
436 matches or better and pass it on to Mussagl. Mussagl will then allow
437 you to dynamically choose a threshold from 20 to 30 base pairs. A
438 threshold of 30 bps would only show 30 out of 30 bp matches. A
439 threshold of 20 bps would show all matches of 20 out of 30 bps or
440 better. If you would like to see results for matches lower than 20 out
441 of 30, you will need to rerun the analysis with a lower threshold.
446 The typical sizes people tend to choose are between 20 and 30. You
447 will likely need to experiment with this setting depending on your
448 needs and input sequence.
454 Mussa reads in sequences which are formated in the fasta_
455 format. Mussa may take a long time to run (>10 minutes) if the total
456 bp length near 280Kb. Once mussa has run once, you can reload
457 previously run analyses.
459 FIXME: We have learned more about how much sequence and how many to
460 put in mussagl, this information should be documented here.
468 Parameter File Format
469 ~~~~~~~~~~~~~~~~~~~~~
471 **File Format (.mupa):**
475 # name of anaylsis directory and stem for associated files
476 ANA_NAME <analysis_name>
478 # if APPEND vars true, a _wXX and/or _tYY added to analysis name
479 # where XX = WINDOW and YY = THRESHOLD
480 # Highly recommeded with use of command line override of WINDOW or THRESHOLD
481 APPEND_WIN <true/false>
482 APPEND_THRES <true/false>
484 # how many sequences are being analyzed
487 # first sequence info
488 SEQUENCE <fasta_file_path>
489 ANNOTATION <annotation_file_path>
490 SEQ_START <sequence_start>
492 # the second sequence info
493 SEQUENCE <fasta_file_path>
494 # ANNOTATION <annotation_file_path>
495 SEQ_START <sequence_start>
496 # SEQ_END <sequence_end>
498 # third sequence info
499 SEQUENCE <fasta_file_path>
500 # ANNOTATION <annotation_file_path>
502 # analyses parameters: command line args -w -t will override these
506 .. csv-table:: Parameter File Options:
507 :header: "Option Name", "Value", "Default", "Required", "Description"
508 :widths: 30 30 30 30 60
510 "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
511 name of directory where analysis will be saved."
512 "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
513 "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
514 "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
516 "SEQUENCE", "/fasta/filepath.fa", "N/A", "true", "Must define one
517 sequence per SEQUENCE_NUM."
518 "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
519 annotation file. See `annotation file format`_ section for more
521 "SEQ_START", "integer", "1", "false", "Optional index into fasta file"
522 "SEQ_END", "integer", "1", "false", "Optional index into fasta file"
523 "WINDOW", "integer", "N/A", "true", "`Window Size`_"
524 "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
528 Annotation File Format
529 ~~~~~~~~~~~~~~~~~~~~~~
531 The first line in the file is the sequence name. Each line there after
532 is a **space** seperated annotation.
536 * The annotation format now supports fasta sequences embeded in the
537 annotation file as shown in the format example below. Mussagl will
538 take this sequence and look for an exact match of this sequence in
539 your sequences. If a match is found, it will label it with the name
540 of from the fasta header.
546 <species/sequence_name>
547 <start> <stop> <annotation_name> <annotation_type>
548 <start> <stop> <annotation_name> <annotation_type>
549 <start> <stop> <annotation_name> <annotation_type>
550 <start> <stop> <annotation_name> <annotation_type>
552 ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
553 ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
554 TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
555 ACGTACGGCAGTACGCGGTCAGA
556 <start> <stop> <annotation_name> <annotation_type>
564 251 500 Glorp Glorptype
565 751 1000 Glorp Glorptype
566 1251 1500 Glorp Glorptype
567 >My favorite DNA sequence
569 1751 2000 Glorp Glorptype
572 .. _motif_file_format:
579 <motif> <red> <green> <blue>
586 .. Define links below
589 .. _GPL: http://www.opensource.org/licenses/gpl-license.php
590 .. _wiki: http://mussa.caltech.edu
591 .. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
592 .. _fasta: http://en.wikipedia.org/wiki/FASTA_format
593 .. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif