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 Mussa has the ability to find lab motifs using the `IUPAC Nucleotide
 847 Code`_ for defining a motif. To define a motif, select **Edit > Edit
 848 Motifs** menu item as shown below.
 849
 850 .. image:: images/view_edit_motifs.png
 851    :alt: "View > Edit Motifs" Menu
 852    :align: center
 853
 854 You will see a dialog box appear with a "apply" button in the bottom
 855 right and one rows for defining motifs and the color that will be
 856 displayed on the sequence. When you start adding your first motif, an
 857 additional row will be added. The check box in the first column
 858 defines whether the motif is displayed or not. The second column is
 859 the motif display color. The third column is for the name of your
 860 motif and finally, the fourth column is motif itself.
 861
 862 .. image:: images/motif_dialog_start.png
 863    :alt: Motif Dialog
 864    :align: center
 865
 866 Now let's make a motif **'AT[C or G]CT'**. Using the `IUPAC Nucleotide
 867 Code`_, type in **'ATSCT'** into the motif field and **'My Motif'** for
 868 the name in the name field as shown below.
 869
 870 Notice how a second row appeared when you started to add the first
 871 motif. Every time you add a new motif, a new row will appear allowing
 872 you to add as many motifs as you need.
 873
 874 .. image:: images/motif_dialog_enter_motif.png
 875    :alt: Enter Motif
 876    :align: center
 877
 878 Now choose a color for your motif by clicking on the colored area to
 879 the left of the name field. Remember to choose a color that will show
 880 up well with a black bar as the background. A good tool for picking a
 881 color is the `Colour Contrast Analyser
 882 <http://juicystudio.com/services/colourcontrast.php>`_ by
 883 `juicystudio.com <http://juicystudio.com/>`_.
 884
 885 .. image:: images/color_chooser.png
 886    :alt: Color Chooser
 887    :align: center
 888
 889 Once you have selected the color for your motif, click on the
 890 **'apply'** button. Notice that if Mussa finds matches to your motif
 891 will now show up in the main Mussa window.
 892
 893 Before Motif:
 894
 895 .. image:: images/motif_dialog_bar_before.png
 896    :alt: Sequence bar before motif
 897    :align: center
 898
 899 After Motif:
 900
 901 .. image:: images/motif_dialog_bar_after.png
 902    :alt: Sequence bar after motif
 903    :align: center
 904
 905 To save your motifs with your analysis, see the `save analysis`_
 906 section. To save your motifs to a file, see the `save motifs to file`_
 907 section.
 908
 909
 910 View Mussa Alignments
 911 ---------------------
 912
 913 Mussagl allows you to zoom in on Mussa alignments by selecting the set
 914 of alignment(s) of interest. To do this, move the mouse near the
 915 alignment you are interested in viewing and then **PRESS** and
 916 **HOLD** the **LEFT mouse button** and **drag the mouse** to the other
 917 side of the conservation track so that you see a bounding box
 918 overlaping the alienment(s) of interest and then **let go** of the
 919 *left mouse button*.
 920
 921 In the example below, I started by left-clicking on the area marked by
 922 a red dot (upper left corner of bounding box) and dragging the mouse to
 923 the area marked by a blue dot (lower right corner of the bounding box)
 924 and letting go of the left mouse button.
 925
 926 .. image:: images/select_sequence.png
 927    :alt: Select Sequence
 928    :align: center
 929
 930 All of the lines which were not selected should be washed out as shown
 931 below:
 932
 933 .. image:: images/washed_out.png
 934    :alt: Tracks washed out
 935    :align: center
 936
 937 With a selection made, goto the **View** menu and select **View mussa alignment**.
 938
 939 .. image:: images/view_mussa_alignment.png
 940    :alt: View mussa alignment
 941    :align: center
 942
 943 You should see the alignment at the base-pair level as shown below.
 944
 945 .. image:: images/mussa_alignment.png
 946    :alt: Mussa alignment
 947    :align: center
 948
 949
 950 Sub-analysis
 951 ------------
 952
 953 To run a sub-analysis **highlight** a section of sequence and *right
 954 click* on it and select **Add to subanalysis**. To the same for the
 955 sequences shown in orange in the screenshot below. Note that you **are
 956 NOT limited** to selecting more than one subsequence from the same
 957 sequence.
 958
 959 .. image:: images/subanalysis_select_seqs.png
 960    :alt: Subanalysis sequence selection
 961    :align: center
 962
 963 Once you have added your sequences for subanalysis, choose a `window size`_ and `threshold`_ and click **Ok**.
 964
 965 .. image:: images/subanalysis_dialog.png
 966    :alt: Subanalysis Dialog
 967    :align: center
 968
 969 A new Mussa window will appear with the subanalysis of your sequences
 970 once it's done running. This may take a while if you selected large
 971 chunks of sequence with a loose threshold.
 972
 973 .. image:: images/subanalysis_done.png
 974    :alt: Subalaysis complete
 975    :align: center
 976
 977
 978 Copying sequence to clipboard
 979 -----------------------------
 980
 981 To copy a sequence to the clipboard, highlight a section of sequence,
 982 as shown in the screen shot below, and do one of the following:
 983
 984  * Select **Copy as FASTA** from the **Edit** menu.
 985  * **Right-Click (Left-click + Apple/Command Key on Mac)** on the highlighted sequence and select **Copy as FASTA**.
 986  * Press **Ctrl + C (on PC)** or **Apple/Command Key + C (on Mac)** on the keyboard.
 987
 988 .. image:: images/copy_sequence.png
 989    :alt: Copy sequence
 990    :align: center
 991
 992 Saving to an Image
 993 ---------------------------------
 994
 995  * Updated to build 419.
 996
 997 To save your current mussa view to an image, select **File > Save to
 998 image...** as shown below.
 999
