Brandon W. King
---------------
-Last updated: Oct 17th, 2006
+Last updated: Oct 18th, 2006
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
Save on Close
~~~~~~~~~~~~~
-FIXME: Write this.
+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
~~~~~~~~~~~~~
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
--------------------
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.
+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).
.. image:: images/save_motifs.png
:alt: Save Motifs
Motif Dialog
************
-**New Features:**
-
-Build 276
- * Allow for toggling individual motifs on and off.
-
-Build 269
- * Field added for naming motifs.
-
Mussa has the ability to find lab motifs using the `IUPAC Nucleotide
Code`_ for defining a motif. To define a motif, select **Edit > Edit
Motifs** menu item as shown below.
: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 sensative to
+repeated DNA segments, which are naturally apart of many 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 it also takes time to store and process the results.
+
+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 lots of repeats in
+your sequences is to use shorter sequences lengths and/or repeat mask
+at least one of your sequences.
+
+Details
+-------
+
+Case: Conservation track suddenly stops
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
.. Define links below
------------------
projects / mussa.git / blobdiff