doc/manual/mussagl_manual.rst

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