doc/manual/mussagl_manual.rst

   1 ==============
   2 Mussagl Manual
   3 ==============
   4 ------------------
   5 By Brandon W. King
   6 ------------------
   7
   8 Last updated: May 15th, 2006
   9
  10 Updated to Mussagl build: 141 (Update to 193 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 Dynamic Threshold
 223 ~~~~~~~~~~~~~~~~~
 224
 225 Zoom
 226 ~~~~
 227
 228 Sequence Info
 229 ~~~~~~~~~~~~~
 230
 231 Scroll Bar
 232 ~~~~~~~~~~
 233 .. Moving sequence
 234
 235
 236 Annotations / Motifs
 237 --------------------
 238
 239 Annotations
 240 ~~~~~~~~~~~
 241
 242 Motifs
 243 ~~~~~~
 244
 245 Load Motifs from File
 246 *********************
 247
 248 Motif Dialog
 249 ************
 250
 251
 252 Detailed Info
 253 -------------
 254
 255 Threshold
 256 ~~~~~~~~~
 257
 258 The threshold of an analysis is in minimum number of base pair matches
 259 must be meet to in order to be kept as a match. Note that you can vary
 260 the threshold from within Mussagl. For example, if you choose a
 261 `window size`_ of **30** and a **threshold** of **20** the mussa nway
 262 transitive algorithm will store all matches that are 20 out of 30 bp
 263 matches or better and pass it on to Mussagl. Mussagl will then allow
 264 you to dynamically choose a threshold from 20 to 30 base pairs. A
 265 threshold of 30 bps would only show 30 out of 30 bp matches. A
 266 threshold of 20 bps would show all matches of 20 out of 30 bps or
 267 better. If you would like to see results for matches lower than 20 out
 268 of 30, you will need to rerun the analysis with a lower threshold.
 269
 270 Window Size
 271 ~~~~~~~~~~~
 272
 273 The typical sizes people tend to choose are between 20 and 30. You
 274 will likely need to experiment with this setting depending on your
 275 needs and input sequence.
 276
 277
 278 Sequences
 279 ~~~~~~~~~
 280
 281 Mussa reads in sequences which are formated in the fasta_
 282 format. Mussa may take a long time to run (>10 minutes) if the total
 283 bp length near 280Kb. Once mussa has run once, you can reload
 284 previously run analyses.
 285
 286 FIXME: We have learned more about how much sequence and how many to
 287 put in mussagl, this information should be documented here.
 288
 289
 290 Mussa File Formats
 291 ------------------
 292
 293 .. _param:
 294
 295 Parameter File Format
 296 ~~~~~~~~~~~~~~~~~~~~~
 297
 298 **File Format (.mupa):**
 299
 300 ::
 301
 302   # name of anaylsis directory and stem for associated files
 303   ANA_NAME <analysis_name>
 304
 305   # if APPEND vars true, a _wXX and/or _tYY added to analysis name
 306   # where XX = WINDOW and YY = THRESHOLD
 307   # Highly recommeded with use of command line override of WINDOW or THRESHOLD
 308   APPEND_WIN <true/false>
 309   APPEND_THRES <true/false>
 310
 311   # how many sequences are being analyzed
 312   SEQUENCE_NUM <num>
 313
 314   # first sequence info
 315   SEQUENCE <fasta_file_path>
 316   ANNOTATION <annotation_file_path>
 317   SEQ_START <sequence_start>
 318
 319   # the second sequence info
 320   SEQUENCE <fasta_file_path>
 321   # ANNOTATION <annotation_file_path>
 322   SEQ_START <sequence_start>
 323   # SEQ_END <sequence_end>
 324
 325   # third sequence info
 326   SEQUENCE <fasta_file_path>
 327   # ANNOTATION <annotation_file_path>
 328
 329   # analyses parameters: command line args -w -t will override these
 330   WINDOW <num>
 331   THRESHOLD <num>
 332
 333 .. csv-table:: Parameter File Options:
 334    :header: "Option Name", "Value", "Default", "Required", "Description"
 335    :widths: 30 30 30 30 60
 336
 337    "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
 338    name of directory where analysis will be saved."
 339    "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
 340    "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
 341    "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
 342    to analyse"
 343    "SEQUENCE", "/fasta/filepath.fa", "N/A", "true", "Must define one
 344    sequence per SEQUENCE_NUM."
 345    "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
 346    annotation file. See `annotation file format`_ section for more
 347    information."
 348    "SEQ_START", "integer", "1", "false", "Optional index into fasta file"
 349    "SEQ_END", "integer", "1", "false", "Optional index into fasta file"
 350    "WINDOW", "integer", "N/A", "true", "`Window Size`_"
 351    "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
 352
 353 .. _annot:
 354
 355 Annotation File Format
 356 ~~~~~~~~~~~~~~~~~~~~~~
 357
 358 The first line in the file is the sequence name. Each line there after
 359 is a **space** seperated annotation.
 360
 361 Format:
 362
 363 ::
 364
 365   <species/sequence_name>
 366   <start> <stop> <annotation_name> <annotation_type>
 367   <start> <stop> <annotation_name> <annotation_type>
 368   <start> <stop> <annotation_name> <annotation_type>
 369   <start> <stop> <annotation_name> <annotation_type>
 370   ...
 371
 372 Example:
 373
 374 ::
 375
 376   Mouse
 377   251 500 Glorp Glorptype
 378   751 1000 Glorp Glorptype
 379   1251 1500 Glorp Glorptype
 380   1751 2000 Glorp Glorptype
 381
 382
 383 .. _motif:
 384
 385 Motif File Format
 386 ~~~~~~~~~~~~~~~~~
 387
 388 Format:
 389
 390   <motif> <red> <green> <blue>
 391
 392 Example:
 393
 394   GGCC 0.0 1 1
 395
 396
 397 .. Define links below
 398    ------------------
 399
 400 .. _GPL: http://www.opensource.org/licenses/gpl-license.php
 401 .. _wiki: http://mussa.caltech.edu
 402 .. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
 403 .. _fasta: http://en.wikipedia.org/wiki/FASTA_format
 404