Brandon W. King
---------------
-Last updated: July 7th, 2006
+Last updated: Oct 18th, 2006
-Updated to Mussagl build: 287
+Updated to Mussagl build: (In process to 424)
.. Things to add
* New features / change log
- * Comment out anything isn't implemented yet.
- * List of features that will be implemented in the future.
+ * (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.
* Document why one fast record per region.
* How to deal with the hazards of small utrs vis motif finder. (Add warning)
- * Add warning about saving fasta file.
+ * Add warning about saving FASTA file.
* Add a general principles section near the top
* Using comparison algorithm which will pickup all repeats
* Add info about repeatmasking
* Mention advantages of using mupa.
* Mention the difference between using arrows and scroll bar
* Document the color for motifs
- * Update for Mac user left click
+ * Update for Mac user left-click
-* Wormbase/Flybase/mirBASE
+ * Wormbase/Flybase/mirBASE tutorials
.. contents::
+Status
+======
+
+Major New Features
+------------------
+
+ * Build 381
+ * Analysis "Save As" feature
+
+Change Log
+----------
+
+.. INSERT CHANGE LOG HERE
+.. END INSERT CHANGE LOG
+
+Features to be Implemented
+--------------------------
+
+For an up-to-date list of features to be implemented visit:
+http://woldlab.caltech.edu/cgi-bin/mussa/roadmap
+
Introduction
============
Short History of Mussa
----------------------
-
Mussa Python/PMW Prototype
~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~
Refactored version using the more elegant Qt GUI framework and
-OpenGL for hardware acceleration for those who have beter graphics
+OpenGL for hardware acceleration for those who have better graphics
cards.
Getting Mussagl
If you already have your data, you can skip ahead to the the `Using
Mussagl`_ section.
-Lets say you have a gene of interest called 'SMN1' and you want to
+Let's say you have a gene of interest called 'SMN1' and you want to
know how the sequence surrounding the gene in multiple species is
conserved. Guess what, that's what we are going to do, retrieve the
DNA sequence for SMN1 and prepare it for using in Mussa.
For more information about SMN1 visit `NCBI's OMIM
<http://www.ncbi.nlm.nih.gov/entrez/dispomim.cgi?id=609682>`_.
+The SMN1 data retrieved in this section can be downloaded from the
+`Mussa Example Data
+<http://woldlab.caltech.edu/cgi-bin/mussa/wiki/ExampleData>`_ page if
+you prefer to skip this section of the manual.
+
+
UCSC Genome Browser Method
--------------------------
There are many methods of retrieving DNA sequence, but for this
-example we will retrieve SMN1 through the UCSC genome broswer located
+example we will retrieve SMN1 through the UCSC genome browser located
at http://genome.ucsc.edu/.
+
.. image:: images/ucsc_genome_browser_home.png
- :alt: UCSC Genome Broswer
+ :alt: UCSC Genome Browser
:align: center
Step 1 - Find SMN1
Step 2 - Download CDS/UTR sequence for annotations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Since we have found **SMN1**, this would be a convient time to extract
+Since we have found **SMN1**, this would be a convenient time to extract
the DNA sequence for the CDS and UTRs of the gene to use it as an
annotation_ in Mussa.
1. UNcheck **introns**.
(We only want to annotate CDS and UTRs.)
- 2. Select **one fasta record** per **region**.
- (Mussa needs each CDS and UTR represented by one fasta record per CDS/UTR).
+ 2. Select **one FASTA record** per **region**.
+ (Mussa needs each CDS and UTR represented by one FASTA record per CDS/UTR).
3. Select **CDS in upper case, UTR in lower case.**
.. image:: images/ucsc_gb_smn1_human_get_genomic_sequence_diff.png
:alt: Genome Browser - SMN1 (human) - Get genomic sequence setup
:align: center
-Now click the **submit** button. You will then see a fasta file with
-many fasta records representing the CDS and UTRS.
+Now click the **submit** button. You will then see a FASTA file with
+many FASTA records representing the CDS and UTRS.
.. image:: images/ucsc_gb_smn1_human_get_genomic_sequence_submit.png
:alt: Genome Browser - SMN1 (human) - CDS/UTR sequence
:align: center
-Now you need to save the fasta records to a **text file**. If you are
+Now you need to save the FASTA records to a **text file**. If you are
using **Firefox** or **Internet Explorer 6+** click on the **File >
Save As** menu option.
:align: center
**IMPORTANT:** You should open the file with a text editor and make
- sure **no html** was saved... If you find any html markup, delete
+ sure **no HTML** was saved... If you find any HTML markup, delete
the markup and save the file.
Now we are going to **modify the file** you just saved to **add the
You can add more annotations to this file if you wish. See the
`annotation file format`_ section for details of the file format. By
-including fasta records in the annotation_ file, Mussa searches your
+including FASTA records in the annotation_ file, Mussa searches your
DNA sequence for an exact match of the sequence in the annotation_
file. If found, it will be marked as an annotation_ within Mussa.
:alt: Genome Browser - SMN1 (human) - DNA Option
:align: center
-Now in the **get dna in window** page, lets add an arbitrary amount of
-extra sequence on to each end of the gene, lets say 5000 base pairs.
+Now in the **get dna in window** page, let's add an arbitrary amount of
+extra sequence on to each end of the gene, let's say 5000 base pairs.
.. image:: images/ucsc_gb_smn1_human_get_dna.png
:alt: Genome Browser - SMN1 (human) - Get DNA
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
What good is a multiple sequence alignment viewer without multiple
-sequences? Lets find a similar gene in a few more species.
+sequences? Let'S find a similar gene in a few more species.
Use the back button on your web browser until you get the **genome
-broswer view** of **SMN1** as shown below.
+browser view** of **SMN1** as shown below.
.. image:: images/ucsc_genome_browser_home.png
- :alt: UCSC Genome Broswer
+ :alt: UCSC Genome Browser
:align: center
**Click on SMN1** shown **between** the **two orange arrows** shown
'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
3. Motif_
- 4. `Conservation tracks`_
+ 4. `Red conservation tracks`_
- 5. `Motif Toggle`_
+ 5. `Blue conservation tracks`_
6. `Zoom Factor`_ (Base pairs per pixel)
Each of the black bars represents one of the loaded sequences, in this
case the sequence around the gene 'MCK' in human, mouse, and rabbit.
-FIXME: Should I mention the repeats here?
-
Annotation
~~~~~~~~~~
Annotations can be included on any of the sequences using the `Load a
-mussa parameter file`_ method of loading your sequences. You can
-define annotations by location or using an exact sub-sequence and you
-may also choose any color for display of the annotation; see the
-`Annotation File Format`_ section for details.
-
-Note: Currently there is no way to add annotations using the GUI (only
-via the .mupa file). We plan to add this feature in the future, but it
-likely will not make it into the first release.
+mussa parameter file`_ or `Create a new analysis`_ method of loading
+your sequences. You can define annotations by location or using an
+exact sub-sequence or a FASTA sequence of the section of DNA you wish
+to annotate. See the `Annotation File Format`_ section for details.
Motif
Motif shown in light blue on sequence bar.
The only real difference between an annotation and motif in Mussagl is
-that you can define motifs from within the GUI. See the `Motifs`_
-section for more information.
+that you can define motifs and choose a color from within the GUI. See
+the `Motifs`_ section for more information.
-Conservation tracks
-~~~~~~~~~~~~~~~~~~~
+Red conservation tracks
+~~~~~~~~~~~~~~~~~~~~~~~
.. figure:: images/conservation_tracks.png
:alt: Conservation Tracks
bars.
The **red lines** between the sequence bars represent conservation
-between the sequences and **blue lines** represent **reverse
-complement** conservation. The amount of sequence conservation shown
-will depend on the relatedness of your sequences and the `dynamic
-threshold` you are using. Sequences with lots of repeats will cause
-major slow downs in calculating the matches.
+between the sequences (i.e. not reverse complement matches)
+The amount of sequence conservation shown will depend on how much your
+sequences are related and the `dynamic threshold`_ you are using.
-Motif Toggle
-~~~~~~~~~~~~
-.. image:: images/motif_toggle.png
- :alt: Motif Toggle
+Blue conservation tracks
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: images/conservation_tracks.png
+ :alt: Conservation Tracks
:align: center
+
+ Conservations tracks shown as red and blue lines between sequence
+ bars.
-Toggles motifs on and off. This will not turn on and off annotations.
+**Blue lines** represent **reverse complement** conservation relative
+to the sequence attached to the top of the blue line.
-Note: As of the current build (#200), this feature hasn't been
-implemented.
+The amount of sequence conservation shown will depend on how much your
+sequences are related and the `dynamic threshold`_ you are using.
Zoom Factor
:alt: Dynamic Threshold
:align: center
-You can dynamically change the threshold for how strong of match you
-consider the conservation to be with one of two options:
+You can dynamically change the threshold for how strong a match you
+consider the conservation to be by changing the value in the dynamic
+threshold box.
- 1. Number of base pair matches out of window size.
-
- 2. Percent base pair conservation.
+The value you enter is the minimum number of base pairs that have to
+be matched in order to be considered conserved. The second number that
+you can't change is the `window size`_ you used when creating the
+experiment. The last number is the percent match.
See the Threshold_ section for more information.
2. Total Size of Sequence
3. Current base pair position
+Note that you can **update the species** text box. Make sure to **save your
+experiment** after making this change by selecting **File > Save
+Analysis** from the menu.
Sequence Scroll Bar
~~~~~~~~~~~~~~~~~~~
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 I have loaded a second
+ experiment.
+
+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
--------------------
previous run or by defining your own motif file. See the `Motif File
Format`_ section for details.
+NOTE: Valid motif list file extensions are:
+
+ * .mtl
+ * .txt
+
To load a motif file, select **Load Motif List** item from the
**File** menu and select a motif list file.
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 lets 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.
+Now let's make a motif **'AT[C or G]CT'**. Using the `IUPAC Nucleotide
+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.
-View Mussa Alignements
-----------------------
+Deleting a Motif
+^^^^^^^^^^^^^^^^
+
+To delete a motif, remove all text from the name and sequence columns
+and close the motif editor.
+
+View Mussa Alignments
+---------------------
Mussagl allows you to zoom in on Mussa alignments by selecting the set
of alignment(s) of interest. To do this, move the mouse near the
overlaping the alienment(s) of interest and then **let go** of the
*left mouse button*.
-In the example below, I started by left clicking on the area marked by
-a red dot (upper left corner of bounding box) and draging the mouse to
+In the example below, I started by left-clicking on the area marked by
+a red dot (upper left corner of bounding box) and dragging the mouse to
the area marked by a blue dot (lower right corner of the bounding box)
and letting go of the left mouse button.
To copy a sequence to the clipboard, highlight a section of sequence,
as shown in the screen shot below, and do one of the following:
- * Select **Copy as Fasta** from the **Edit** menu.
- * **Right Click (Left click + Apple/Command Key on Mac)** on the highlighted sequence and select **Copy as Fasta**.
+ * Select **Copy as FASTA** from the **Edit** menu.
+ * **Right-Click (Left-click + Apple/Command Key on Mac)** on the highlighted sequence and select **Copy as FASTA**.
* Press **Ctrl + C (on PC)** or **Apple/Command Key + C (on Mac)** on the keyboard.
.. image:: images/copy_sequence.png
:alt: Copy sequence
:align: center
+
Saving to an Image
---------------------------------
-FIXME: Need to write this section
+ * Updated to build 419.
+
+To save your current mussa view to an image, select **File > Save to
+image...** as shown below.
+
+.. image:: images/save_to_image_menu.png
+ :alt: File > Save to image...
+ :align: center
+
+You can define the width and the height of the image to save. By
+default it will use the same size of your current view. Since the
+Mussa view is implemented using vectors, if you choose a larger size
+then your current view, Mussa will redraw at the higher resolution
+when saving. In other words, you get higher quality images when saving
+at a higher resolution.
+
+If you check the "Lock aspect ratio" check box, which I have circled
+in red, then when you change one value, say width, the other, height,
+will update automatically to keep the same aspect ratio.
+
+.. image:: images/save_to_image_dialog.png
+ :alt: Save to image dialog
+ :align: center
+
+Click save and choose a location and filename for your file.
+
+The valid image formats are:
+
+ * .png (default if no extension specified.)
+ * .jpg
Detailed Information
Sequences
~~~~~~~~~
-Mussa reads in sequences which are formatted in the fasta_
+Mussa reads in sequences which are formatted in the FASTA_
format. Mussa may take a long time to run (>10 minutes) if the total
bp length near 280Kb. Once mussa has run once, you can reload
previously run analyzes.
SEQUENCE_NUM <num>
# first sequence info
- SEQUENCE <fasta_file_path>
+ SEQUENCE <FASTA_file_path>
ANNOTATION <annotation_file_path>
SEQ_START <sequence_start>
# the second sequence info
- SEQUENCE <fasta_file_path>
+ SEQUENCE <FASTA_file_path>
# ANNOTATION <annotation_file_path>
SEQ_START <sequence_start>
# SEQ_END <sequence_end>
# third sequence info
- SEQUENCE <fasta_file_path>
+ SEQUENCE <FASTA_file_path>
# ANNOTATION <annotation_file_path>
# analyzes parameters: command line args -w -t will override these
"APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
"SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
to analyze"
- "SEQUENCE", "/fasta/filepath.fa", "N/A", "true", "Must define one
+ "SEQUENCE", "/FASTA/filepath.fa", "N/A", "true", "Must define one
sequence per SEQUENCE_NUM."
"ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
annotation file. See `annotation file format`_ section for more
information."
- "SEQ_START", "integer", "1", "false", "Optional index into fasta file"
- "SEQ_END", "integer", "1", "false", "Optional index into fasta file"
+ "SEQ_START", "integer", "1", "false", "Optional index into FASTA file"
+ "SEQ_END", "integer", "1", "false", "Optional index into FASTA file"
"WINDOW", "integer", "N/A", "true", "`Window Size`_"
"THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
New as of build 198:
- * The annotation format now supports fasta sequences embedded in the
+ * The annotation format now supports FASTA sequences embedded in the
annotation file as shown in the format example below. Mussagl will
take this sequence and look for an exact match of this sequence in
your sequences. If a match is found, it will label it with the name
- of from the fasta header.
+ of from the FASTA header.
Format:
<start> <stop> <annotation_name> <annotation_type>
<start> <stop> <annotation_name> <annotation_type>
<start> <stop> <annotation_name> <annotation_type>
- >Fasta Header
+ >FASTA Header
ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
.. _GPL: http://www.opensource.org/licenses/gpl-license.php
.. _wiki: http://mussa.caltech.edu
.. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
-.. _fasta: http://en.wikipedia.org/wiki/FASTA_format
+.. _FASTA: http://en.wikipedia.org/wiki/fasta_format
.. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif
\ No newline at end of file
projects / mussa.git / blobdiff