Brandon W. King
---------------
-Last updated: Oct 16th, 2006
+Last updated: Oct 20th, 2006
-Updated to Mussagl build: 287? (In process to 424)
+Updated to Mussagl build: (In process to 424)
.. Things to add
* New features / change log
- * Comment out anything isn't implemented yet.
+ * (DONE) Comment out anything isn't implemented yet.
* (DONE) List of features that will be implemented in the future.
* Look into the homology mapping of UCSC.
* Add toggle to genomes.
Features to be Implemented
--------------------------
- * Motif editor supporting more than 10 motifs
- (Status: http://woldlab.caltech.edu/cgi-bin/mussa/ticket/122)
- * Save motifs from Mussagl
- (Status: http://woldlab.caltech.edu/cgi-bin/mussa/ticket/133)
-
For an up-to-date list of features to be implemented visit:
http://woldlab.caltech.edu/cgi-bin/mussa/roadmap
'demo_w30_t20'. Mussa will create a folder with this name to store
the analysis files in once it has been run.
- 2. Choose a `window size`_. For this demo **choose 30**.
-
- 3. Choose a threshold_... for this demo **choose 20**. See the
+ 2. Choose a threshold_... for this demo **choose 20**. See the
Threshold_ section for more detailed information.
+ 3. Choose a `window size`_. For this demo **choose 30**.
+
+
4. Choose the number of sequences_ you would like. For this demo
**choose 3**.
:alt: Steps 1-4
:align: center
-Now click on the 'Browse' button next to the sequence input box and
-then select /examples/seq/human_mck_pro.fa file. Do the same in the
-next two sequence input boxes selecting mouse_mck_pro.fa and
-rabbit_mck_pro.fa as shown below. Note that you can create annotation
-files using the mussa `Annotation File Format`_ to add annotations to
-your sequence.
+First enter the species name of "Human" in the first "Species" text
+box. Now click on the 'Browse' button next to the sequence input box
+and then select /examples/seq/human_mck_pro.fa file. Do the same in
+the next two sequence input boxes selecting mouse_mck_pro.fa and
+rabbit_mck_pro.fa as shown below. Make sure to give them a species
+name as well. Note that you can create annotation files using the
+mussa `Annotation File Format`_ to add annotations to your sequence.
.. image:: images/define_analysis_step2.png
:alt: Choose sequences
:alt: Mussagl Demo
:align: center
-This analysis is now saved in a directory called **demo_w30_t20** in
-the current working directory. If you close and reopen Mussagl, you
-can reload the saved analysis. See `Load an analysis`_ section below
-for details.
+By default your analysis is NOT saved. If you try to close an analysis
+without saving, you will be prompted with a dialog box asking you if
+you would like to save your analysis. The `Saving`_ section for
+details on saving your analysis. When saving, choose directory and
+give the analysis the name **demo_w30_t20**. If you close and reopen
+Mussagl, you will then be able to load the saved analysis. See `Load
+an analysis`_ section below for details.
Load a mussa parameter file
on creating a .mupa file.
Once you have a .mupa file created, load Mussagl and select the **File >
-Load Mussa Parameters** menu option. Select the .mupa file and click
+Create Analysis from File** menu option. Select the .mupa file and click
open.
.. image:: images/load_mupa_menu.png
~~~~~~~~~~~~~~~~
To load a previously run analysis open Mussagl and select the **File >
-Load Analysis** menu option. Select an analysis **directory** and
+Open Existing Analysis** menu option. Select an analysis **directory** and
click open.
.. image:: images/load_analysis_menu.png
useful when you have zoomed in using the `zoom factor`_.
+Saving
+------
+
+Save on Close
+~~~~~~~~~~~~~
+
+When ever you create a new analysis or make a change such as
+adding/editing a motif or changing a species name, an asterisk (*)
+will appear in the title of the window showing that there are changes
+that have not been saved. If you close a Mussa window without saving
+changes, Mussa will ask you if you would like to save the changes that
+have been made.
+
+Save Analysis
+~~~~~~~~~~~~~
+
+After making changes, such as updating species names or adding/editing
+motifs, you can save these changes by selecting the **File > Save
+analysis** menu option or pressing **CTRL + S** (PC) or
+**Apple/Command Key + S** (on Mac).
+
+.. image:: images/save_analysis.png
+ :alt: Save analysis
+ :align: center
+
+Save Analysis As
+~~~~~~~~~~~~~~~~
+
+To save a copy of your analysis to a new location, select the **File >
+Save analysis as** menu option and choose a new location and name for
+your analysis.
+
+.. image:: images/save_analysis_as.png
+ :alt: Save analysis
+ :align: center
+
+Save Motif List
+~~~~~~~~~~~~~~~
+
+See `Save Motifs to File`_ in the `Motifs`_ section.
+
+
+Viewing Multiple Analyses
+-------------------------
+
+Some times it is useful to view more than one analysis at a time. To
+do accomplish this, Mussa allows you to open a new Mussa window by
+selecting the **File > New Mussa Window** menu option.
+
+.. image:: images/new_mussa_window_menu.png
+ :alt: New Mussa Window Menu Option
+ :align: center
+
+A new Mussa window will pop up.
+
+.. figure:: images/new_mussa_window.png
+ :alt: New Mussa Window
+ :align: center
+
+ A new Mussa window on the right, in which a second analysis has
+ been loaded.
+
+Now you can create or load an existing analysis, in this new window,
+as described in the `Create/Load Analysis`_ section.
+
+You can view as many analyses as you can fit on your screen or until
+you run out of available RAM. If you notice a rapid decrease in
+performance and hear lots of noise coming from your hard drive, you
+probably ran out of RAM and are now using virtual memory (i.e. much
+much slower). If this happens, you may need to avoid opening as many
+analyses at one time.
+
+
Annotations / Motifs
--------------------
Save Motifs to File
*******************
-Note: Currently not implemented
+Motifs from the `Motif Dialog`_ can be saved to file for use with
+other analyses. If you just want your motifs to be saved with your
+analysis, see the `save analysis`_ section for details.
+To save a motif list, select **File > Save Motifs** menu option. By
+default, Mussa will append .mtl if you do not provide a file extension
+(valid file extensions: .mtl & .txt).
-Motif Dialog
-************
+.. image:: images/save_motifs.png
+ :alt: Save Motifs
+ :align: center
-**New Features:**
-
-Build 276
- * Allow for toggling individual motifs on and off.
-Build 269
- * Field added for naming motifs.
+Motif Dialog
+************
Mussa has the ability to find lab motifs using the `IUPAC Nucleotide
Code`_ for defining a motif. To define a motif, select **Edit > Edit
:alt: "View > Edit Motifs" Menu
:align: center
-You will see a dialog box appear with a "set motifs" button and 10
-rows for defining motifs and the color that will be displayed on the
-sequence. By default all 10 motifs start off as with white as the
-color. In the image below, I changed the color from white to blue to
-make it easier to see. The first text box is for the motif and the
-second box is for the name of the motif. The check box defines whether
-the motif is displayed or not.
+You will see a dialog box appear with a "apply" button in the bottom
+right and one rows for defining motifs and the color that will be
+displayed on the sequence. When you start adding your first motif, an
+additional row will be added. The check box in the first column
+defines whether the motif is displayed or not. The second column is
+the motif display color. The third column is for the name of your
+motif and finally, the fourth column is motif itself.
.. image:: images/motif_dialog_start.png
:alt: Motif Dialog
:align: center
Now let's make a motif **'AT[C or G]CT'**. Using the `IUPAC Nucleotide
-Code`_, type in **'ATSCT'** into the first box and 'My Motif' for the
-name in the second box as shown below.
+Code`_, type in **'ATSCT'** into the motif field and **'My Motif'** for
+the name in the name field as shown below.
+
+Notice how a second row appeared when you started to add the first
+motif. Every time you add a new motif, a new row will appear allowing
+you to add as many motifs as you need.
.. image:: images/motif_dialog_enter_motif.png
:alt: Enter Motif
:align: center
Now choose a color for your motif by clicking on the colored area to
-the left of the motif. In the image above, you would click on the blue
-square, but by default the squares will be white. Remember to choose a
-color that will show up well with a black bar as the background.
+the left of the name field. Remember to choose a color that will show
+up well with a black bar as the background. A good tool for picking a
+color is the `Colour Contrast Analyser
+<http://juicystudio.com/services/colourcontrast.php>`_ by
+`juicystudio.com <http://juicystudio.com/>`_.
.. image:: images/color_chooser.png
:alt: Color Chooser
:align: center
-Once you have selected the color for your motif, click on the 'set
-motifs' button. Notice that if Mussa finds matches to your motif will
-now show up in the main Mussagl window.
+Once you have selected the color for your motif, click on the
+**'apply'** button. Notice that if Mussa finds matches to your motif
+will now show up in the main Mussa window.
Before Motif:
:alt: Sequence bar after motif
:align: center
+To save your motifs with your analysis, see the `save analysis`_
+section. To save your motifs to a file, see the `save motifs to file`_
+section.
+
+Deleting a Motif
+^^^^^^^^^^^^^^^^
+
+To delete a motif, remove all text from the name and sequence columns
+and close the motif editor.
View Mussa Alignments
---------------------
To run a sub-analysis **highlight** a section of sequence and *right
click* on it and select **Add to subanalysis**. To the same for the
sequences shown in orange in the screenshot below. Note that you **are
-NOT limited** to selecting more than one subsequence from the same
+NOT limited** to selecting only one subsequence from the same
sequence.
.. image:: images/subanalysis_select_seqs.png
:alt: Copy sequence
:align: center
+
Saving to an Image
---------------------------------
- * Updated to build 419.
-
To save your current mussa view to an image, select **File > Save to
image...** as shown below.
====== ================= ===================================
+
+Understanding Mussa
+===================
+
+
+Performance
+-----------
+
+Algorithm Behavior
+~~~~~~~~~~~~~~~~~~
+
+FIXME: Include seqcomp algorithm info.
+
+FIXME: Include transitivity info.
+
+Repeats
+~~~~~~~
+
+The algorithm Mussa uses to find conserved sequences is sensitive to
+repeated DNA segments, which are frequently occurring in most
+genomes. The problem with repeats, is that one repeat from one
+sequence can show up many times in another sequence. Every connection
+Mussa makes takes up memory and CPU time to process.
+
+The formula for the number of connections, C, that will be made for R
+instances of a single repeat (meaning R copies of one repeat in each
+sequence) and S sequences is:
+
+C = (R^2)[S(S-1)/2]
+
+Table of example situations:
+
+===== ===== =====
+ C R S
+===== ===== =====
+ 16 4 2
+ 48 4 3
+ 96 4 4
+ 160 4 5
+ 240 4 6
+ 336 4 7
+ 448 4 8
+ 24 2 4
+ 54 3 4
+ 96 4 4
+ 150 5 4
+ 216 6 4
+ 294 7 4
+ 384 8 4
+ 2500 50 2
+ 7500 50 3
+15000 50 4
+10000 100 2
+30000 100 3
+60000 100 4
+===== ===== =====
+
+After the connections, C, are found, they are passed on to the
+transitivity filter, which is a C^2 algorithm (FIXME: confirm
+algorithm is C^2). This means with 50 repeats in 2 sequences giving
+you a C of 2500, ends up with a C^2 of 6,250,000.
+
+**Conclusion: repeats cause the processing time of Mussa to skyrocket.**
+
+One way to deal with a situation where you have many repeats in your
+sequences is do any of the following: user shorter sequence lengths;
+repeat mask one or more of your sequences; or increase the threshold.
+
+Details
+-------
+
+Case: Conservation track suddenly stops
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
.. Define links below
------------------