1000 .. image:: images/save_to_image_menu.png
1001    :alt: File > Save to image...
1002    :align: center
1003
1004 You can define the width and the height of the image to save. By
1005 default it will use the same size of your current view. Since the
1006 Mussa view is implemented using vectors, if you choose a larger size
1007 then your current view, Mussa will redraw at the higher resolution
1008 when saving. In other words, you get higher quality images when saving
1009 at a higher resolution.
1010
1011 If you check the "Lock aspect ratio" check box, which I have circled
1012 in red, then when you change one value, say width, the other, height,
1013 will update automatically to keep the same aspect ratio.
1014
1015 .. image:: images/save_to_image_dialog.png
1016    :alt: Save to image dialog
1017    :align: center
1018
1019 Click save and choose a location and filename for your file.
1020
1021 The valid image formats are:
1022
1023   * .png (default if no extension specified.)
1024   * .jpg
1025
1026
1027 Detailed Information
1028 --------------------
1029
1030 Threshold
1031 ~~~~~~~~~
1032
1033 The threshold of an analysis is in minimum number of base pair matches
1034 must be meet to in order to be kept as a match. Note that you can vary
1035 the threshold from within Mussagl. For example, if you choose a
1036 `window size`_ of **30** and a **threshold** of **20** the mussa nway
1037 transitive algorithm will store all matches that are 20 out of 30 bp
1038 matches or better and pass it on to Mussagl. Mussagl will then allow
1039 you to dynamically choose a threshold from 20 to 30 base pairs. A
1040 threshold of 30 bps would only show 30 out of 30 bp matches. A
1041 threshold of 20 bps would show all matches of 20 out of 30 bps or
1042 better. If you would like to see results for matches lower than 20 out
1043 of 30, you will need to rerun the analysis with a lower threshold.
1044
1045 Window Size
1046 ~~~~~~~~~~~
1047
1048 The typical sizes people tend to choose are between 20 and 30. You
1049 will likely need to experiment with this setting depending on your
1050 needs and input sequence.
1051
1052
1053 Sequences
1054 ~~~~~~~~~
1055
1056 Mussa reads in sequences which are formatted in the FASTA_
1057 format. Mussa may take a long time to run (>10 minutes) if the total
1058 bp length near 280Kb. Once mussa has run once, you can reload
1059 previously run analyzes.
1060
1061 FIXME: We have learned more about how much sequence and how many to
1062 put in Mussagl, this information should be documented here.
1063
1064
1065 Mussa File Formats
1066 ------------------
1067
1068 .. _param:
1069
1070 Parameter File Format
1071 ~~~~~~~~~~~~~~~~~~~~~
1072
1073 **File Format (.mupa):**
1074
1075 ::
1076
1077   # name of analysis directory and stem for associated files
1078   ANA_NAME <analysis_name>
1079
1080   # if APPEND vars true, a _wXX and/or _tYY added to analysis name
1081   # where XX = WINDOW and YY = THRESHOLD
1082   # Highly recommeded with use of command line override of WINDOW or THRESHOLD
1083   APPEND_WIN <true/false>
1084   APPEND_THRES <true/false>
1085
1086   # how many sequences are being analyzed
1087   SEQUENCE_NUM <num>
1088
1089   # first sequence info
1090   SEQUENCE <FASTA_file_path>
1091   ANNOTATION <annotation_file_path>
1092   SEQ_START <sequence_start>
1093
1094   # the second sequence info
1095   SEQUENCE <FASTA_file_path>
1096   # ANNOTATION <annotation_file_path>
1097   SEQ_START <sequence_start>
1098   # SEQ_END <sequence_end>
1099
1100   # third sequence info
1101   SEQUENCE <FASTA_file_path>
1102   # ANNOTATION <annotation_file_path>
1103
1104   # analyzes parameters: command line args -w -t will override these
1105   WINDOW <num>
1106   THRESHOLD <num>
1107
1108 .. csv-table:: Parameter File Options:
1109    :header: "Option Name", "Value", "Default", "Required", "Description"
1110    :widths: 30 30 30 30 60
1111
1112    "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
1113    name of directory where analysis will be saved."
1114    "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
1115    "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
1116    "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
1117    to analyze"
1118    "SEQUENCE", "/FASTA/filepath.fa", "N/A", "true", "Must define one
1119    sequence per SEQUENCE_NUM."
1120    "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
1121    annotation file. See `annotation file format`_ section for more
1122    information."
1123    "SEQ_START", "integer", "1", "false", "Optional index into FASTA file"
1124    "SEQ_END", "integer", "1", "false", "Optional index into FASTA file"
1125    "WINDOW", "integer", "N/A", "true", "`Window Size`_"
1126    "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
1127
1128 .. _annot:
1129
1130 Annotation File Format
1131 ~~~~~~~~~~~~~~~~~~~~~~
1132
1133 The first line in the file is the sequence name. Each line there after
1134 is a **space** separated annotation.
1135
1136 New as of build 198:
1137
1138  * The annotation format now supports FASTA sequences embedded in the
1139    annotation file as shown in the format example below. Mussagl will
1140    take this sequence and look for an exact match of this sequence in
1141    your sequences. If a match is found, it will label it with the name
1142    of from the FASTA header.
1143
1144 Format:
1145
1146 ::
1147
1148   <species/sequence_name>
1149   <start> <stop> <annotation_name> <annotation_type>
1150   <start> <stop> <annotation_name> <annotation_type>
1151   <start> <stop> <annotation_name> <annotation_type>
1152   <start> <stop> <annotation_name> <annotation_type>
1153   >FASTA Header
1154   ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
1155   ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
1156   TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
1157   ACGTACGGCAGTACGCGGTCAGA
1158   <start> <stop> <annotation_name> <annotation_type>
1159   ...
1160
1161 Example:
1162
1163 ::
1164
1165   Mouse
1166   251 500 Glorp Glorptype
1167   751 1000 Glorp Glorptype
1168   1251 1500 Glorp Glorptype
1169   >My favorite DNA sequence
1170   GATTACA
1171   1751 2000 Glorp Glorptype
1172
1173
1174 .. _motif_file_format:
1175
1176 Motif File Format
1177 ~~~~~~~~~~~~~~~~~
1178
1179 Format:
1180
1181   <motif> <red> <green> <blue>
1182
1183 Example:
1184
1185   GGCC 0.0 1 1
1186
1187
1188
1189 IUPAC Nucleotide Code
1190 ~~~~~~~~~~~~~~~~~~~~~~
1191
1192 For your convenience, below is a table of the IUPAC Nucleotide Code.
1193
1194 The following table is table 1 from "Nomenclature for Incompletely
1195 Specified Bases in Nucleic Acid Sequences" which can be found at
1196 http://www.chem.qmul.ac.uk/iubmb/misc/naseq.html.
1197
1198 ======  =================  ===================================
1199 Symbol  Meaning            Origin of designation
1200 ======  =================  ===================================
1201 G       G                  Guanine
1202 A       A                  Adenine
1203 T       T                  Thymine
1204 C       C                  Cytosine
1205 R       G or A             puRine
1206 Y       T or C             pYrimidine
1207 M       A or C             aMino
1208 K       G or T             Keto
1209 S       G or C             Strong interaction (3 H bonds)
1210 W       A or T             Weak interaction (2 H bonds)
1211 H       A or C or T        not-G, H follows G in the alphabet
1212 B       G or T or C        not-A, B follows A
1213 V       G or C or A        not-T (not-U), V follows U
1214 D       G or A or T        not-C, D follows C
1215 N       G or A or T or C   aNy
1216 ======  =================  ===================================
1217
1218
1219 .. Define links below
1220    ------------------
1221
1222 .. _GPL: http://www.opensource.org/licenses/gpl-license.php
1223 .. _wiki: http://mussa.caltech.edu
1224 .. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
1225 .. _FASTA: http://en.wikipedia.org/wiki/fasta_format
1226 .. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif