doc/manual/mussagl_manual.rst

   1 ==============
   2 Mussagl Manual
   3 ==============
   4 ---------------
   5 Brandon W. King
   6 ---------------
   7
   8 Last updated: May 23th, 2006
   9
  10 Updated to Mussagl build: 141 (Update to 200 in progress)
  11
  12
  13 .. contents::
  14
  15 Introduction
  16 ============
  17
  18
  19 What is Mussagl?
  20 ----------------
  21
  22
  23 Short History of Mussa
  24 ----------------------
  25
  26
  27 Mussa Python/PMW Prototype
  28 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  29
  30
  31 Mussa C++/FLTK
  32 ~~~~~~~~~~~~~~
  33
  34
  35 Mussagl C++/Qt/OpenGL
  36 ~~~~~~~~~~~~~~~~~~~~~
  37
  38
  39 Getting Mussagl
  40 ===============
  41
  42 License
  43 -------
  44
  45 Mussagl has been released open source under the `GPL v2
  46 license`__.
  47
  48 __ GPL_
  49
  50 Platforms
  51 ---------
  52
  53 You have the option of building from source or downloading prebuilt
  54 binaries. Most people will want the prebuilt versions.
  55
  56 Supported Platforms:
  57
  58  * Mac OS X (binary or source)
  59  * Windows XP (binary or source)
  60  * Linux (source)
  61
  62 Download
  63 --------
  64
  65 Mussagl in binary form for OS X and Windows and/or source can be
  66 downloaded from http://mussa.caltech.edu/.
  67
  68 Install
  69 -------
  70
  71 Mac OS X
  72 ~~~~~~~~
  73 Once you have downloaded the .dmg file, double click on it and follow
  74 the install instructions.
  75
  76 FIXME: Mention how to launch the program.
  77
  78
  79 Windows XP
  80 ~~~~~~~~~~
  81 Once you have downloaded the Mussagl installer, double click on the
  82 installer and follow the install instructions.
  83
  84 To start Mussagl, launch the program from Start > Programs > Mussagl >
  85 Mussagl.
  86
  87
  88 Linux
  89 ~~~~~
  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.
  92
  93
  94 Build from Source
  95 ~~~~~~~~~~~~~~~~~
  96
  97 Instructions for building from source can be found `build page
  98 <http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild>`_ on the
  99 `Mussa wiki`__.
 100
 101 __ wiki_
 102
 103
 104 Using Mussagl
 105 =============
 106
 107
 108 Launch Mussagl
 109 --------------
 110 Launch Mussagl... It should look similar to the screen shot below.
 111
 112 .. image:: images/opened.png
 113    :alt: Launch Mussa
 114    :align: center
 115
 116
 117
 118 Create/Load Analysis
 119 ----------------------
 120
 121 Currently there are three ways to load a Mussa experiment.
 122
 123  1. `Create a new analysis`_
 124  2. `Load a mussa parameter file`_ (.mupa)
 125  3. `Load an analysis`_
 126
 127 .. _createnew:
 128
 129 Create a new analysis
 130 ~~~~~~~~~~~~~~~~~~~~~
 131
 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.
 135
 136 .. image:: images/define_analysis.png
 137    :alt: Define Analysis
 138    :align: center
 139
 140 Instructions:
 141
 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.
 145
 146  2. Choose a `window size`_. For this demo **choose 30**.
 147
 148  3. Choose a threshold_... for this demo **choose 20**. See the
 149     Threshold_ section for more detailed information.
 150
 151  4. Choose the number of sequences_ you would like. For this demo
 152     **choose 3**.
 153
 154 .. image:: images/define_analysis_step1a.png
 155    :alt: Steps 1-4
 156    :align: center
 157
 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
 163 your sequence.
 164
 165 .. image:: images/define_analysis_step2.png
 166    :alt: Choose sequences
 167    :align: center
 168
 169 Click the **create** button and in a few moments you should see
 170 something similar to the following screen shot.
 171
 172 .. image:: images/demo.png
 173    :alt: Mussagl Demo
 174    :align: center
 175
 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
 179 for details.
 180
 181
 182 Load a mussa parameter file
 183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 184
 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.
 188
 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
 191 open.
 192
 193 .. image:: images/load_mupa_menu.png
 194    :alt: Load Mussa Parameters
 195    :align: center
 196
 197 If you would like to see an example, you can load the
 198 **mck3test.mupa** file in the examples directory that comes with
 199 Mussagl.
 200
 201 .. image:: images/load_mupa_dialog.png
 202    :alt: Load Mussa Parameters Dialog
 203    :align: center
 204
 205
 206 Load an analysis
 207 ~~~~~~~~~~~~~~~~
 208
 209 To load a previously run analysis open Mussagl and select the **File >
 210 Load Analysis** menu option. Select an analysis **directory** and
 211 click open.
 212
 213 .. image:: images/load_analysis_menu.png
 214    :alt: Load Analysis Menu
 215    :align: center
 216
 217
 218 Main Window
 219 -----------
 220
 221 Overview
 222 ~~~~~~~~
 223 .. Screen-shot with numbers showing features.
 224
 225 .. image:: images/window_overview.png
 226    :alt: Mussa Window
 227    :align: center
 228
 229 Legend:
 230
 231  1. `DNA Sequence (Black bars)`_
 232
 233  2. Annotation_
 234
 235  3. Motif_
 236
 237  4. `Conservation tracks`_
 238
 239  5. `Motif Toggle`_
 240
 241  6. `Zoom Factor`_ (Base pairs per pixel)
 242
 243  7. `Dynamic Threshold`_
 244
 245  8. `Sequence Information Bar`_
 246
 247  9. `Sequence Scroll Bar`_
 248
 249
 250 DNA Sequence (black bars)
 251 ~~~~~~~~~~~~~~~~~~~~~~~~~
 252
 253 .. image:: images/sequence_bar.png
 254    :alt: Sequence Bar
 255    :align: center
 256
 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.
 259
 260 FIXME: Should I mention the repeats here?
 261
 262
 263 Annotation
 264 ~~~~~~~~~~
 265
 266 .. figure:: images/annotation.png
 267    :alt: Annotation
 268    :align: center
 269
 270    Annotation shown in green on sequence bar.
 271
 272
 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.
 278
 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.
 282
 283
 284 Motif
 285 ~~~~~
 286
 287 .. figure:: images/motif.png
 288    :alt: Motif
 289    :align: center
 290
 291    Motif shown in light blue on sequence bar.
 292
 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.
 296
 297
 298 Conservation tracks
 299 ~~~~~~~~~~~~~~~~~~~
 300
 301 .. figure:: images/conservation_tracks.png
 302    :alt: Conservation Tracks
 303    :align: center
 304
 305    Conservations tracks shown as red and blue lines between sequence
 306    bars.
 307
 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.
 314
 315
 316 Motif Toggle
 317 ~~~~~~~~~~~~
 318
 319 .. image:: images/motif_toggle.png
 320    :alt: Motif Toggle
 321    :align: center
 322
 323 Toggles motifs on and off. This will not turn on and off annotations.
 324
 325 Note: As of the current build (#200), this feature hasn't been
 326 implemented.
 327
 328
 329 Zoom Factor
 330 ~~~~~~~~~~~
 331
 332 .. image:: images/zoom_factor.png
 333    :alt: Zoom Factor
 334    :align: center
 335
 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).
 340
 341
 342 Dynamic Threshold
 343 ~~~~~~~~~~~~~~~~~
 344
 345 .. image:: images/dynamic_threshold.png
 346    :alt: Dynamic Threshold
 347    :align: center
 348
 349 You can dynamically change the threshold for how strong of match you
 350 consider the conservation to be with one of two options:
 351
 352  1. Number of base pair matches out of window size.
 353
 354  2. Percent base pair conservation.
 355
 356 See the Threshold_ section for more information.
 357
 358
 359 Sequence Information Bar
 360 ~~~~~~~~~~~~~~~~~~~~~~~~
 361
 362 .. image:: images/seq_info_bar.png
 363    :alt: Sequence Information Bar
 364    :align: center
 365
 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
 368 information:
 369
 370  1. Species (If it has been defined)
 371  2. Total Size of Sequence
 372  3. Current base pair position
 373
 374
 375 Sequence Scroll Bar
 376 ~~~~~~~~~~~~~~~~~~~
 377
 378 .. image:: images/scroll_bar.png
 379    :alt: Sequence Scroll Bar
 380    :align: center
 381
 382 The scroll bar allows you to scroll through the sequence which is
 383 useful when you have zoomed in using the `zoom factor`_.
 384
 385
 386 Annotations / Motifs
 387 --------------------
 388
 389 Annotations
 390 ~~~~~~~~~~~
 391
 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).
 397
 398 Motifs
 399 ~~~~~~
 400
 401 Load Motifs from File
 402 *********************
 403
 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.
 407
 408 To load a motif file, select **Load Motif List** item from the
 409 **File** menu and select a motif list file.
 410
 411 .. image:: images/load_motif.png
 412    :alt: Load Motif List
 413    :align: center
 414
 415
 416 Save Motifs to File
 417 *******************
 418
 419 Note: Currently not implemented
 420
 421
 422 Motif Dialog
 423 ************
 424
 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.
 428
 429 .. image:: images/view_edit_motifs.png
 430    :alt: "View > Edit Motifs" Menu
 431    :align: center
 432
 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.
 438
 439 .. image:: images/motif_dialog_start.png
 440    :alt: Motif Dialog
 441    :align: center
 442
 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.
 445
 446 .. image:: images/motif_dialog_enter_motif.png
 447    :alt: Enter Motif
 448    :align: center
 449
 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.
 454
 455 .. image:: images/color_chooser.png
 456    :alt: Color Chooser
 457    :align: center
 458
 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.
 462
 463 Before Motif:
 464
 465 .. image:: images/motif_dialog_bar_before.png
 466    :alt: Sequence bar before motif
 467    :align: center
 468
 469 After Motif:
 470
 471 .. image:: images/motif_dialog_bar_after.png
 472    :alt: Sequence bar after motif
 473    :align: center
 474
 475
 476 View Mussa Alignements
 477 ----------------------
 478
 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
 485 *left mouse button*.
 486
 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.
 491
 492 .. image:: images/select_sequence.png
 493    :alt: Select Sequence
 494    :align: center
 495
 496 All of the lines which were not selected should be washed out as shown
 497 below:
 498
 499 .. image:: images/washed_out.png
 500    :alt: Tracks washed out
 501    :align: center
 502
 503 With a selection made, goto the **View** menu and select **View mussa alignment**.
 504
 505 .. image:: images/view_mussa_alignment.png
 506    :alt: View mussa alignment
 507    :align: center
 508
 509 You should see the alignment at the base-pair level as shown below.
 510
 511 .. image:: images/mussa_alignment.png
 512    :alt: Mussa alignment
 513    :align: center
 514
 515
 516
 517
 518 Saving to an Image
 519 ---------------------------------
 520
 521 FIXME: Need to write this section
 522
 523
 524 Detailed Information
 525 --------------------
 526
 527 Threshold
 528 ~~~~~~~~~
 529
 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.
 541
 542 Window Size
 543 ~~~~~~~~~~~
 544
 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.
 548
 549
 550 Sequences
 551 ~~~~~~~~~
 552
 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.
 557
 558 FIXME: We have learned more about how much sequence and how many to
 559 put in Mussagl, this information should be documented here.
 560
 561
 562 Mussa File Formats
 563 ------------------
 564
 565 .. _param:
 566
 567 Parameter File Format
 568 ~~~~~~~~~~~~~~~~~~~~~
 569
 570 **File Format (.mupa):**
 571
 572 ::
 573
 574   # name of analysis directory and stem for associated files
 575   ANA_NAME <analysis_name>
 576
 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>
 582
 583   # how many sequences are being analyzed
 584   SEQUENCE_NUM <num>
 585
 586   # first sequence info
 587   SEQUENCE <fasta_file_path>
 588   ANNOTATION <annotation_file_path>
 589   SEQ_START <sequence_start>
 590
 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>
 596
 597   # third sequence info
 598   SEQUENCE <fasta_file_path>
 599   # ANNOTATION <annotation_file_path>
 600
 601   # analyzes parameters: command line args -w -t will override these
 602   WINDOW <num>
 603   THRESHOLD <num>
 604
 605 .. csv-table:: Parameter File Options:
 606    :header: "Option Name", "Value", "Default", "Required", "Description"
 607    :widths: 30 30 30 30 60
 608
 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
 614    to analyze"
 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
 619    information."
 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`_"
 624
 625 .. _annot:
 626
 627 Annotation File Format
 628 ~~~~~~~~~~~~~~~~~~~~~~
 629
 630 The first line in the file is the sequence name. Each line there after
 631 is a **space** separated annotation.
 632
 633 New as of build 198:
 634
 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.
 640
 641 Format:
 642
 643 ::
 644
 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>
 650   >Fasta Header
 651   ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
 652   ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
 653   TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
 654   ACGTACGGCAGTACGCGGTCAGA
 655   <start> <stop> <annotation_name> <annotation_type>
 656   ...
 657
 658 Example:
 659
 660 ::
 661
 662   Mouse
 663   251 500 Glorp Glorptype
 664   751 1000 Glorp Glorptype
 665   1251 1500 Glorp Glorptype
 666   >My favorite DNA sequence
 667   GATTACA
 668   1751 2000 Glorp Glorptype
 669
 670
 671 .. _motif_file_format:
 672
 673 Motif File Format
 674 ~~~~~~~~~~~~~~~~~
 675
 676 Format:
 677
 678   <motif> <red> <green> <blue>
 679
 680 Example:
 681
 682   GGCC 0.0 1 1
 683
 684
 685
 686 IUPAC Nucleotide Code
 687 ~~~~~~~~~~~~~~~~~~~~~~
 688
 689 For your convenience, below is a table of the IUPAC Nucleotide Code.
 690
 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.
 694
 695 ======  =================  ===================================
 696 Symbol  Meaning            Origin of designation
 697 ======  =================  ===================================
 698 G       G                  Guanine
 699 A       A                  Adenine
 700 T       T                  Thymine
 701 C       C                  Cytosine
 702 R       G or A             puRine
 703 Y       T or C             pYrimidine
 704 M       A or C             aMino
 705 K       G or T             Keto
 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 ======  =================  ===================================
 714
 715
 716 .. Define links below
 717    ------------------
 718
 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
 724