doc/manual/mussagl_manual.rst

   1 ==============
   2 Mussagl Manual
   3 ==============
   4 ---------------
   5 Brandon W. King
   6 ---------------
   7
   8 Last updated: Oct 17th, 2006
   9
  10 Updated to Mussagl build: (In process to 424)
  11
  12
  13 .. Things to add
  14         * New features / change log
  15         * Comment out anything isn't implemented yet.
  16         * (DONE) List of features that will be implemented in the future.
  17         * Look into the homology mapping of UCSC.
  18         * Add toggle to genomes.
  19         * Document why one fast record per region.
  20         * How to deal with the hazards of small utrs vis motif finder. (Add warning)
  21         * Add warning about saving FASTA file.
  22         * Add a general principles section near the top
  23                 * Using comparison algorithm which will pickup all repeats
  24                 * Add info about repeatmasking
  25                 * Checking upstream and downstream genes for make sure you are in the right regions.
  26         * Later on: look into Ensembl
  27         * Look into method of homology instead of blating.
  28         * Mention advantages of using mupa.
  29         * Mention the difference between using arrows and scroll bar
  30         * Document the color for motifs
  31         * Update for Mac user left-click
  32
  33         * Wormbase/Flybase/mirBASE tutorials
  34
  35
  36
  37 .. contents::
  38
  39 Status
  40 ======
  41
  42 Major New Features
  43 ------------------
  44
  45  * Build 381
  46    * Analysis "Save As" feature
  47
  48 Change Log
  49 ----------
  50
  51 .. INSERT CHANGE LOG HERE
  52 .. END INSERT CHANGE LOG
  53
  54 Features to be Implemented
  55 --------------------------
  56
  57  * Motif editor supporting more than 10 motifs
  58    (Status: http://woldlab.caltech.edu/cgi-bin/mussa/ticket/122)
  59  * Save motifs from Mussagl
  60    (Status: http://woldlab.caltech.edu/cgi-bin/mussa/ticket/133)
  61
  62 For an up-to-date list of features to be implemented visit:
  63 http://woldlab.caltech.edu/cgi-bin/mussa/roadmap
  64
  65 Introduction
  66 ============
  67
  68
  69 What is Mussagl?
  70 ----------------
  71
  72 Mussa is an N-way version of the FamilyRelations (which is a part of
  73 the Cartwheel project) 2-way comparative sequence analysis
  74 software. Given DNA sequence from N species, Mussa uses all possible
  75 pairwise comparions to derive an N-wise comparison. For example, given
  76 sequences 1,2,3, and 4, Mussa makes 6 2-way comparisons: 1vs2, 1vs3,
  77 1vs4, 2vs3, 2vs4, and 3vs4. It then compares all the links between
  78 these comparisons, saving those that satisfy a transitivity
  79 requirement. The saved paths are then displayed in an interactive
  80 viewer.
  81
  82 Short History of Mussa
  83 ----------------------
  84
  85 Mussa Python/PMW Prototype
  86 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  87
  88 First Python/PMW based protoype.
  89
  90 Mussa C++/FLTK
  91 ~~~~~~~~~~~~~~
  92
  93 A rewrite for speed purposes using C++ and FLTK GUI toolkit.
  94
  95 Mussagl C++/Qt/OpenGL
  96 ~~~~~~~~~~~~~~~~~~~~~
  97
  98 Refactored version using the more elegant Qt GUI framework and
  99 OpenGL for hardware acceleration for those who have better graphics
 100 cards.
 101
 102 Getting Mussagl
 103 ===============
 104
 105 License
 106 -------
 107
 108 Mussagl has been released open source under the `GPL v2
 109 license`__.
 110
 111 __ GPL_
 112
 113 Platforms
 114 ---------
 115
 116 You have the option of building from source or downloading prebuilt
 117 binaries. Most people will want the prebuilt versions.
 118
 119 Supported Platforms:
 120
 121  * Mac OS X (binary or source)
 122  * Windows XP (binary or source)
 123  * Linux (source)
 124
 125 Download
 126 --------
 127
 128 Mussagl in binary form for OS X and Windows and/or source can be
 129 downloaded from http://mussa.caltech.edu/.
 130
 131 Install
 132 -------
 133
 134 Mac OS X
 135 ~~~~~~~~
 136 Once you have downloaded the .dmg file, double click on it and follow
 137 the install instructions.
 138
 139 FIXME: Mention how to launch the program.
 140
 141
 142 Windows XP
 143 ~~~~~~~~~~
 144 Once you have downloaded the Mussagl installer, double click on the
 145 installer and follow the install instructions.
 146
 147 To start Mussagl, launch the program from Start > Programs > Mussagl >
 148 Mussagl.
 149
 150
 151 Linux
 152 ~~~~~
 153 Currently we do not have a binary installer for Linux. You will have
 154 to build from source. See the 'build from source' section below.
 155
 156
 157 Build from Source
 158 ~~~~~~~~~~~~~~~~~
 159
 160 Instructions for building from source can be found `build page
 161 <http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild>`_ on the
 162 `Mussa wiki`__.
 163
 164 __ wiki_
 165
 166
 167 Obtaining Input Data
 168 ====================
 169
 170 If you already have your data, you can skip ahead to the the `Using
 171 Mussagl`_ section.
 172
 173 Let's say you have a gene of interest called 'SMN1' and you want to
 174 know how the sequence surrounding the gene in multiple species is
 175 conserved. Guess what, that's what we are going to do, retrieve the
 176 DNA sequence for SMN1 and prepare it for using in Mussa.
 177
 178 For more information about SMN1 visit `NCBI's OMIM
 179 <http://www.ncbi.nlm.nih.gov/entrez/dispomim.cgi?id=609682>`_.
 180
 181 The SMN1 data retrieved in this section can be downloaded from the
 182 `Mussa Example Data
 183 <http://woldlab.caltech.edu/cgi-bin/mussa/wiki/ExampleData>`_ page if
 184 you prefer to skip this section of the manual.
 185
 186
 187 UCSC Genome Browser Method
 188 --------------------------
 189
 190 There are many methods of retrieving DNA sequence, but for this
 191 example we will retrieve SMN1 through the UCSC genome browser located
 192 at http://genome.ucsc.edu/.
 193
 194
 195 .. image:: images/ucsc_genome_browser_home.png
 196    :alt: UCSC Genome Browser
 197    :align: center
 198
 199 Step 1 - Find SMN1
 200 ~~~~~~~~~~~~~~~~~~
 201
 202 The first step in finding SMN1 is to use the **Gene Sorter** menu
 203 option which I have highlighted in orange below:
 204
 205 .. image:: images/ucsc_menu_bar_gene_sorter.png
 206    :alt: Gene Sorter Menu Option
 207    :align: center
 208
 209 Gene Sorter page:
 210
 211 .. image:: images/ucsc_gene_sorter.png
 212    :alt: Gene Sorter
 213    :align: center
 214
 215 We will start by looking for SMN1 in the **Human Genome** and **sorting by name similarity**.
 216
 217 .. image:: images/ucsc_gs_sort_name_sim.png
 218    :alt: Gene Sorter - Name Similarity
 219    :align: center
 220
 221 After you have selected **Human Genome** and **sorting by name similarity**, type *SMN1* into the search box.
 222
 223 .. image:: images/ucsc_gs_smn1.png
 224    :alt: Gene
 225    :align: center
 226
 227 Press **Go!** and you should see the following page:
 228
 229 .. image:: images/ucsc_gs_found.png
 230    :alt: Found SMN1
 231    :align: center
 232
 233 Click on **SMN1** and you will be taking the gene expression atlas
 234 page.
 235
 236 .. image:: images/ucsc_gs_genome_position.png
 237    :alt: Gene expression atlas
 238    :align: center
 239
 240 Click on **chr5 70,270,558** found in the **SMN1 row**, **Genome
 241 position column**.
 242
 243 Now we have found the location of SMN1 on human!
 244
 245 .. image:: images/ucsc_gb_smn1_human.png
 246    :alt: Genome Browser - SMN1 (human)
 247    :align: center
 248
 249
 250 Step 2 - Download CDS/UTR sequence for annotations
 251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 252
 253 Since we have found **SMN1**, this would be a convenient time to extract
 254 the DNA sequence for the CDS and UTRs of the gene to use it as an
 255 annotation_ in Mussa.
 256
 257 **Click on SMN1** shown **between** the **two orange arrows** shown
 258 below.
 259
 260 .. image:: images/ucsc_gb_smn1_human_click_smn1.png
 261    :alt: Genome Browser - SMN1 (human) - Orange Arrows
 262    :align: center
 263
 264 You should find yourself at the SMN1 description page.
 265
 266 .. image:: images/ucsc_gb_smn1_description_page.png
 267    :alt: Genome Browser - SMN1 (human) - Description page
 268    :align: center
 269
 270 **Scroll down** until you get to the **Sequence section** and click on
 271 **Genomic (chr5:70,256,524-70,284,592)**.
 272
 273 .. image:: images/ucsc_gb_smn1_human_sequence.png
 274    :alt: Genome Browser - SMN1 (human) - Sequence
 275    :align: center
 276
 277 You should now be at the **Genomic sequence near gene** page:
 278
 279 .. image:: images/ucsc_gb_smn1_human_get_genomic_sequence.png
 280    :alt: Genome Browser - SMN1 (human) - Get genomic sequence
 281    :align: center
 282
 283 Make the following changes (highlighted in orange in the screenshot
 284 below):
 285
 286  1. UNcheck **introns**.
 287     (We only want to annotate CDS and UTRs.)
 288  2. Select **one FASTA record** per **region**.
 289     (Mussa needs each CDS and UTR represented by one FASTA record per CDS/UTR).
 290  3. Select **CDS in upper case, UTR in lower case.**
 291
 292 .. image:: images/ucsc_gb_smn1_human_get_genomic_sequence_diff.png
 293    :alt: Genome Browser - SMN1 (human) - Get genomic sequence setup
 294    :align: center
 295
 296 Now click the **submit** button. You will then see a FASTA file with
 297 many FASTA records representing the CDS and UTRS.
 298
 299 .. image:: images/ucsc_gb_smn1_human_get_genomic_sequence_submit.png
 300    :alt: Genome Browser - SMN1 (human) - CDS/UTR sequence
 301    :align: center
 302
 303 Now you need to save the FASTA records to a **text file**. If you are
 304 using **Firefox** or **Internet Explorer 6+** click on the **File >
 305 Save As** menu option.
 306
 307 **IMPORTANT:** Make sure you select **Text Files** and **NOT**, I
 308 repeat **NOT Webpage Complete** (see screenshot below.)
 309
 310 Type in **smn1_human_annot.txt** for the file name.
 311
 312 .. image:: images/smn1_human_annot.png
 313    :alt: Genome Browser - SMN1 (human) - sequence annotation file
 314    :align: center
 315
 316 **IMPORTANT:** You should open the file with a text editor and make
 317   sure **no HTML** was saved... If you find any HTML markup, delete
 318   the markup and save the file.
 319
 320 Now we are going to **modify the file** you just saved to **add the
 321 name of the species** to the **annotation file**. All you have to do
 322 is **add a new line** at the **top of the file** with the word **'Human'** as
 323 shown below:
 324
 325 .. image:: images/smn1_human_annot_plus_human.png
 326    :alt: Genome Browser - SMN1 (human) - sequence annotation file
 327    :align: center
 328
 329 You can add more annotations to this file if you wish. See the
 330 `annotation file format`_ section for details of the file format. By
 331 including FASTA records in the annotation_ file, Mussa searches your
 332 DNA sequence for an exact match of the sequence in the annotation_
 333 file. If found, it will be marked as an annotation_ within Mussa.
 334
 335
 336 Step 3 - Download gene and upstream/downstream sequence
 337 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 338
 339 Use the back button in your web browser to get back the **genome
 340 browser view** of **SMN1** as shown below.
 341
 342 .. image:: images/ucsc_gb_smn1_human.png
 343    :alt: Genome Browser - SMN1 (human)
 344    :align: center
 345
 346 There are two options for getting additional sequence around your
 347 gene. The more complex way is to zoom out so that you have the
 348 sequence you want being shown in the genome browser and then follow
 349 the directions for the following method.
 350
 351 The second option, which we will choose, is to leave the genome
 352 browser zoomed exactly at the location of SMN1 and click on the
 353 **DNA** option on the menu bar (shown with orange arrows in the
 354 screenshot below.)
 355
 356 .. image:: images/ucsc_gb_smn1_human_dna_option.png
 357    :alt: Genome Browser - SMN1 (human) - DNA Option
 358    :align: center
 359
 360 Now in the **get dna in window** page, let's add an arbitrary amount of
 361 extra sequence on to each end of the gene, let's say 5000 base pairs.
 362
 363 .. image:: images/ucsc_gb_smn1_human_get_dna.png
 364    :alt: Genome Browser - SMN1 (human) - Get DNA
 365    :align: center
 366
 367 Click the **get DNA** button.
 368
 369 .. image:: images/ucsc_gb_smn1_human_dna.png
 370    :alt: Genome Browser - SMN1 (human) - DNA
 371    :align: center
 372
 373 Save the DNA sequence to a text file called 'smn1_human_dna.fa' as we
 374 did in step 2 with the annotation file.
 375
 376 **IMPORTANT:** Make sure the file is saved as a text file and not an
 377 HTML file. Open the file with a text editor and remove any HTML markup
 378 you find.
 379
 380
 381 Step 4 - Same/similar/related gene other species.
 382 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 383
 384 What good is a multiple sequence alignment viewer without multiple
 385 sequences? Let'S find a similar gene in a few more species.
 386
 387 Use the back button on your web browser until you get the **genome
 388 browser view** of **SMN1** as shown below.
 389
 390 .. image:: images/ucsc_genome_browser_home.png
 391    :alt: UCSC Genome Browser
 392    :align: center
 393
 394 **Click on SMN1** shown **between** the **two orange arrows** shown
 395 below.
 396
 397 .. image:: images/ucsc_gb_smn1_human_click_smn1.png
 398    :alt: Genome Browser - SMN1 (human) - Orange Arrows
 399    :align: center
 400
 401 You should find yourself at the SMN1 description page.
 402
 403 .. image:: images/ucsc_gb_smn1_description_page.png
 404    :alt: Genome Browser - SMN1 (human) - Description page
 405    :align: center
 406
 407 **Scroll down** until you get to the **Sequence section** and click on
 408 **Protein (262 aa)**.
 409
 410 .. image:: images/ucsc_gb_smn1_human_sequence.png
 411    :alt: Genome Browser - SMN1 (human) - Sequence
 412    :align: center
 413
 414 Copy the SMN1 protein seqeunce by highlighting it and selecting **Edit
 415 > Copy** option from the menu.
 416
 417 .. image:: images/smn1_human_protein.png
 418    :alt: Genome Browser - SMN1 (human) - Protein
 419    :align: center
 420
 421 Press the back button on the web browser once and then scroll to the
 422 top of the page and click on the **BLAT** option on the menu bar
 423 (shown below with orange arrows).
 424
 425 .. image:: images/ucsc_gb_smn1_human_blat.png
 426    :alt: Genome Browser - SMN1 (human) - Blat
 427    :align: center
 428
 429 **Paste** in the **protein sequence** and **change** the **genome** to
 430 **mouse** as shown below and then click **submit**.
 431
 432 .. image:: images/ucsc_gb_smn1_human_blat_paste.png
 433    :alt: Genome Browser - SMN1 (human) - Blat paste protein
 434    :align: center
 435
 436 Notice that we have two hits, one of which looks pretty good at 89.9%
 437 match.
 438
 439 .. image:: images/ucsc_gb_smn1_human_blat_hits.png
 440    :alt: Genome Browser - SMN1 (human) - Blat hits
 441    :align: center
 442
 443 **Click** on the **brower** link next to the 89.9% match. Notice in
 444 the genome browser (shown below) that there is an annotated gene
 445 called SMN1 for mouse which matches the line called **your sequence
 446 from blat search**. This means we are fairly confidant we found the
 447 right location in the mouse genome.
 448
 449 .. image:: images/ucsc_gb_smn1_human_blat_to_browser.png
 450    :alt: Genome Browser - SMN1 (human) - Blat to browser
 451    :align: center
 452
 453 Follow steps 1 through 3 for mouse and then repeat step 4 with the
 454 human protein sequence to find **SMN1** in the following species (if
 455 you find a match):
 456
 457  1. Rat
 458  2. Rabbit
 459  3. Dog
 460  4. Armadillo
 461  5. Elephant
 462  6. Opposum
 463  7. x_tropicalis
 464
 465 Make sure to save the extended DNA sequence and annotation file for
 466 each one.
 467
 468 Using Mussagl
 469 =============
 470
 471
 472 Launch Mussagl
 473 --------------
 474 Launch Mussagl... It should look similar to the screen shot below.
 475
 476 .. image:: images/opened.png
 477    :alt: Launch Mussa
 478    :align: center
 479
 480
 481
 482 Create/Load Analysis
 483 ----------------------
 484
 485 Currently there are three ways to load a Mussa experiment.
 486
 487  1. `Create a new analysis`_
 488  2. `Load a mussa parameter file`_ (.mupa)
 489  3. `Load an analysis`_
 490
 491 .. _createnew:
 492
 493 Create a new analysis
 494 ~~~~~~~~~~~~~~~~~~~~~
 495
 496 To create a new analysis select 'Define analysis' from the 'File'
 497 menu. You should see a dialog box similar to the one below. For this
 498 demo we will use the example sequences that come with Mussagl.
 499
 500 .. image:: images/define_analysis.png
 501    :alt: Define Analysis
 502    :align: center
 503
 504 Instructions:
 505
 506  1. **Give the experiment a name**, for this demo, we'll use
 507     'demo_w30_t20'. Mussa will create a folder with this name to store
 508     the analysis files in once it has been run.
 509
 510  2. Choose a threshold_... for this demo **choose 20**. See the
 511     Threshold_ section for more detailed information.
 512
 513  3. Choose a `window size`_. For this demo **choose 30**.
 514
 515
 516  4. Choose the number of sequences_ you would like. For this demo
 517     **choose 3**.
 518
 519 .. image:: images/define_analysis_step1a.png
 520    :alt: Steps 1-4
 521    :align: center
 522
 523 First enter the species name of "Human" in the first "Species" text
 524 box. Now click on the 'Browse' button next to the sequence input box
 525 and then select /examples/seq/human_mck_pro.fa file. Do the same in
 526 the next two sequence input boxes selecting mouse_mck_pro.fa and
 527 rabbit_mck_pro.fa as shown below. Make sure to give them a species
 528 name as well. Note that you can create annotation files using the
 529 mussa `Annotation File Format`_ to add annotations to your sequence.
 530
 531 .. image:: images/define_analysis_step2.png
 532    :alt: Choose sequences
 533    :align: center
 534
 535 Click the **create** button and in a few moments you should see
 536 something similar to the following screen shot.
 537
 538 .. image:: images/demo.png
 539    :alt: Mussagl Demo
 540    :align: center
 541
 542 By default your analysis is NOT saved. If you try to close an analysis
 543 without saving, you will be prompted with a dialog box asking you if
 544 you would like to save your analysis. The `Saving`_ section for
 545 details on saving your analysis. When saving, choose directory and
 546 give the analysis the name **demo_w30_t20**. If you close and reopen
 547 Mussagl, you will then be able to load the saved analysis. See `Load
 548 an analysis`_ section below for details.
 549
 550
 551 Load a mussa parameter file
 552 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 553
 554 If you prefer, you can define your Mussa analysis using the Mussa
 555 parameter file. See the `Parameter File Format`_ section for details
 556 on creating a .mupa file.
 557
 558 Once you have a .mupa file created, load Mussagl and select the **File >
 559 Create Analysis from File** menu option. Select the .mupa file and click
 560 open.
 561
 562 .. image:: images/load_mupa_menu.png
 563    :alt: Load Mussa Parameters
 564    :align: center
 565
 566 If you would like to see an example, you can load the
 567 **mck3test.mupa** file in the examples directory that comes with
 568 Mussagl.
 569
 570 .. image:: images/load_mupa_dialog.png
 571    :alt: Load Mussa Parameters Dialog
 572    :align: center
 573
 574
 575 Load an analysis
 576 ~~~~~~~~~~~~~~~~
 577
 578 To load a previously run analysis open Mussagl and select the **File >
 579 Open Existing Analysis** menu option. Select an analysis **directory** and
 580 click open.
 581
 582 .. image:: images/load_analysis_menu.png
 583    :alt: Load Analysis Menu
 584    :align: center
 585
 586
 587 Main Window
 588 -----------
 589
 590 Overview
 591 ~~~~~~~~
 592 .. Screen-shot with numbers showing features.
 593
 594 .. image:: images/window_overview.png
 595    :alt: Mussa Window
 596    :align: center
 597
 598 Legend:
 599
 600  1. `DNA Sequence (Black bars)`_
 601
 602  2. Annotation_
 603
 604  3. Motif_
 605
 606  4. `Red conservation tracks`_
 607
 608  5. `Blue conservation tracks`_
 609
 610  6. `Zoom Factor`_ (Base pairs per pixel)
 611
 612  7. `Dynamic Threshold`_
 613
 614  8. `Sequence Information Bar`_
 615
 616  9. `Sequence Scroll Bar`_
 617
 618
 619 DNA Sequence (black bars)
 620 ~~~~~~~~~~~~~~~~~~~~~~~~~
 621
 622 .. image:: images/sequence_bar.png
 623    :alt: Sequence Bar
 624    :align: center
 625
 626 Each of the black bars represents one of the loaded sequences, in this
 627 case the sequence around the gene 'MCK' in human, mouse, and rabbit.
 628
 629
 630 Annotation
 631 ~~~~~~~~~~
 632
 633 .. figure:: images/annotation.png
 634    :alt: Annotation
 635    :align: center
 636
 637    Annotation shown in green on sequence bar.
 638
 639
 640 Annotations can be included on any of the sequences using the `Load a
 641 mussa parameter file`_ or `Create a new analysis`_ method of loading
 642 your sequences. You can define annotations by location or using an
 643 exact sub-sequence or a FASTA sequence of the section of DNA you wish
 644 to annotate. See the `Annotation File Format`_ section for details.
 645
 646
 647 Motif
 648 ~~~~~
 649
 650 .. figure:: images/motif.png
 651    :alt: Motif
 652    :align: center
 653
 654    Motif shown in light blue on sequence bar.
 655
 656 The only real difference between an annotation and motif in Mussagl is
 657 that you can define motifs and choose a color from within the GUI. See
 658 the `Motifs`_ section for more information.
 659
 660
 661 Red conservation tracks
 662 ~~~~~~~~~~~~~~~~~~~~~~~
 663
 664 .. figure:: images/conservation_tracks.png
 665    :alt: Conservation Tracks
 666    :align: center
 667
 668    Conservations tracks shown as red and blue lines between sequence
 669    bars.
 670
 671 The **red lines** between the sequence bars represent conservation
 672 between the sequences (i.e. not reverse complement matches)
 673
 674 The amount of sequence conservation shown will depend on how much your
 675 sequences are related and the `dynamic threshold`_ you are using.
 676
 677
 678 Blue conservation tracks
 679 ~~~~~~~~~~~~~~~~~~~~~~~~
 680
 681 .. figure:: images/conservation_tracks.png
 682    :alt: Conservation Tracks
 683    :align: center
 684
 685    Conservations tracks shown as red and blue lines between sequence
 686    bars.
 687
 688 **Blue lines** represent **reverse complement** conservation relative
 689 to the sequence attached to the top of the blue line.
 690
 691 The amount of sequence conservation shown will depend on how much your
 692 sequences are related and the `dynamic threshold`_ you are using.
 693
 694
 695 Zoom Factor
 696 ~~~~~~~~~~~
 697
 698 .. image:: images/zoom_factor.png
 699    :alt: Zoom Factor
 700    :align: center
 701
 702 The zoom factor represents the number of base pairs represented per
 703 pixel. When you zoom in far enough the sequence will switch from
 704 seeing a black bar, representing the sequence, to the actual sequence
 705 (well, ASCII representation of sequence).
 706
 707
 708 Dynamic Threshold
 709 ~~~~~~~~~~~~~~~~~
 710
 711 .. image:: images/dynamic_threshold.png
 712    :alt: Dynamic Threshold
 713    :align: center
 714
 715 You can dynamically change the threshold for how strong a match you
 716 consider the conservation to be by changing the value in the dynamic
 717 threshold box.
 718
 719 The value you enter is the minimum number of base pairs that have to
 720 be matched in order to be considered conserved. The second number that
 721 you can't change is the `window size`_ you used when creating the
 722 experiment. The last number is the percent match.
 723
 724 See the Threshold_ section for more information.
 725
 726
 727 Sequence Information Bar
 728 ~~~~~~~~~~~~~~~~~~~~~~~~
 729
 730 .. image:: images/seq_info_bar.png
 731    :alt: Sequence Information Bar
 732    :align: center
 733
 734 The sequence information bars can be found to the left and right sides
 735 of Mussagl. Next to each sequence you will find the following
 736 information:
 737
 738  1. Species (If it has been defined)
 739  2. Total Size of Sequence
 740  3. Current base pair position
 741
 742 Note that you can **update the species** text box. Make sure to **save your
 743 experiment** after making this change by selecting **File > Save
 744 Analysis** from the menu.
 745
 746 Sequence Scroll Bar
 747 ~~~~~~~~~~~~~~~~~~~
 748
 749 .. image:: images/scroll_bar.png
 750    :alt: Sequence Scroll Bar
 751    :align: center
 752
 753 The scroll bar allows you to scroll through the sequence which is
 754 useful when you have zoomed in using the `zoom factor`_.
 755
 756
 757 Saving
 758 ------
 759
 760 Save on Close
 761 ~~~~~~~~~~~~~
 762
 763 FIXME: Write this.
 764
 765 Save Analysis
 766 ~~~~~~~~~~~~~
 767
 768 After making changes, such as updating species names or adding/editing
 769 motifs, you can save these changes by selecting the **File > Save
 770 analysis** menu option or pressing **CTRL + S** (PC) or
 771 **Apple/Command Key + S** (on Mac).
 772
 773 .. image:: images/save_analysis.png
 774    :alt: Save analysis
 775    :align: center
 776
 777 Save Analysis As
 778 ~~~~~~~~~~~~~~~~
 779
 780 To save a copy of your analysis to a new location, select the **File >
 781 Save analysis as** menu option and choose a new location and name for
 782 your analysis.
 783
 784 .. image:: images/save_analysis_as.png
 785    :alt: Save analysis
 786    :align: center
 787
 788 Save Motif List
 789 ~~~~~~~~~~~~~~~
 790
 791 See `Save Motifs to File`_ in the `Motifs`_ section.
 792
 793
 794 Annotations / Motifs
 795 --------------------
 796
 797 Annotations
 798 ~~~~~~~~~~~
 799
 800 Currently annotations can be added to a sequence using the mussa
 801 `annotation file format`_ and can be loaded by selecting the
 802 annotation file when defining a new analysis (see `Create a new
 803 analysis`_ section) or by defining a .mupa file pointing to your
 804 annotation file (see `Load a mussa parameter file`_ section).
 805
 806 Motifs
 807 ~~~~~~
 808
 809 Load Motifs from File
 810 *********************
 811
 812 It is possible to load motifs from a file which was saved from a
 813 previous run or by defining your own motif file. See the `Motif File
 814 Format`_ section for details.
 815
 816 NOTE: Valid motif list file extensions are:
 817
 818   * .mtl
 819   * .txt
 820
 821 To load a motif file, select **Load Motif List** item from the
 822 **File** menu and select a motif list file.
 823
 824 .. image:: images/load_motif.png
 825    :alt: Load Motif List
 826    :align: center
 827
 828
 829 Save Motifs to File
 830 *******************
 831
 832 Motifs from the `Motif Dialog`_ can be saved to file for use with
 833 other analyses. If you just want your motifs to be saved with your
 834 analysis, see the `save analysis`_ section for details.
 835
 836 To save a motif list, select **File > Save Motifs** menu option.
 837
 838 .. image:: images/save_motifs.png
 839    :alt: Save Motifs
 840    :align: center
 841
 842
 843 Motif Dialog
 844 ************
 845
 846 **New Features:**
 847
 848 Build 276
 849  * Allow for toggling individual motifs on and off.
 850
 851 Build 269
 852  * Field added for naming motifs.
 853
 854 Mussa has the ability to find lab motifs using the `IUPAC Nucleotide
 855 Code`_ for defining a motif. To define a motif, select **Edit > Edit
 856 Motifs** menu item as shown below.
 857
 858 .. image:: images/view_edit_motifs.png
 859    :alt: "View > Edit Motifs" Menu
 860    :align: center
 861
 862 You will see a dialog box appear with a "set motifs" button and 10
 863 rows for defining motifs and the color that will be displayed on the
 864 sequence. By default all 10 motifs start off as with white as the
 865 color. In the image below, I changed the color from white to blue to
 866 make it easier to see. The first text box is for the motif and the
 867 second box is for the name of the motif. The check box defines whether
 868 the motif is displayed or not.
 869
 870 .. image:: images/motif_dialog_start.png
 871    :alt: Motif Dialog
 872    :align: center
 873
 874 Now let's make a motif **'AT[C or G]CT'**. Using the `IUPAC Nucleotide
 875 Code`_, type in **'ATSCT'** into the first box and 'My Motif' for the
 876 name in the second box as shown below.
 877
 878 .. image:: images/motif_dialog_enter_motif.png
 879    :alt: Enter Motif
 880    :align: center
 881
 882 Now choose a color for your motif by clicking on the colored area to
 883 the left of the motif. In the image above, you would click on the blue
 884 square, but by default the squares will be white. Remember to choose a
 885 color that will show up well with a black bar as the background.
 886
 887 .. image:: images/color_chooser.png
 888    :alt: Color Chooser
 889    :align: center
 890
 891 Once you have selected the color for your motif, click on the 'set
 892 motifs' button. Notice that if Mussa finds matches to your motif will
 893 now show up in the main Mussagl window.
 894
 895 Before Motif:
 896
 897 .. image:: images/motif_dialog_bar_before.png
 898    :alt: Sequence bar before motif
 899    :align: center
 900
 901 After Motif:
 902
 903 .. image:: images/motif_dialog_bar_after.png
 904    :alt: Sequence bar after motif
 905    :align: center
 906
 907
 908 View Mussa Alignments
 909 ---------------------
 910
 911 Mussagl allows you to zoom in on Mussa alignments by selecting the set
 912 of alignment(s) of interest. To do this, move the mouse near the
 913 alignment you are interested in viewing and then **PRESS** and
 914 **HOLD** the **LEFT mouse button** and **drag the mouse** to the other
 915 side of the conservation track so that you see a bounding box
 916 overlaping the alienment(s) of interest and then **let go** of the
 917 *left mouse button*.
 918
 919 In the example below, I started by left-clicking on the area marked by
 920 a red dot (upper left corner of bounding box) and dragging the mouse to
 921 the area marked by a blue dot (lower right corner of the bounding box)
 922 and letting go of the left mouse button.
 923
 924 .. image:: images/select_sequence.png
 925    :alt: Select Sequence
 926    :align: center
 927
 928 All of the lines which were not selected should be washed out as shown
 929 below:
 930
 931 .. image:: images/washed_out.png
 932    :alt: Tracks washed out
 933    :align: center
 934
 935 With a selection made, goto the **View** menu and select **View mussa alignment**.
 936
 937 .. image:: images/view_mussa_alignment.png
 938    :alt: View mussa alignment
 939    :align: center
 940
 941 You should see the alignment at the base-pair level as shown below.
 942
 943 .. image:: images/mussa_alignment.png
 944    :alt: Mussa alignment
 945    :align: center
 946
 947
 948 Sub-analysis
 949 ------------
 950
 951 To run a sub-analysis **highlight** a section of sequence and *right
 952 click* on it and select **Add to subanalysis**. To the same for the
 953 sequences shown in orange in the screenshot below. Note that you **are
 954 NOT limited** to selecting more than one subsequence from the same
 955 sequence.
 956
 957 .. image:: images/subanalysis_select_seqs.png
 958    :alt: Subanalysis sequence selection
 959    :align: center
 960
 961 Once you have added your sequences for subanalysis, choose a `window size`_ and `threshold`_ and click **Ok**.
 962
 963 .. image:: images/subanalysis_dialog.png
 964    :alt: Subanalysis Dialog
 965    :align: center
 966
 967 A new Mussa window will appear with the subanalysis of your sequences
 968 once it's done running. This may take a while if you selected large
 969 chunks of sequence with a loose threshold.
 970
 971 .. image:: images/subanalysis_done.png
 972    :alt: Subalaysis complete
 973    :align: center
 974
 975
 976 Copying sequence to clipboard
 977 -----------------------------
 978
 979 To copy a sequence to the clipboard, highlight a section of sequence,
 980 as shown in the screen shot below, and do one of the following:
 981
 982  * Select **Copy as FASTA** from the **Edit** menu.
 983  * **Right-Click (Left-click + Apple/Command Key on Mac)** on the highlighted sequence and select **Copy as FASTA**.
 984  * Press **Ctrl + C (on PC)** or **Apple/Command Key + C (on Mac)** on the keyboard.
 985
 986 .. image:: images/copy_sequence.png
 987    :alt: Copy sequence
 988    :align: center
 989
 990 Saving to an Image
 991 ---------------------------------
 992
 993  * Updated to build 419.
 994
 995 To save your current mussa view to an image, select **File > Save to
 996 image...** as shown below.
 997
 998 .. image:: images/save_to_image_menu.png
 999    :alt: File > Save to image...
1000    :align: center
1001
1002 You can define the width and the height of the image to save. By
1003 default it will use the same size of your current view. Since the
1004 Mussa view is implemented using vectors, if you choose a larger size
1005 then your current view, Mussa will redraw at the higher resolution
1006 when saving. In other words, you get higher quality images when saving
1007 at a higher resolution.
1008
1009 If you check the "Lock aspect ratio" check box, which I have circled
1010 in red, then when you change one value, say width, the other, height,
1011 will update automatically to keep the same aspect ratio.
1012
1013 .. image:: images/save_to_image_dialog.png
1014    :alt: Save to image dialog
1015    :align: center
1016
1017 Click save and choose a location and filename for your file.
1018
1019 The valid image formats are:
1020
1021   * .png (default if no extension specified.)
1022   * .jpg
1023
1024
1025 Detailed Information
1026 --------------------
1027
1028 Threshold
1029 ~~~~~~~~~
1030
1031 The threshold of an analysis is in minimum number of base pair matches
1032 must be meet to in order to be kept as a match. Note that you can vary
1033 the threshold from within Mussagl. For example, if you choose a
1034 `window size`_ of **30** and a **threshold** of **20** the mussa nway
1035 transitive algorithm will store all matches that are 20 out of 30 bp
1036 matches or better and pass it on to Mussagl. Mussagl will then allow
1037 you to dynamically choose a threshold from 20 to 30 base pairs. A
1038 threshold of 30 bps would only show 30 out of 30 bp matches. A
1039 threshold of 20 bps would show all matches of 20 out of 30 bps or
1040 better. If you would like to see results for matches lower than 20 out
1041 of 30, you will need to rerun the analysis with a lower threshold.
1042
1043 Window Size
1044 ~~~~~~~~~~~
1045
1046 The typical sizes people tend to choose are between 20 and 30. You
1047 will likely need to experiment with this setting depending on your
1048 needs and input sequence.
1049
1050
1051 Sequences
1052 ~~~~~~~~~
1053
1054 Mussa reads in sequences which are formatted in the FASTA_
1055 format. Mussa may take a long time to run (>10 minutes) if the total
1056 bp length near 280Kb. Once mussa has run once, you can reload
1057 previously run analyzes.
1058
1059 FIXME: We have learned more about how much sequence and how many to
1060 put in Mussagl, this information should be documented here.
1061
1062
1063 Mussa File Formats
1064 ------------------
1065
1066 .. _param:
1067
1068 Parameter File Format
1069 ~~~~~~~~~~~~~~~~~~~~~
1070
1071 **File Format (.mupa):**
1072
1073 ::
1074
1075   # name of analysis directory and stem for associated files
1076   ANA_NAME <analysis_name>
1077
1078   # if APPEND vars true, a _wXX and/or _tYY added to analysis name
1079   # where XX = WINDOW and YY = THRESHOLD
1080   # Highly recommeded with use of command line override of WINDOW or THRESHOLD
1081   APPEND_WIN <true/false>
1082   APPEND_THRES <true/false>
1083
1084   # how many sequences are being analyzed
1085   SEQUENCE_NUM <num>
1086
1087   # first sequence info
1088   SEQUENCE <FASTA_file_path>
1089   ANNOTATION <annotation_file_path>
1090   SEQ_START <sequence_start>
1091
1092   # the second sequence info
1093   SEQUENCE <FASTA_file_path>
1094   # ANNOTATION <annotation_file_path>
1095   SEQ_START <sequence_start>
1096   # SEQ_END <sequence_end>
1097
1098   # third sequence info
1099   SEQUENCE <FASTA_file_path>
1100   # ANNOTATION <annotation_file_path>
1101
1102   # analyzes parameters: command line args -w -t will override these
1103   WINDOW <num>
1104   THRESHOLD <num>
1105
1106 .. csv-table:: Parameter File Options:
1107    :header: "Option Name", "Value", "Default", "Required", "Description"
1108    :widths: 30 30 30 30 60
1109
1110    "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
1111    name of directory where analysis will be saved."
1112    "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
1113    "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
1114    "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
1115    to analyze"
1116    "SEQUENCE", "/FASTA/filepath.fa", "N/A", "true", "Must define one
1117    sequence per SEQUENCE_NUM."
1118    "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
1119    annotation file. See `annotation file format`_ section for more
1120    information."
1121    "SEQ_START", "integer", "1", "false", "Optional index into FASTA file"
1122    "SEQ_END", "integer", "1", "false", "Optional index into FASTA file"
1123    "WINDOW", "integer", "N/A", "true", "`Window Size`_"
1124    "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
1125
1126 .. _annot:
1127
1128 Annotation File Format
1129 ~~~~~~~~~~~~~~~~~~~~~~
1130
1131 The first line in the file is the sequence name. Each line there after
1132 is a **space** separated annotation.
1133
1134 New as of build 198:
1135
1136  * The annotation format now supports FASTA sequences embedded in the
1137    annotation file as shown in the format example below. Mussagl will
1138    take this sequence and look for an exact match of this sequence in
1139    your sequences. If a match is found, it will label it with the name
1140    of from the FASTA header.
1141
1142 Format:
1143
1144 ::
1145
1146   <species/sequence_name>
1147   <start> <stop> <annotation_name> <annotation_type>
1148   <start> <stop> <annotation_name> <annotation_type>
1149   <start> <stop> <annotation_name> <annotation_type>
1150   <start> <stop> <annotation_name> <annotation_type>
1151   >FASTA Header
1152   ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
1153   ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
1154   TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
1155   ACGTACGGCAGTACGCGGTCAGA
1156   <start> <stop> <annotation_name> <annotation_type>
1157   ...
1158
1159 Example:
1160
1161 ::
1162
1163   Mouse
1164   251 500 Glorp Glorptype
1165   751 1000 Glorp Glorptype
1166   1251 1500 Glorp Glorptype
1167   >My favorite DNA sequence
1168   GATTACA
1169   1751 2000 Glorp Glorptype
1170
1171
1172 .. _motif_file_format:
1173
1174 Motif File Format
1175 ~~~~~~~~~~~~~~~~~
1176
1177 Format:
1178
1179   <motif> <red> <green> <blue>
1180
1181 Example:
1182
1183   GGCC 0.0 1 1
1184
1185
1186
1187 IUPAC Nucleotide Code
1188 ~~~~~~~~~~~~~~~~~~~~~~
1189
1190 For your convenience, below is a table of the IUPAC Nucleotide Code.
1191
1192 The following table is table 1 from "Nomenclature for Incompletely
1193 Specified Bases in Nucleic Acid Sequences" which can be found at
1194 http://www.chem.qmul.ac.uk/iubmb/misc/naseq.html.
1195
1196 ======  =================  ===================================
1197 Symbol  Meaning            Origin of designation
1198 ======  =================  ===================================
1199 G       G                  Guanine
1200 A       A                  Adenine
1201 T       T                  Thymine
1202 C       C                  Cytosine
1203 R       G or A             puRine
1204 Y       T or C             pYrimidine
1205 M       A or C             aMino
1206 K       G or T             Keto
1207 S       G or C             Strong interaction (3 H bonds)
1208 W       A or T             Weak interaction (2 H bonds)
1209 H       A or C or T        not-G, H follows G in the alphabet
1210 B       G or T or C        not-A, B follows A
1211 V       G or C or A        not-T (not-U), V follows U
1212 D       G or A or T        not-C, D follows C
1213 N       G or A or T or C   aNy
1214 ======  =================  ===================================
1215
1216
1217 .. Define links below
1218    ------------------
1219
1220 .. _GPL: http://www.opensource.org/licenses/gpl-license.php
1221 .. _wiki: http://mussa.caltech.edu
1222 .. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
1223 .. _FASTA: http://en.wikipedia.org/wiki/fasta_format
1224 .. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif