-==============
-Mussagl Manual
-==============
+===================
+Mussagl Manual v1.0
+===================
---------------
Brandon W. King
---------------
-Last updated: May 23th, 2006
+Last updated: Oct 31st, 2006
+
+.. Things to add
+ * New features / change log
+ * (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 a general principles section near the top
+ * Using comparison algorithm which will pickup all repeats
+ * Add info about repeatmasking
+ * Checking upstream and downstream genes for make sure you are in the right regions.
+ * Later on: look into Ensembl
+ * Look into method of homology instead of blating.
+ * 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
+
+ * Wormbase/Flybase/mirBASE tutorials
-Updated to Mussagl build: 200 (Update to 230 in progress)
.. contents::
+Status
+======
+
+
+..
+
+ .. Major New Features
+ .. ------------------
+
+ .. 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
============
What is Mussagl?
----------------
+Mussa is an N-way version of the FamilyRelations (which is a part of
+the Cartwheel project) 2-way comparative sequence analysis
+software. Given DNA sequence from N species, Mussa uses all possible
+pairwise comparions to derive an N-wise comparison. For example, given
+sequences 1,2,3, and 4, Mussa makes 6 2-way comparisons: 1vs2, 1vs3,
+1vs4, 2vs3, 2vs4, and 3vs4. It then compares all the links between
+these comparisons, saving those that satisfy a transitivity
+requirement. The saved paths are then displayed in an interactive
+viewer.
Short History of Mussa
----------------------
-
Mussa Python/PMW Prototype
~~~~~~~~~~~~~~~~~~~~~~~~~~
+First Python/PMW based prototype.
Mussa C++/FLTK
~~~~~~~~~~~~~~
+A rewrite for speed purposes using C++ and FLTK GUI toolkit.
Mussagl C++/Qt/OpenGL
~~~~~~~~~~~~~~~~~~~~~
+Refactored version using the more elegant Qt GUI framework and
+OpenGL for hardware acceleration for those who have better graphics
+cards.
Getting Mussagl
===============
Mac OS X
~~~~~~~~
-Once you have downloaded the .dmg file, double click on it and follow
-the install instructions.
-
-FIXME: Mention how to launch the program.
+ * Download .dmg file.
+ * Double click on .dmg file.
+ * Drag Mussa icon to your /Applications folder.
+ * Double Click on Mussa icon to open program.
Windows XP
~~~~~~~~~~
Obtaining Input Data
====================
-If you already have your data, you can skip ahead to the the `Using
+If you would like help obtaining data for use with Mussagl, you can
+skip ahead to the `Obtaining Input Data - Continued`_ section.
+
+If would like a tour of the software, continue with the `Using
Mussagl`_ section.
-Lets 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>`_.
+Using Mussagl
+=============
-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
-at http://genome.ucsc.edu/.
+Launch Mussagl
+--------------
+Launch Mussagl... It should look similar to the screen shot below.
-.. image:: images/ucsc_genome_browser_home.png
- :alt: UCSC Genome Broswer
+.. image:: images/opened.png
+ :alt: Launch Mussa
:align: center
-Step 1 - Find SMN1
-~~~~~~~~~~~~~~~~~~
-The first step in finding SMN1 is to use the **Gene Sorter** menu
-option which I have highlighted in orange below:
-.. image:: images/ucsc_menu_bar_gene_sorter.png
- :alt: Gene Sorter Menu Option
- :align: center
+Create/Load Analysis
+----------------------
-Gene Sorter page:
+Currently there are three ways to load a Mussa experiment.
-.. image:: images/ucsc_gene_sorter.png
- :alt: Gene Sorter
- :align: center
+ 1. `Create a new analysis`_
+ 2. `Load a mussa parameter file`_ (.mupa)
+ 3. `Load an analysis`_
-We will start by looking for SMN1 in the **Human Genome** and **sorting by name similarity**.
+.. _createnew:
-.. image:: images/ucsc_gs_sort_name_sim.png
- :alt: Gene Sorter - Name Similarity
- :align: center
+Create a new analysis
+~~~~~~~~~~~~~~~~~~~~~
-After you have selected **Human Genome** and **sorting by name similarity**, type *SMN1* into the search box.
+To create a new analysis select 'Define analysis' from the 'File'
+menu. You should see a dialog box similar to the one below. For this
+demo we will use the example sequences that come with Mussagl.
-.. image:: images/ucsc_gs_smn1.png
- :alt: Gene
+.. image:: images/define_analysis.png
+ :alt: Define Analysis
:align: center
-Press **Go!** and you should see the following page:
+Instructions:
-.. image:: images/ucsc_gs_found.png
- :alt: Found SMN1
- :align: center
+ 1. **Give the experiment a name**, for this demo, we'll use
+ 'demo_w30_t20'. Mussa will create a folder with this name to store
+ the analysis files in once it has been run.
-Click on **SMN1** and you will be taking the gene expression atlas
-page.
+ 2. Choose a threshold_... for this demo **choose 20**. See the
+ Threshold_ section for more detailed information.
-.. image:: images/ucsc_gs_genome_position.png
- :alt: Gene expression atlas
- :align: center
+ 3. Choose a `window size`_. For this demo **choose 30**.
-Click on **chr5 70,270,558** found in the **SMN1 row**, **Genome
-position column**.
-Now we have found the location of SMN1 on human!
+ 4. Choose the number of sequences_ you would like. For this demo
+ **choose 3**.
-.. image:: images/ucsc_gb_smn1_human.png
- :alt: Genome Browser - SMN1 (human)
+.. image:: images/define_analysis_step1a.png
+ :alt: Steps 1-4
:align: center
+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.
-Step 2 - Download CDS/UTR sequence for annotations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Since we have found **SMN1**, this would be a convient time to extract
-the DNA sequence for the CDS and UTRs of the gene to use it as an
-annotation_ in Mussa.
+.. image:: images/define_analysis_step2.png
+ :alt: Choose sequences
+ :align: center
-**Click on SMN1** shown **between** the **two orange arrows** shown
-below.
+Click the **create** button and in a few moments you should see
+something similar to the following screen shot.
-.. image:: images/ucsc_gb_smn1_human_click_smn1.png
- :alt: Genome Browser - SMN1 (human) - Orange Arrows
+.. image:: images/demo.png
+ :alt: Mussagl Demo
:align: center
-You should find yourself at the SMN1 description page.
+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.
-.. image:: images/ucsc_gb_smn1_description_page.png
- :alt: Genome Browser - SMN1 (human) - Description page
- :align: center
-**Scroll down** until you get to the **Sequence section** and click on
-**Genomic (chr5:70,256,524-70,284,592)**.
+Load a mussa parameter file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. image:: images/ucsc_gb_smn1_human_sequence.png
- :alt: Genome Browser - SMN1 (human) - Sequence
+If you prefer, you can define your Mussa analysis using the Mussa
+parameter file. See the `Parameter File Format`_ section for details
+on creating a .mupa file.
+
+Once you have a .mupa file created, load Mussagl and select the **File >
+Create Analysis from File** menu option. Select the .mupa file and click
+open.
+
+.. image:: images/load_mupa_menu.png
+ :alt: Load Mussa Parameters
:align: center
-You should now be at the **Genomic sequence near gene** page:
+If you would like to see an example, you can load the
+**mck3test.mupa** file in the examples directory that comes with
+Mussagl or read the `Step 5 - Create Analysis` section from the
+`Obtaining Input Data - Continued`_ section.
-.. image:: images/ucsc_gb_smn1_human_get_genomic_sequence.png
- :alt: Genome Browser - SMN1 (human) - Get genomic sequence
+.. image:: images/load_mupa_dialog.png
+ :alt: Load Mussa Parameters Dialog
:align: center
-Make the following changes (highlighted in orange in the screenshot
-below):
- 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).
- 3. Select **split UTR and CDS parts of an exon into separate FASTA records**.
- (Breaks up **exons** into CDSs and UTRs.)
-.. image:: images/ucsc_gb_smn1_human_get_genomic_sequence_diff.png
- :alt: Genome Browser - SMN1 (human) - Get genomic sequence setup
- :align: center
+Load an analysis
+~~~~~~~~~~~~~~~~
-Now click the **submit** button. You will then see a fasta file with
-many fasta records representing the CDS and UTRS.
+To load a previously run analysis open Mussagl and select the **File >
+Open Existing Analysis** menu option. Select an analysis **directory** and
+click open.
-.. image:: images/ucsc_gb_smn1_human_get_genomic_sequence_submit.png
- :alt: Genome Browser - SMN1 (human) - CDS/UTR sequence
+.. image:: images/load_analysis_menu.png
+ :alt: Load Analysis Menu
:align: center
-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.
-**IMPORTANT:** Make sure you select **Text Files** and **NOT**, I
-repeat **NOT Webpage Complete** (see screenshot below.)
+Main Window
+-----------
-Type in **smn1_human_annot.txt** for the file name.
+Overview
+~~~~~~~~
+.. Screen-shot with numbers showing features.
-.. image:: images/smn1_human_annot.png
- :alt: Genome Browser - SMN1 (human) - sequence annotation file
+.. image:: images/window_overview.png
+ :alt: Mussa Window
: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
- the markup and save the file.
-
-Now we are going to **modify the file** you just saved to **add the
-name of the species** to the **annotation file**. All you have to do
-is **add a new line** at the **top of the file** with the word **'Human'** as
-shown below:
+Legend:
-.. image:: images/smn1_human_annot_plus_human.png
- :alt: Genome Browser - SMN1 (human) - sequence annotation file
- :align: center
+ 1. `DNA Sequence (Black bars)`_
+
+ 2. Annotation_
-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
-DNA sequence for an exact match of the sequence in the annotation_
-file. If found, it will be marked as an annotation_ within Mussa.
+ 3. Motif_
+ 4. `Red conservation tracks`_
-Step 3 - Download gene and upstream/downstream sequence
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ 5. `Blue conservation tracks`_
-Use the back button in your web browser to get back the **genome
-browser view** of **SMN1** as shown below.
+ 6. `Zoom Factor`_ (Base pairs per pixel)
-.. image:: images/ucsc_gb_smn1_human.png
- :alt: Genome Browser - SMN1 (human)
- :align: center
+ 7. `Dynamic Threshold`_
-There are two options for getting additional sequence around your
-gene. The more complex way is to zoom out so that you have the
-sequence you want being shown in the genome browser and then follow
-the directions for the following method.
+ 8. `Sequence Information Bar`_
-The second option, which we will choose, is to leave the genome
-browser zoomed exactly at the location of SMN1 and click on the
-**DNA** option on the menu bar (shown with orange arrows in the
-screenshot below.)
+ 9. `Sequence Scroll Bar`_
-.. image:: images/ucsc_gb_smn1_human_dna_option.png
- :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.
+DNA Sequence (black bars)
+~~~~~~~~~~~~~~~~~~~~~~~~~
-.. image:: images/ucsc_gb_smn1_human_get_dna.png
- :alt: Genome Browser - SMN1 (human) - Get DNA
+.. image:: images/sequence_bar.png
+ :alt: Sequence Bar
:align: center
-Click the **get DNA** button.
+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.
-.. image:: images/ucsc_gb_smn1_human_dna.png
- :alt: Genome Browser - SMN1 (human) - DNA
- :align: center
-Save the DNA sequence to a text file called 'smn1_human_dna.fa' as we
-did in step 2 with the annotation file.
+Annotation
+~~~~~~~~~~
-**IMPORTANT:** Make sure the file is saved as a text file and not an
-HTML file. Open the file with a text editor and remove any HTML markup
-you find.
+.. figure:: images/annotation.png
+ :alt: Annotation
+ :align: center
+
+ Annotation shown in green on sequence bar.
-Step 4 - Same/similar/related gene other species.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Annotations can be included on any of the sequences using the `Load a
+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.
-What good is a multiple sequence alignment viewer without multiple
-sequences? Lets 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.
+Motif
+~~~~~
-.. image:: images/ucsc_genome_browser_home.png
- :alt: UCSC Genome Broswer
+.. figure:: images/motif.png
+ :alt: Motif
:align: center
-**Click on SMN1** shown **between** the **two orange arrows** shown
-below.
+ Motif shown in light blue on sequence bar.
-.. image:: images/ucsc_gb_smn1_human_click_smn1.png
- :alt: Genome Browser - SMN1 (human) - Orange Arrows
- :align: center
+The only real difference between an annotation and motif in Mussagl is
+that you can define motifs and choose a color from within the GUI. See
+the `Motifs`_ section for more information.
-You should find yourself at the SMN1 description page.
-.. image:: images/ucsc_gb_smn1_description_page.png
- :alt: Genome Browser - SMN1 (human) - Description page
+Red conservation tracks
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: images/conservation_tracks.png
+ :alt: Conservation Tracks
:align: center
+
+ Conservations tracks shown as red and blue lines between sequence
+ bars.
-**Scroll down** until you get to the **Sequence section** and click on
-**Protein (262 aa)**.
+The **red lines** between the sequence bars represent conservation
+between the sequences (i.e. not reverse complement matches)
-.. image:: images/ucsc_gb_smn1_human_sequence.png
- :alt: Genome Browser - SMN1 (human) - Sequence
- :align: center
+The amount of sequence conservation shown will depend on how much your
+sequences are related and the `dynamic threshold`_ you are using.
-Copy the SMN1 protein seqeunce by highlighting it and selecting **Edit
-> Copy** option from the menu.
+To **deselect**, click and drag over any white area and then release
+the mouse button.
-.. image:: images/smn1_human_protein.png
- :alt: Genome Browser - SMN1 (human) - Protein
- :align: center
-Press the back button on the web browser once and then scroll to the
-top of the page and click on the **BLAT** option on the menu bar
-(shown below with orange arrows).
+Blue conservation tracks
+~~~~~~~~~~~~~~~~~~~~~~~~
-.. image:: images/ucsc_gb_smn1_human_blat.png
- :alt: Genome Browser - SMN1 (human) - Blat
+.. figure:: images/conservation_tracks.png
+ :alt: Conservation Tracks
:align: center
+
+ Conservations tracks shown as red and blue lines between sequence
+ bars.
-**Paste** in the **protein sequence** and **change** the **genome** to
-**mouse** as shown below and then click **submit**.
-
-.. image:: images/ucsc_gb_smn1_human_blat_paste.png
- :alt: Genome Browser - SMN1 (human) - Blat paste protein
- :align: center
+**Blue lines** represent **reverse complement** conservation relative
+to the sequence attached to the top of the blue line.
-Notice that we have two hits, one of which looks pretty good at 89.9%
-match.
+The amount of sequence conservation shown will depend on how much your
+sequences are related and the `dynamic threshold`_ you are using.
-.. image:: images/ucsc_gb_smn1_human_blat_hits.png
- :alt: Genome Browser - SMN1 (human) - Blat hits
- :align: center
+To **deselect**, click and drag over any white area and then release
+the mouse button.
-**Click** on the **brower** link next to the 89.9% match. Notice in
-the genome browser (shown below) that there is an annotated gene
-called SMN1 for mouse which matches the line called **your sequence
-from blat search**. This means we are fairly confidant we found the
-right location in the mouse genome.
+Zoom Factor
+~~~~~~~~~~~
-.. image:: images/ucsc_gb_smn1_human_blat_to_browser.png
- :alt: Genome Browser - SMN1 (human) - Blat to browser
+.. image:: images/zoom_factor.png
+ :alt: Zoom Factor
:align: center
-Follow steps 1 through 3 for mouse and then repeat step 4 with the
-human protein sequence to find **SMN1** in the following species (if
-you find a match):
+The zoom factor represents the number of base pairs represented per
+pixel. When you zoom in far enough the sequence will switch from
+seeing a black bar, representing the sequence, to the actual sequence
+(well, ASCII representation of sequence).
- 1. Rat
- 2. Rabbit
- 3. Dog
- 4. Armadillo
- 5. Elephant
- 6. Opposum
- 7. x_tropicalis
-Make sure to save the extended DNA sequence and annotation file for
-each one.
+Dynamic Threshold
+~~~~~~~~~~~~~~~~~
-Using Mussagl
-=============
+.. image:: images/dynamic_threshold.png
+ :alt: Dynamic Threshold
+ :align: center
+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.
-Launch Mussagl
---------------
-Launch Mussagl... It should look similar to the screen shot below.
+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.
-.. image:: images/opened.png
- :alt: Launch Mussa
+Below is an animation of the dynamic threshold being increased over
+time.
+
+.. image:: images/threshold_change.gif
+ :alt: Animated Dynamic Threshold
:align: center
+See the Threshold_ section for more information.
-Create/Load Analysis
-----------------------
+Sequence Information Bar
+~~~~~~~~~~~~~~~~~~~~~~~~
-Currently there are three ways to load a Mussa experiment.
+.. image:: images/seq_info_bar.png
+ :alt: Sequence Information Bar
+ :align: center
- 1. `Create a new analysis`_
- 2. `Load a mussa parameter file`_ (.mupa)
- 3. `Load an analysis`_
+The sequence information bars can be found to the left and right sides
+of Mussagl. Next to each sequence you will find the following
+information:
-.. _createnew:
+ 1. Species (If it has been defined)
+ 2. Total Size of Sequence
+ 3. Current base pair position
-Create a new analysis
-~~~~~~~~~~~~~~~~~~~~~
+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.
-To create a new analysis select 'Define analysis' from the 'File'
-menu. You should see a dialog box similar to the one below. For this
-demo we will use the example sequences that come with Mussagl.
+Sequence Scroll Bar
+~~~~~~~~~~~~~~~~~~~
-.. image:: images/define_analysis.png
- :alt: Define Analysis
+.. image:: images/scroll_bar.png
+ :alt: Sequence Scroll Bar
:align: center
-Instructions:
+The scroll bar allows you to scroll through the sequence which is
+useful when you have zoomed in using the `zoom factor`_.
- 1. **Give the experiment a name**, for this demo, we'll use
- '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**.
+Saving
+------
- 3. Choose a threshold_... for this demo **choose 20**. See the
- Threshold_ section for more detailed information.
+Save on Close
+~~~~~~~~~~~~~
- 4. Choose the number of sequences_ you would like. For this demo
- **choose 3**.
+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.
-.. image:: images/define_analysis_step1a.png
- :alt: Steps 1-4
- :align: center
+Save Analysis
+~~~~~~~~~~~~~
-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.
+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/define_analysis_step2.png
- :alt: Choose sequences
+.. image:: images/save_analysis.png
+ :alt: Save analysis
:align: center
-Click the **create** button and in a few moments you should see
-something similar to the following screen shot.
+Save Analysis As
+~~~~~~~~~~~~~~~~
-.. image:: images/demo.png
- :alt: Mussagl Demo
+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
-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.
+Save Motif List
+~~~~~~~~~~~~~~~
+See `Save Motifs to File`_ in the `Motifs`_ section.
-Load a mussa parameter file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you prefer, you can define your Mussa analysis using the Mussa
-parameter file. See the `Parameter File Format`_ section for details
-on creating a .mupa file.
+Viewing Multiple Analyses
+-------------------------
-Once you have a .mupa file created, load Mussagl and select the **File >
-Load Mussa Parameters** menu option. Select the .mupa file and click
-open.
+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/load_mupa_menu.png
- :alt: Load Mussa Parameters
+.. image:: images/new_mussa_window_menu.png
+ :alt: New Mussa Window Menu Option
:align: center
-If you would like to see an example, you can load the
-**mck3test.mupa** file in the examples directory that comes with
-Mussagl.
+A new Mussa window will pop up.
-.. image:: images/load_mupa_dialog.png
- :alt: Load Mussa Parameters Dialog
+.. 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.
-Load an analysis
-~~~~~~~~~~~~~~~~
+Now you can create or load an existing analysis, in this new window,
+as described in the `Create/Load Analysis`_ section.
-To load a previously run analysis open Mussagl and select the **File >
-Load Analysis** menu option. Select an analysis **directory** and
-click open.
+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.
-.. image:: images/load_analysis_menu.png
- :alt: Load Analysis Menu
- :align: center
+Annotations / Motifs
+--------------------
-Main Window
------------
+Annotations
+~~~~~~~~~~~
-Overview
-~~~~~~~~
-.. Screen-shot with numbers showing features.
+Currently annotations can be added to a sequence using the mussa
+`annotation file format`_ and can be loaded by selecting the
+annotation file when defining a new analysis (see `Create a new
+analysis`_ section) or by defining a .mupa file pointing to your
+annotation file (see `Load a mussa parameter file`_ section).
-.. image:: images/window_overview.png
- :alt: Mussa Window
- :align: center
+Motifs
+~~~~~~
-Legend:
+Load Motifs from File
+*********************
- 1. `DNA Sequence (Black bars)`_
-
- 2. Annotation_
+It is possible to load motifs from a file which was saved from a
+previous run or by defining your own motif file. See the `Motif File
+Format`_ section for details.
- 3. Motif_
+NOTE: Valid motif list file extensions are:
+
+ * .mtl
+ * .txt
- 4. `Conservation tracks`_
+To load a motif file, select **Load Motif List** item from the
+**File** menu and select a motif list file.
- 5. `Motif Toggle`_
+.. image:: images/load_motif.png
+ :alt: Load Motif List
+ :align: center
- 6. `Zoom Factor`_ (Base pairs per pixel)
- 7. `Dynamic Threshold`_
+Save Motifs to File
+*******************
- 8. `Sequence Information Bar`_
+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.
- 9. `Sequence Scroll Bar`_
+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
+ :align: center
-DNA Sequence (black bars)
-~~~~~~~~~~~~~~~~~~~~~~~~~
-.. image:: images/sequence_bar.png
- :alt: Sequence Bar
+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
+Motifs** menu item as shown below.
+
+.. image:: images/view_edit_motifs.png
+ :alt: "View > Edit Motifs" Menu
:align: center
-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.
+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.
-FIXME: Should I mention the repeats here?
+.. 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 motif field and **'My Motif'** for
+the name in the name field as shown below.
-Annotation
-~~~~~~~~~~
+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.
-.. figure:: images/annotation.png
- :alt: Annotation
+.. image:: images/motif_dialog_enter_motif.png
+ :alt: Enter Motif
:align: center
-
- Annotation shown in green on sequence bar.
+Now choose a color for your motif by clicking on the colored area to
+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/>`_.
-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.
+.. image:: images/color_chooser.png
+ :alt: Color Chooser
+ :align: center
-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.
+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:
-Motif
-~~~~~
+.. image:: images/motif_dialog_bar_before.png
+ :alt: Sequence bar before motif
+ :align: center
-.. figure:: images/motif.png
- :alt: Motif
+After Motif:
+
+.. image:: images/motif_dialog_bar_after.png
+ :alt: Sequence bar after motif
:align: center
- Motif shown in light blue on sequence bar.
+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.
-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.
+Deleting a Motif
+^^^^^^^^^^^^^^^^
+To delete a motif, remove all text from the name and sequence columns
+and close the motif editor.
-Conservation tracks
-~~~~~~~~~~~~~~~~~~~
+View Mussa Alignments
+---------------------
-.. figure:: images/conservation_tracks.png
- :alt: Conservation Tracks
+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
+alignment you are interested in viewing and then **PRESS** and
+**HOLD** the **LEFT mouse button** and **drag the mouse** to the other
+side of the conservation track so that you see a bounding box
+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 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.
+
+.. image:: images/select_sequence.png
+ :alt: Select Sequence
:align: center
-
- Conservations tracks shown as red and blue lines between sequence
- 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.
+All of the lines which were not selected should be washed out as shown
+below:
+.. image:: images/washed_out.png
+ :alt: Tracks washed out
+ :align: center
-Motif Toggle
-~~~~~~~~~~~~
+With a selection made, goto the **View** menu and select **View mussa alignment**.
-.. image:: images/motif_toggle.png
- :alt: Motif Toggle
+.. image:: images/view_mussa_alignment.png
+ :alt: View mussa alignment
:align: center
-Toggles motifs on and off. This will not turn on and off annotations.
+You should see the alignment at the base-pair level as shown below.
-Note: As of the current build (#200), this feature hasn't been
-implemented.
+.. image:: images/mussa_alignment.png
+ :alt: Mussa alignment
+ :align: center
-Zoom Factor
-~~~~~~~~~~~
+Sub-analysis
+------------
-.. image:: images/zoom_factor.png
- :alt: Zoom Factor
- :align: center
+Sub-analysis was created to allow you to analyze a sub-region using
+different parameters. This may allow you to find matches which may not
+have shown up with your initial settings.
-The zoom factor represents the number of base pairs represented per
-pixel. When you zoom in far enough the sequence will switch from
-seeing a black bar, representing the sequence, to the actual sequence
-(well, ASCII representation of sequence).
-
-
-Dynamic Threshold
-~~~~~~~~~~~~~~~~~
+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 only one subsequence from the same
+sequence.
-.. image:: images/dynamic_threshold.png
- :alt: Dynamic Threshold
+.. image:: images/subanalysis_select_seqs.png
+ :alt: Subanalysis sequence selection
:align: center
-You can dynamically change the threshold for how strong of match you
-consider the conservation to be with one of two options:
-
- 1. Number of base pair matches out of window size.
-
- 2. Percent base pair conservation.
-
-See the Threshold_ section for more information.
-
+Once you have added your sequences for subanalysis, choose a `window size`_ and `threshold`_ and click **Ok**.
-Sequence Information Bar
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. image:: images/seq_info_bar.png
- :alt: Sequence Information Bar
+.. image:: images/subanalysis_dialog.png
+ :alt: Subanalysis Dialog
:align: center
-The sequence information bars can be found to the left and right sides
-of Mussagl. Next to each sequence you will find the following
-information:
-
- 1. Species (If it has been defined)
- 2. Total Size of Sequence
- 3. Current base pair position
-
-
-Sequence Scroll Bar
-~~~~~~~~~~~~~~~~~~~
+A new Mussa window will appear with the subanalysis of your sequences
+once it's done running. This may take a while if you selected large
+chunks of sequence with a loose threshold.
-.. image:: images/scroll_bar.png
- :alt: Sequence Scroll Bar
+.. image:: images/subanalysis_done.png
+ :alt: Subalaysis complete
:align: center
-The scroll bar allows you to scroll through the sequence which is
-useful when you have zoomed in using the `zoom factor`_.
-
-
-Annotations / Motifs
---------------------
-
-Annotations
-~~~~~~~~~~~
-
-Currently annotations can be added to a sequence using the mussa
-`annotation file format`_ and can be loaded by selecting the
-annotation file when defining a new analysis (see `Create a new
-analysis`_ section) or by defining a .mupa file pointing to your
-annotation file (see `Load a mussa parameter file`_ section).
-
-Motifs
-~~~~~~
-Load Motifs from File
-*********************
+Copying sequence to clipboard
+-----------------------------
-It is possible to load motifs from a file which was saved from a
-previous run or by defining your own motif file. See the `Motif File
-Format`_ section for details.
+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:
-To load a motif file, select **Load Motif List** item from the
-**File** menu and select a motif list file.
+ * 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/load_motif.png
- :alt: Load Motif List
+.. image:: images/copy_sequence.png
+ :alt: Copy sequence
:align: center
-Save Motifs to File
-*******************
-
-Note: Currently not implemented
-
-
-Motif Dialog
-************
-
-Mussa has the ability to find lab motifs using the `IUPAC Nucleotide
-Code`_ for defining a motif. To define a motif, select **View > Edit
-Motifs** menu item as shown below.
-
-.. image:: images/view_edit_motifs.png
- :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.
-
-.. 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 as shown below.
-
-.. 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.
-
-.. 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.
-
-Before Motif:
-
-.. image:: images/motif_dialog_bar_before.png
- :alt: Sequence bar before motif
- :align: center
-
-After Motif:
-
-.. image:: images/motif_dialog_bar_after.png
- :alt: Sequence bar after motif
- :align: center
-
-
-View Mussa Alignements
-----------------------
-
-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
-alignment you are interested in viewing and then **PRESS** and
-**HOLD** the **LEFT mouse button** and **drag the mouse** to the other
-side of the conservation track so that you see a bounding box
-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
-the area marked by a blue dot (lower right corner of the bounding box)
-and letting go of the left mouse button.
-
-.. image:: images/select_sequence.png
- :alt: Select Sequence
- :align: center
+Saving to an Image
+---------------------------------
-All of the lines which were not selected should be washed out as shown
-below:
+To save your current mussa view to an image, select **File > Save to
+image...** as shown below.
-.. image:: images/washed_out.png
- :alt: Tracks washed out
+.. image:: images/save_to_image_menu.png
+ :alt: File > Save to image...
:align: center
-With a selection made, goto the **View** menu and select **View mussa alignment**.
+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.
-.. image:: images/view_mussa_alignment.png
- :alt: View mussa alignment
- :align: center
+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.
-You should see the alignment at the base-pair level as shown below.
-
-.. image:: images/mussa_alignment.png
- :alt: Mussa alignment
+.. 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:
-
-Saving to an Image
----------------------------------
-
-FIXME: Need to write this section
+ * .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.
Parameter File Format
~~~~~~~~~~~~~~~~~~~~~
+Note that for the comment character '#' to work, it must contain a
+space after it (i.e. '# ').
+
**File Format (.mupa):**
::
APPEND_WIN <true/false>
APPEND_THRES <true/false>
- # how many sequences are being analyzed
- 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
name of directory where analysis will be saved."
"APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
"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 per SEQUENCE_NUM."
+ "SEQUENCE", "/FASTA/filepath.fa", "N/A", "true", "Absolute/Relative file
+ path to sequence."
"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`_"
The first line in the file is the sequence name. Each line there after
is a **space** separated annotation.
-New as of build 198:
+Update:
- * 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
Format:
- <motif> <red> <green> <blue>
+::
+
+ <motif> <optional name> <red> <green> <blue> <optional alpha>
Example:
- GGCC 0.0 1 1
+::
+ AGTGAG "My First Motif" 0.333333 0.588235 1 1
+ ATGAT "2nd Motif" 1 0 0 1
IUPAC Nucleotide Code
====== ================= ===================================
+Obtaining Input Data - Continued
+--------------------------------
+
+If you already have your data, may want to go to the `Using Mussagl`_
+section of the manual.
+
+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 browser located
+at http://genome.ucsc.edu/.
+
+
+.. image:: images/ucsc_genome_browser_home.png
+ :alt: UCSC Genome Browser
+ :align: center
+
+Step 1 - Find SMN1
+******************
+
+The first step in finding SMN1 is to use the **Gene Sorter** menu
+option which I have highlighted in orange below:
+
+.. image:: images/ucsc_menu_bar_gene_sorter.png
+ :alt: Gene Sorter Menu Option
+ :align: center
+
+Gene Sorter page:
+
+.. image:: images/ucsc_gene_sorter.png
+ :alt: Gene Sorter
+ :align: center
+
+We will start by looking for SMN1 in the **Human Genome** and **sorting by name similarity**.
+
+.. image:: images/ucsc_gs_sort_name_sim.png
+ :alt: Gene Sorter - Name Similarity
+ :align: center
+
+After you have selected **Human Genome** and **sorting by name similarity**, type *SMN1* into the search box.
+
+.. image:: images/ucsc_gs_smn1.png
+ :alt: Gene
+ :align: center
+
+Press **Go!** and you should see the following page:
+
+.. image:: images/ucsc_gs_found.png
+ :alt: Found SMN1
+ :align: center
+
+Click on **SMN1** and you will be taking the gene expression atlas
+page.
+
+.. image:: images/ucsc_gs_genome_position.png
+ :alt: Gene expression atlas
+ :align: center
+
+Click on **chr5 70,270,558** found in the **SMN1 row**, **Genome
+position column**.
+
+Now we have found the location of SMN1 on human!
+
+.. image:: images/ucsc_gb_smn1_human.png
+ :alt: Genome Browser - SMN1 (human)
+ :align: center
+
+
+Step 2 - Download CDS/UTR sequence for annotations
+**************************************************
+
+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.
+
+**Click on SMN1** shown **between** the **two orange arrows** shown
+below.
+
+.. image:: images/ucsc_gb_smn1_human_click_smn1.png
+ :alt: Genome Browser - SMN1 (human) - Orange Arrows
+ :align: center
+
+You should find yourself at the SMN1 description page.
+
+.. image:: images/ucsc_gb_smn1_description_page.png
+ :alt: Genome Browser - SMN1 (human) - Description page
+ :align: center
+
+**Scroll down** until you get to the **Sequence section** and click on
+**Genomic (chr5:70,256,524-70,284,592)**.
+
+.. image:: images/ucsc_gb_smn1_human_sequence.png
+ :alt: Genome Browser - SMN1 (human) - Sequence
+ :align: center
+
+You should now be at the **Genomic sequence near gene** page:
+
+.. image:: images/ucsc_gb_smn1_human_get_genomic_sequence.png
+ :alt: Genome Browser - SMN1 (human) - Get genomic sequence
+ :align: center
+
+Make the following changes (highlighted in orange in the screenshot
+below):
+
+ 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).
+ 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.
+
+.. 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
+using **Firefox** or **Internet Explorer 6+** click on the **File >
+Save As** menu option.
+
+**IMPORTANT:** Make sure you select **Text Files** and **NOT**, I
+repeat **NOT Webpage Complete** (see screenshot below.)
+
+Type in **smn1_human_annot.txt** for the file name.
+
+.. image:: images/smn1_human_annot.png
+ :alt: Genome Browser - SMN1 (human) - sequence annotation file
+ :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
+ the markup and save the file.
+
+Now we are going to **modify the file** you just saved to **add the
+name of the species** to the **annotation file**. All you have to do
+is **add a new line** at the **top of the file** with the word **'Human'** as
+shown below:
+
+.. image:: images/smn1_human_annot_plus_human.png
+ :alt: Genome Browser - SMN1 (human) - sequence annotation file
+ :align: center
+
+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
+DNA sequence for an exact match of the sequence in the annotation_
+file. If found, it will be marked as an annotation_ within Mussa.
+
+
+Step 3 - Download gene and upstream/downstream sequence
+*******************************************************
+
+Use the back button in your web browser to get back the **genome
+browser view** of **SMN1** as shown below.
+
+.. image:: images/ucsc_gb_smn1_human.png
+ :alt: Genome Browser - SMN1 (human)
+ :align: center
+
+There are two options for getting additional sequence around your
+gene. The more complex way is to zoom out so that you have the
+sequence you want being shown in the genome browser and then follow
+the directions for the following method.
+
+The second option, which we will choose, is to leave the genome
+browser zoomed exactly at the location of SMN1 and click on the
+**DNA** option on the menu bar (shown with orange arrows in the
+screenshot below.)
+
+.. image:: images/ucsc_gb_smn1_human_dna_option.png
+ :alt: Genome Browser - SMN1 (human) - DNA Option
+ :align: center
+
+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
+ :align: center
+
+Click the **get DNA** button.
+
+.. image:: images/ucsc_gb_smn1_human_dna.png
+ :alt: Genome Browser - SMN1 (human) - DNA
+ :align: center
+
+Save the DNA sequence to a text file called 'smn1_human_dna.fa' as we
+did in step 2 with the annotation file.
+
+**IMPORTANT:** Make sure the file is saved as a text file and not an
+HTML file. Open the file with a text editor and remove any HTML markup
+you find.
+
+
+Step 4 - Same/similar/related gene other species.
+*************************************************
+
+What good is a multiple sequence alignment viewer without multiple
+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
+browser view** of **SMN1** as shown below.
+
+.. image:: images/ucsc_genome_browser_home.png
+ :alt: UCSC Genome Browser
+ :align: center
+
+**Click on SMN1** shown **between** the **two orange arrows** shown
+below.
+
+.. image:: images/ucsc_gb_smn1_human_click_smn1.png
+ :alt: Genome Browser - SMN1 (human) - Orange Arrows
+ :align: center
+
+You should find yourself at the SMN1 description page.
+
+.. image:: images/ucsc_gb_smn1_description_page.png
+ :alt: Genome Browser - SMN1 (human) - Description page
+ :align: center
+
+**Scroll down** until you get to the **Sequence section** and click on
+**Protein (262 aa)**.
+
+.. image:: images/ucsc_gb_smn1_human_sequence.png
+ :alt: Genome Browser - SMN1 (human) - Sequence
+ :align: center
+
+Copy the SMN1 protein seqeunce by highlighting it and selecting **Edit
+> Copy** option from the menu.
+
+.. image:: images/smn1_human_protein.png
+ :alt: Genome Browser - SMN1 (human) - Protein
+ :align: center
+
+Press the back button on the web browser once and then scroll to the
+top of the page and click on the **BLAT** option on the menu bar
+(shown below with orange arrows).
+
+.. image:: images/ucsc_gb_smn1_human_blat.png
+ :alt: Genome Browser - SMN1 (human) - Blat
+ :align: center
+
+**Paste** in the **protein sequence** and **change** the **genome** to
+**mouse** as shown below and then click **submit**.
+
+.. image:: images/ucsc_gb_smn1_human_blat_paste.png
+ :alt: Genome Browser - SMN1 (human) - Blat paste protein
+ :align: center
+
+Notice that we have two hits, one of which looks pretty good at 89.9%
+match.
+
+.. image:: images/ucsc_gb_smn1_human_blat_hits.png
+ :alt: Genome Browser - SMN1 (human) - Blat hits
+ :align: center
+
+**Click** on the **brower** link next to the 89.9% match. Notice in
+the genome browser (shown below) that there is an annotated gene
+called SMN1 for mouse which matches the line called **your sequence
+from blat search**. This means we are fairly confidant we found the
+right location in the mouse genome.
+
+.. image:: images/ucsc_gb_smn1_human_blat_to_browser.png
+ :alt: Genome Browser - SMN1 (human) - Blat to browser
+ :align: center
+
+Follow steps 1 through 3 for mouse and then repeat step 4 with the
+human protein sequence to find **SMN1** in the following species (if
+you find a match):
+
+ 1. Rat
+ 2. Rabbit
+ 3. Dog
+ 4. Armadillo
+ 5. Elephant
+ 6. Opposum
+ 7. x_tropicalis
+
+Make sure to save the extended DNA sequence and annotation file for
+each one.
+
+
+Step 5 - Create Analysis
+************************
+
+At this point you should have the annotations and fasta files for each
+species. If you skipped the first four steps or are having trouble,
+you can download the example data from the `Mussa Example Data
+<http://woldlab.caltech.edu/cgi-bin/mussa/wiki/ExampleData>`_ page.
+
+There are two methods for creating an analysis. You can create MUssa
+PArameter file (.mupa), or you can use the create analysis dialog. To
+use the analysis dialog, see the `create a new analysis`_ section.
+
+If you are planning on do lots of analyses using the same sets of DNA
+sequence but with different parameters, annotations, and/or species,
+it is often best to setup a `mupa`_ file, so you can:
+
+ * Change parameters and rerun analysis easily.
+ * Use Mussa command line option to run a batch analyses.
+ * Define an analysis for someone else to run.
+
+Now, we will create a `mupa`_ file for smn1 for an analysis with
+Human, Mouse, and Cow. I'll start by showing you the `mupa`_ file and
+then walking you through it line by line.
+
+Start by creating a new text file called *smn1_human_mouse_cow.mupa*,
+in your smn1 directory. I decided to put each of the fasta and
+annotation files for each species in it's own directory, so I will use
+that setup (see screen shot below).
+
+.. image:: images/smn1_dir_structure.png
+ :alt: SMN1 directory structure
+ :align: center
+
+smn1_human_mouse_cow.mupa:
+::
+
+ # Analysis name
+ ANA_NAME smn1_human_mouse_cow
+
+ # Appending to analysis name
+ APPEND_WIN true
+ APPEND_THRES true
+
+ # Human sequence
+ SEQUENCE human/smn1_human_dna.fasta
+ ANNOTATION human/smn1_human_annotations.txt
+
+ SEQUENCE mouse/smn1_mouse_dna.fasta
+ ANNOTATION mouse/smn1_mouse_annotations.txt
+
+ SEQUENCE cow/smn1_cow_dna.fasta
+ ANNOTATION cow/smn1_cow_annotations.txt
+
+ # Window size / Threshold
+ WINDOW 30
+ THRESHOLD 24
+
+The first line is the analysis name. This will be the name of the
+directory the results will be saved in when using the Mussa `command
+line`_ option --no-gui to run an analysis. If you are using the Mussa
+GUI, then you will be prompted for a directory name as mentioned in
+the `saving`_ section.
+
+::
+
+ # Analysis name
+ ANA_NAME smn1_human_mouse_cow
+
+If your provide the APPEND_WIN and/or APPEND_THRES, and set them to
+true, the window size and threshold will be appended to the analysis
+name. In this example, using the --no-gui `command line`_ option, our
+directory name would be *smn1_human_mouse_cow_w30_t24*.
+
+::
+
+ # Appending to analysis name
+ APPEND_WIN true
+ APPEND_THRES true
+
+The following six lines provide Mussa with the location of the
+sequence files and annotation files. The files can provided with
+relative paths from the .mupa file. In other words, this .mupa file
+will provide the proper path to the human sequence only if there
+exists a directory called *human* in the same directory as this .mupa
+file.
+
+To provide the species name for each species, you have to put the
+species name in the annotation files. See the `annotation file
+format`_ section for more details.
+
+::
+
+ # Human sequence
+ SEQUENCE human/smn1_human_dna.fasta
+ ANNOTATION human/smn1_human_annotations.txt
+
+ SEQUENCE mouse/smn1_mouse_dna.fasta
+ ANNOTATION mouse/smn1_mouse_annotations.txt
+
+ SEQUENCE cow/smn1_cow_dna.fasta
+ ANNOTATION cow/smn1_cow_annotations.txt
+
+And finally, the `window size`_ and `threshold`_ parameters.
+
+::
+
+ # Window size / Threshold
+ WINDOW 30
+ THRESHOLD 24
+
+Next, open Mussagl and select the **File > Create Analysis from File**
+menu option. Mussagl should run your analysis if everything was setup
+properly.
+
+
+
+Understanding Mussa
+===================
+
+Command Line
+------------
+
+Mussa has some very useful command line options that allow for
+loading an existing analysis or running a new analysis with or without
+launching the GUI.
+
+Mussa options:
+ --help help message
+ -p, --run-analysis arg run an analysis defined by the mussa parameter file
+ --view-analysis arg load a previously run analysis
+ --motifs arg annotate analysis with motifs from this file
+ --no-gui terminate without running an analysis
+ --python launch as a `python interpreter`_
+
+Running an analysis using the --no-gui option is useful when you want
+to run many analyses on a compute server and save the results for
+viewing in the future.
+
+
+Performance
+-----------
+
+Algorithm Behavior
+~~~~~~~~~~~~~~~~~~
+
+FIXME: Include seqcomp algorithm info.
+
+FIXME: Include transitivity info.
+
+Repeats
+~~~~~~~
+
+Repeat masking of all input sequences, or at least of the "reference"
+genome, can be important for reducing compute time and for simplifying
+subsequent visual interpretation. Larger loci generally contain more
+repeat elements, and as their number grows so will the number of Mussa
+connections among them. If not repeat filtered, connectivity between
+shared repeat elements can obscure important relationships between
+single copy features.
+
+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.**
+
+To deal with a situation where you have many repeats in your sequences
+do any of the following:
+
+ * Use shorter sequence lengths.
+ * Repeat mask one or more of your sequences.
+ * Increase the threshold.
+
+
+Details
+-------
+
+Case: Conservation track suddenly stops
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Details about this potentially confusing case can be found `here
+<http://woldlab.caltech.edu/cgi-bin/mussa/wiki/OverlappingWindows>`_.
+
+Python Interpreter
+------------------
+
+Mussagl has some functionality for running a python interpreter for
+interacting with the internals of Mussagl and/or executing Python
+code. This feature is mostly experimental at this point in time. If
+you have interest in this feature or would like to know more about it,
+contact us using the contact information found at
+http://mussa.caltech.edu/.
+
.. Define links below
------------------
.. _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
-.. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif
\ No newline at end of file
+.. _FASTA: http://en.wikipedia.org/wiki/fasta_format
+.. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif
+.. _mupa: `Parameter File Format`_
\ No newline at end of file
projects / mussa.git / blobdiff