doc/manual/mussagl_manual.rst

   1 ==============
   2 Mussagl Manual
   3 ==============
   4 ---------------
   5 Brandon W. King
   6 ---------------
   7
   8 Last updated: May 18th, 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 Detailed Information
 477 --------------------
 478
 479 Threshold
 480 ~~~~~~~~~
 481
 482 The threshold of an analysis is in minimum number of base pair matches
 483 must be meet to in order to be kept as a match. Note that you can vary
 484 the threshold from within Mussagl. For example, if you choose a
 485 `window size`_ of **30** and a **threshold** of **20** the mussa nway
 486 transitive algorithm will store all matches that are 20 out of 30 bp
 487 matches or better and pass it on to Mussagl. Mussagl will then allow
 488 you to dynamically choose a threshold from 20 to 30 base pairs. A
 489 threshold of 30 bps would only show 30 out of 30 bp matches. A
 490 threshold of 20 bps would show all matches of 20 out of 30 bps or
 491 better. If you would like to see results for matches lower than 20 out
 492 of 30, you will need to rerun the analysis with a lower threshold.
 493
 494 Window Size
 495 ~~~~~~~~~~~
 496
 497 The typical sizes people tend to choose are between 20 and 30. You
 498 will likely need to experiment with this setting depending on your
 499 needs and input sequence.
 500
 501
 502 Sequences
 503 ~~~~~~~~~
 504
 505 Mussa reads in sequences which are formatted in the fasta_
 506 format. Mussa may take a long time to run (>10 minutes) if the total
 507 bp length near 280Kb. Once mussa has run once, you can reload
 508 previously run analyzes.
 509
 510 FIXME: We have learned more about how much sequence and how many to
 511 put in Mussagl, this information should be documented here.
 512
 513
 514 Mussa File Formats
 515 ------------------
 516
 517 .. _param:
 518
 519 Parameter File Format
 520 ~~~~~~~~~~~~~~~~~~~~~
 521
 522 **File Format (.mupa):**
 523
 524 ::
 525
 526   # name of analysis directory and stem for associated files
 527   ANA_NAME <analysis_name>
 528
 529   # if APPEND vars true, a _wXX and/or _tYY added to analysis name
 530   # where XX = WINDOW and YY = THRESHOLD
 531   # Highly recommeded with use of command line override of WINDOW or THRESHOLD
 532   APPEND_WIN <true/false>
 533   APPEND_THRES <true/false>
 534
 535   # how many sequences are being analyzed
 536   SEQUENCE_NUM <num>
 537
 538   # first sequence info
 539   SEQUENCE <fasta_file_path>
 540   ANNOTATION <annotation_file_path>
 541   SEQ_START <sequence_start>
 542
 543   # the second sequence info
 544   SEQUENCE <fasta_file_path>
 545   # ANNOTATION <annotation_file_path>
 546   SEQ_START <sequence_start>
 547   # SEQ_END <sequence_end>
 548
 549   # third sequence info
 550   SEQUENCE <fasta_file_path>
 551   # ANNOTATION <annotation_file_path>
 552
 553   # analyzes parameters: command line args -w -t will override these
 554   WINDOW <num>
 555   THRESHOLD <num>
 556
 557 .. csv-table:: Parameter File Options:
 558    :header: "Option Name", "Value", "Default", "Required", "Description"
 559    :widths: 30 30 30 30 60
 560
 561    "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
 562    name of directory where analysis will be saved."
 563    "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
 564    "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
 565    "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
 566    to analyze"
 567    "SEQUENCE", "/fasta/filepath.fa", "N/A", "true", "Must define one
 568    sequence per SEQUENCE_NUM."
 569    "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
 570    annotation file. See `annotation file format`_ section for more
 571    information."
 572    "SEQ_START", "integer", "1", "false", "Optional index into fasta file"
 573    "SEQ_END", "integer", "1", "false", "Optional index into fasta file"
 574    "WINDOW", "integer", "N/A", "true", "`Window Size`_"
 575    "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
 576
 577 .. _annot:
 578
 579 Annotation File Format
 580 ~~~~~~~~~~~~~~~~~~~~~~
 581
 582 The first line in the file is the sequence name. Each line there after
 583 is a **space** separated annotation.
 584
 585 New as of build 198:
 586
 587  * The annotation format now supports fasta sequences embedded in the
 588    annotation file as shown in the format example below. Mussagl will
 589    take this sequence and look for an exact match of this sequence in
 590    your sequences. If a match is found, it will label it with the name
 591    of from the fasta header.
 592
 593 Format:
 594
 595 ::
 596
 597   <species/sequence_name>
 598   <start> <stop> <annotation_name> <annotation_type>
 599   <start> <stop> <annotation_name> <annotation_type>
 600   <start> <stop> <annotation_name> <annotation_type>
 601   <start> <stop> <annotation_name> <annotation_type>
 602   >Fasta Header
 603   ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
 604   ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
 605   TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
 606   ACGTACGGCAGTACGCGGTCAGA
 607   <start> <stop> <annotation_name> <annotation_type>
 608   ...
 609
 610 Example:
 611
 612 ::
 613
 614   Mouse
 615   251 500 Glorp Glorptype
 616   751 1000 Glorp Glorptype
 617   1251 1500 Glorp Glorptype
 618   >My favorite DNA sequence
 619   GATTACA
 620   1751 2000 Glorp Glorptype
 621
 622
 623 .. _motif_file_format:
 624
 625 Motif File Format
 626 ~~~~~~~~~~~~~~~~~
 627
 628 Format:
 629
 630   <motif> <red> <green> <blue>
 631
 632 Example:
 633
 634   GGCC 0.0 1 1
 635
 636
 637
 638 IUPAC Nucleotide Code
 639 ~~~~~~~~~~~~~~~~~~~~~~
 640
 641 For your convenience, below is a table of the IUPAC Nucleotide Code.
 642
 643 The following table is table 1 from "Nomenclature for Incompletely
 644 Specified Bases in Nucleic Acid Sequences" which can be found at
 645 http://www.chem.qmul.ac.uk/iubmb/misc/naseq.html.
 646
 647 ======  =================  ===================================
 648 Symbol  Meaning            Origin of designation
 649 ======  =================  ===================================
 650 G       G                  Guanine
 651 A       A                  Adenine
 652 T       T                  Thymine
 653 C       C                  Cytosine
 654 R       G or A             puRine
 655 Y       T or C             pYrimidine
 656 M       A or C             aMino
 657 K       G or T             Keto
 658 S       G or C             Strong interaction (3 H bonds)
 659 W       A or T             Weak interaction (2 H bonds)
 660 H       A or C or T        not-G, H follows G in the alphabet
 661 B       G or T or C        not-A, B follows A
 662 V       G or C or A        not-T (not-U), V follows U
 663 D       G or A or T        not-C, D follows C
 664 N       G or A or T or C   aNy
 665 ======  =================  ===================================
 666
 667
 668 .. Define links below
 669    ------------------
 670
 671 .. _GPL: http://www.opensource.org/licenses/gpl-license.php
 672 .. _wiki: http://mussa.caltech.edu
 673 .. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
 674 .. _fasta: http://en.wikipedia.org/wiki/FASTA_format
 675 .. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif
 676