8 Last updated: March 23rd, 2006
10 Updated to Mussagl build: 141
23 Short History of Mussa
24 ----------------------
27 Mussa Python/PMW Prototype
28 ~~~~~~~~~~~~~~~~~~~~~~~~~~
45 Mussagl has been released open source under the `GPL v2
53 You have the option of building from source or downloading prebuilt
54 binaries. Most people will want the prebuilt versions.
58 * Mac OS X (binary or source)
59 * Windows XP (binary or source)
65 Mussagl can be downloaded from http://mussa.caltech.edu/.
72 Once you have downloaded the .dmg file, dubble click on it and follow
73 the install instructions.
75 FIXME: Mention how to launch the program.
80 Once you have downloaded the Mussagl installer, double click on the
81 installer and follow the install instructions.
83 To start mussagl, launch the program from Start > Programs > Mussagl >
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.
96 Instructions for building from source can be found `build page
97 <http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild>`_ on the
109 Launch Mussagl... It should look similar to the screen shot below.
111 .. image:: images/opened.png
118 ----------------------
120 Currently there are three ways to load a mussa experiment.
122 1. `Create a new analysis`_
123 2. `Load a mussa parameter file`_ (.mupa)
124 3. `Load an analysis`_
128 Create a new analysis
129 ~~~~~~~~~~~~~~~~~~~~~
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.
135 .. image:: images/define_analysis.png
136 :alt: Define Analysis
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.
145 2. Choose a `window size`_. For this demo **choose 30**.
147 3. Choose a threshold_... for this demo **choose 20**. See the
148 Threshold_ section for more detailed information.
150 4. Choose the number of sequences_ you would like. For this demo
153 .. image:: images/define_analysis_step1a.png
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.
162 .. image:: images/define_analysis_step2.png
163 :alt: Choose sequences
166 Click the **create** button and in a few moments you should see
167 something similar to the following screen shot.
169 .. image:: images/demo.png
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
179 Load a mussa parameter file
180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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
190 .. image:: images/load_mupa_menu.png
191 :alt: Load Mussa Parameters
194 If you would like to see an example, you can load the
195 **mck3test.mupa** file in the examples directory that comes with
198 .. image:: images/load_mupa_dialog.png
199 :alt: Load Mussa Parameters Dialog
206 To load a previously run analysis open Mussagl and select the **File >
207 Load Analysis** menu option. Select an analysis **directory** and
210 .. image:: images/load_analysis_menu.png
211 :alt: Load Analysis Menu
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
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
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.
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.
261 Parameter File Format
262 ~~~~~~~~~~~~~~~~~~~~~
264 **File Format (.mupa):**
268 # name of anaylsis directory and stem for associated files
269 ANA_NAME <analysis_name>
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>
277 # how many sequences are being analyzed
280 # first sequence info
281 SEQUENCE <fasta_file_path>
282 ANNOTATION <annotation_file_path>
283 SEQ_START <sequence_start>
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>
291 # third sequence info
292 SEQUENCE <fasta_file_path>
293 # ANNOTATION <annotation_file_path>
295 # analyses parameters: command line args -w -t will override these
299 .. csv-table:: Parameter File Options:
300 :header: "Option Name", "Value", "Default", "Required", "Description"
301 :widths: 30 30 30 30 60
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
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
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`_"
321 Annotation File Format
322 ~~~~~~~~~~~~~~~~~~~~~~
324 The first line in the file is the sequence name. Each line there after
325 is a **space** seperated annotation.
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>
343 251 500 Glorp Glorptype
344 751 1000 Glorp Glorptype
345 1251 1500 Glorp Glorptype
346 1751 2000 Glorp Glorptype
356 <motif> <red> <green> <blue>
360 .. Define links below
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