doc/manual/mussagl_manual.rst

   1 ==============
   2 Mussagl Manual
   3 ==============
   4 ------------------
   5 By 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 can be downloaded from http://mussa.caltech.edu/.
  66
  67 Install
  68 -------
  69
  70 Mac OS X
  71 ~~~~~~~~
  72 Once you have downloaded the .dmg file, dubble click on it and follow
  73 the install instructions.
  74
  75 FIXME: Mention how to launch the program.
  76
  77
  78 Windows XP
  79 ~~~~~~~~~~
  80 Once you have downloaded the Mussagl installer, double click on the
  81 installer and follow the install instructions.
  82
  83 To start mussagl, launch the program from Start > Programs > Mussagl >
  84 Mussgl.
  85
  86
  87 Linux
  88 ~~~~~
  89 Currently we do not have a binary installer for Linux. You will have
  90 to build from source. See the 'build from source' section below.
  91
  92
  93 Build from Source
  94 ~~~~~~~~~~~~~~~~~
  95
  96 Instructions for building from source can be found `build page
  97 <http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild>`_ on the
  98 `Mussa wiki`__.
  99
 100 __ wiki_
 101
 102
 103 Using Mussagl
 104 =============
 105
 106
 107 Launch Mussagl
 108 --------------
 109 Launch Mussagl... It should look similar to the screen shot below.
 110
 111 .. image:: images/opened.png
 112    :alt: Launch Mussa
 113    :align: center
 114
 115
 116
 117 Create/Load Analysis
 118 ----------------------
 119
 120 Currently there are three ways to load a mussa experiment.
 121
 122  1. `Create a new analysis`_
 123  2. `Load a mussa parameter file`_ (.mupa)
 124  3. `Load an analysis`_
 125
 126 .. _createnew:
 127
 128 Create a new analysis
 129 ~~~~~~~~~~~~~~~~~~~~~
 130
 131 To create a new analysis select 'Define analysis' from the 'File'
 132 menu. You should see a dialog box similar to the one below. For this
 133 demo we will use the example sequences that come with Mussagl.
 134
 135 .. image:: images/define_analysis.png
 136    :alt: Define Analysis
 137    :align: center
 138
 139 Instructions:
 140
 141  1. **Give the experiement a name**, for this demo, we'll use
 142     'demo_w30_t20'. Mussa will create a folder with this name to store
 143     the analysis files in once it has been run.
 144
 145  2. Choose a `window size`_. For this demo **choose 30**.
 146
 147  3. Choose a threshold_... for this demo **choose 20**. See the
 148     Threshold_ section for more detailed information.
 149
 150  4. Choose the number of sequences_ you would like. For this demo
 151     **choose 3**.
 152
 153 .. image:: images/define_analysis_step1a.png
 154    :alt: Steps 1-4
 155    :align: center
 156
 157 Now click on the 'Browse' button next to the sequence input box and
 158 then select /examples/seq/human_mck_pro.fa file. Do the same in the
 159 next two sequence input boxes selecting mouse_mck_pro.fa and
 160 rabbit_mck_pro.fa as shown below.
 161
 162 .. image:: images/define_analysis_step2.png
 163    :alt: Choose sequences
 164    :align: center
 165
 166 Click the **create** button and in a few moments you should see
 167 something similar to the following screen shot.
 168
 169 .. image:: images/demo.png
 170    :alt: Mussagl Demo
 171    :align: center
 172
 173 This analysis is now saved in a directory called **demo_w30_t20** in
 174 the current working directory. If you close and reopen Mussagl, you
 175 can reload the saved analysis. See `Load an analysis`_ section below
 176 for details.
 177
 178
 179 Load a mussa parameter file
 180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 181
 182 If you prefer, you can define your Mussa analysis using the Mussa
 183 parameter file. See the `Parameter File Format`_ section for details
 184 on creating a .mupa file.
 185
 186 Once you have a .mupa file created, load Mussgl and select the **File >
 187 Load Mussa Parameters** menu option. Select the .mupa file and click
 188 open.
 189
 190 .. image:: images/load_mupa_menu.png
 191    :alt: Load Mussa Parameters
 192    :align: center
 193
 194 If you would like to see an example, you can load the
 195 **mck3test.mupa** file in the examples directory that comes with
 196 Mussagl.
 197
 198 .. image:: images/load_mupa_dialog.png
 199    :alt: Load Mussa Parameters Dialog
 200    :align: center
 201
 202
 203 Load an analysis
 204 ~~~~~~~~~~~~~~~~
 205
 206 To load a previously run analysis open Mussagl and select the **File >
 207 Load Analysis** menu option. Select an analysis **directory** and
 208 click open.
 209
 210 .. image:: images/load_analysis_menu.png
 211    :alt: Load Analysis Menu
 212    :align: center
 213
 214
 215 Main Window
 216 -----------
 217
 218 Overview
 219 ~~~~~~~~
 220 .. Screenshot with numbers showing features.
 221
 222 .. image:: images/window_overview.png
 223    :alt: Mussa Window
 224    :align: center
 225
 226 Legend:
 227
 228  1. `DNA Sequence (Black bars)`_
 229
 230  2. Annotation_
 231
 232  3. Motif_
 233
 234  4. `Conservation tracks`_
 235
 236  5. `Motif Toggle`_
 237
 238  6. `Zoom Factor`_ (Base pairs per pixel)
 239
 240  7. `Dynamic Threshold`_
 241
 242  8. `Sequence Information Bar`_
 243
 244  9. `Sequence Scroll Bar`_
 245
 246
 247 DNA Sequence (black bars)
 248 ~~~~~~~~~~~~~~~~~~~~~~~~~
 249
 250 .. image:: images/sequence_bar.png
 251    :alt: Sequence Bar
 252    :align: center
 253
 254 Each of the black bars represents one of the loaded sequences, in this
 255 case the sequence around the gene 'MCK' in human, mouse, and rabit.
 256
 257 FIXME: Should I mention the repeats here?
 258
 259
 260 Annotation
 261 ~~~~~~~~~~
 262
 263 .. figure:: images/annotation.png
 264    :alt: Annotation
 265    :align: center
 266
 267    Annotation shown in green on sequence bar.
 268
 269
 270 Annotations can be included on any of the sequences using the `Load a
 271 mussa parameter file`_ method of loading your sequences. You can
 272 define annotations by location or using an exact subsequence and you
 273 may also choose any color for display of the annoation; see the
 274 `Annotation File Format`_ section for details.
 275
 276 Note: Currently there is no way to add annotations using the GUI (only
 277 via the .mupa file). We plan to add this feature in the future, but it
 278 likely will not make it into the first release.
 279
 280
 281 Motif
 282 ~~~~~
 283
 284 .. figure:: images/motif.png
 285    :alt: Motif
 286    :align: center
 287
 288    Motif shown in light blue on sequence bar.
 289
 290 The only real difference between an annotation and motif in mussagl is
 291 that you can define motifs from within the GUI. See the `Motifs`_
 292 section for more information.
 293
 294
 295 Conservation tracks
 296 ~~~~~~~~~~~~~~~~~~~
 297
 298 .. figure:: images/conservation_tracks.png
 299    :alt: Conservation Tracks
 300    :align: center
 301
 302    Conservations tracks shown as red lines between sequence bars.
 303
 304 The red lines between the sequence bars represent conservation between
 305 the sequences. The amount of sequence conservation shown will depend
 306 on the relatedness of your sequences and the `dynamic threshold` you
 307 are using. Sequences with lots of repeats will cause major slow downs
 308 in calculating the matches.
 309
 310
 311 Motif Toggle
 312 ~~~~~~~~~~~~
 313
 314 .. image:: images/motif_toggle.png
 315    :alt: Motif Toggle
 316    :align: center
 317
 318 Toggles motifs on and off. This will not turn on and off annotations.
 319
 320 Note: As of the current build (#200), this feature hasn't been
 321 implemented.
 322
 323
 324 Zoom Factor
 325 ~~~~~~~~~~~
 326
 327 .. image:: images/zoom_factor.png
 328    :alt: Zoom Factor
 329    :align: center
 330
 331 The zoom factor represents the number of base pairs represented per
 332 pixel. When you zoom in far enough the sequence will switch from
 333 seeing a black bar, representing the sequence, to the actual sequence
 334 (well, ASCII representation of sequence).
 335
 336
 337 Dynamic Threshold
 338 ~~~~~~~~~~~~~~~~~
 339
 340 .. image:: images/dynamic_threshold.png
 341    :alt: Dynamic Threshold
 342    :align: center
 343
 344 You can dynamically change the threshold for how strong of match you
 345 consider the conservation to be with one of two options:
 346
 347  1. Number of base pair matchs out of window size.
 348
 349  2. Percent base pair conservation.
 350
 351 See the Threshold_ section for more infromation.
 352
 353
 354 Sequence Information Bar
 355 ~~~~~~~~~~~~~~~~~~~~~~~~
 356
 357 .. image:: images/seq_info_bar.png
 358    :alt: Sequence Information Bar
 359    :align: center
 360
 361 The sequence infomation bars can be found to the left and right sides
 362 of mussagl. Next to each sequence you will find the following
 363 information:
 364
 365  1. Species (If it has been defined)
 366  2. Total Size of Sequence
 367  3. Current base pair position
 368
 369
 370 Sequence Scroll Bar
 371 ~~~~~~~~~~~~~~~~~~~
 372
 373 .. image:: images/scroll_bar.png
 374    :alt: Sequence Scroll Bar
 375    :align: center
 376
 377 The scroll bar allows you to scroll through the sequence which is
 378 useful when you have zoomed in using the `zoom factor`_.
 379
 380
 381 Annotations / Motifs
 382 --------------------
 383
 384 Annotations
 385 ~~~~~~~~~~~
 386
 387 Motifs
 388 ~~~~~~
 389
 390 Load Motifs from File
 391 *********************
 392
 393 Motif Dialog
 394 ************
 395
 396
 397 Detailed Info
 398 -------------
 399
 400 Threshold
 401 ~~~~~~~~~
 402
 403 The threshold of an analysis is in minimum number of base pair matches
 404 must be meet to in order to be kept as a match. Note that you can vary
 405 the threshold from within Mussagl. For example, if you choose a
 406 `window size`_ of **30** and a **threshold** of **20** the mussa nway
 407 transitive algorithm will store all matches that are 20 out of 30 bp
 408 matches or better and pass it on to Mussagl. Mussagl will then allow
 409 you to dynamically choose a threshold from 20 to 30 base pairs. A
 410 threshold of 30 bps would only show 30 out of 30 bp matches. A
 411 threshold of 20 bps would show all matches of 20 out of 30 bps or
 412 better. If you would like to see results for matches lower than 20 out
 413 of 30, you will need to rerun the analysis with a lower threshold.
 414
 415 Window Size
 416 ~~~~~~~~~~~
 417
 418 The typical sizes people tend to choose are between 20 and 30. You
 419 will likely need to experiment with this setting depending on your
 420 needs and input sequence.
 421
 422
 423 Sequences
 424 ~~~~~~~~~
 425
 426 Mussa reads in sequences which are formated in the fasta_
 427 format. Mussa may take a long time to run (>10 minutes) if the total
 428 bp length near 280Kb. Once mussa has run once, you can reload
 429 previously run analyses.
 430
 431 FIXME: We have learned more about how much sequence and how many to
 432 put in mussagl, this information should be documented here.
 433
 434
 435 Mussa File Formats
 436 ------------------
 437
 438 .. _param:
 439
 440 Parameter File Format
 441 ~~~~~~~~~~~~~~~~~~~~~
 442
 443 **File Format (.mupa):**
 444
 445 ::
 446
 447   # name of anaylsis directory and stem for associated files
 448   ANA_NAME <analysis_name>
 449
 450   # if APPEND vars true, a _wXX and/or _tYY added to analysis name
 451   # where XX = WINDOW and YY = THRESHOLD
 452   # Highly recommeded with use of command line override of WINDOW or THRESHOLD
 453   APPEND_WIN <true/false>
 454   APPEND_THRES <true/false>
 455
 456   # how many sequences are being analyzed
 457   SEQUENCE_NUM <num>
 458
 459   # first sequence info
 460   SEQUENCE <fasta_file_path>
 461   ANNOTATION <annotation_file_path>
 462   SEQ_START <sequence_start>
 463
 464   # the second sequence info
 465   SEQUENCE <fasta_file_path>
 466   # ANNOTATION <annotation_file_path>
 467   SEQ_START <sequence_start>
 468   # SEQ_END <sequence_end>
 469
 470   # third sequence info
 471   SEQUENCE <fasta_file_path>
 472   # ANNOTATION <annotation_file_path>
 473
 474   # analyses parameters: command line args -w -t will override these
 475   WINDOW <num>
 476   THRESHOLD <num>
 477
 478 .. csv-table:: Parameter File Options:
 479    :header: "Option Name", "Value", "Default", "Required", "Description"
 480    :widths: 30 30 30 30 60
 481
 482    "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
 483    name of directory where analysis will be saved."
 484    "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
 485    "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
 486    "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
 487    to analyse"
 488    "SEQUENCE", "/fasta/filepath.fa", "N/A", "true", "Must define one
 489    sequence per SEQUENCE_NUM."
 490    "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
 491    annotation file. See `annotation file format`_ section for more
 492    information."
 493    "SEQ_START", "integer", "1", "false", "Optional index into fasta file"
 494    "SEQ_END", "integer", "1", "false", "Optional index into fasta file"
 495    "WINDOW", "integer", "N/A", "true", "`Window Size`_"
 496    "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
 497
 498 .. _annot:
 499
 500 Annotation File Format
 501 ~~~~~~~~~~~~~~~~~~~~~~
 502
 503 The first line in the file is the sequence name. Each line there after
 504 is a **space** seperated annotation.
 505
 506 Format:
 507
 508 ::
 509
 510   <species/sequence_name>
 511   <start> <stop> <annotation_name> <annotation_type>
 512   <start> <stop> <annotation_name> <annotation_type>
 513   <start> <stop> <annotation_name> <annotation_type>
 514   <start> <stop> <annotation_name> <annotation_type>
 515   ...
 516
 517 Example:
 518
 519 ::
 520
 521   Mouse
 522   251 500 Glorp Glorptype
 523   751 1000 Glorp Glorptype
 524   1251 1500 Glorp Glorptype
 525   1751 2000 Glorp Glorptype
 526
 527
 528 .. _motif_file_format:
 529
 530 Motif File Format
 531 ~~~~~~~~~~~~~~~~~
 532
 533 Format:
 534
 535   <motif> <red> <green> <blue>
 536
 537 Example:
 538
 539   GGCC 0.0 1 1
 540
 541
 542 .. Define links below
 543    ------------------
 544
 545 .. _GPL: http://www.opensource.org/licenses/gpl-license.php
 546 .. _wiki: http://mussa.caltech.edu
 547 .. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
 548 .. _fasta: http://en.wikipedia.org/wiki/FASTA_format
 549 .. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif
 550