Brandon W. King
---------------
-Last updated: May 23th, 2006
+Last updated: July 7th, 2006
+
+Updated to Mussagl build: 287
+
+
+.. Things to add
+ * New features / change log
+ * Comment out anything isn't implemented yet.
+ * 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
-Updated to Mussagl build: 141 (Update to 200 in progress)
.. contents::
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 protoype.
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 beter graphics
+cards.
Getting Mussagl
===============
__ wiki_
+Obtaining Input Data
+====================
+
+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
+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>`_.
+
+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/.
+
+.. image:: images/ucsc_genome_browser_home.png
+ :alt: UCSC Genome Broswer
+ :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 convient 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, lets add an arbitrary amount of
+extra sequence on to each end of the gene, lets 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? 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.
+
+.. image:: images/ucsc_genome_browser_home.png
+ :alt: UCSC Genome Broswer
+ :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.
+
Using Mussagl
=============
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 **View > Edit
+Code`_ for defining a motif. To define a motif, select **Edit > Edit
Motifs** menu item as shown below.
.. image:: images/view_edit_motifs.png
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.
+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.
.. 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.
+Code`_, type in **'ATSCT'** into the first box and 'My Motif' for the
+name in the second box as shown below.
.. image:: images/motif_dialog_enter_motif.png
:alt: Enter Motif
:align: center
+Sub-analysis
+------------
+
+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
+sequence.
+
+.. image:: images/subanalysis_select_seqs.png
+ :alt: Subanalysis sequence selection
+ :align: center
+
+Once you have added your sequences for subanalysis, choose a `window size`_ and `threshold`_ and click **Ok**.
+
+.. image:: images/subanalysis_dialog.png
+ :alt: Subanalysis Dialog
+ :align: center
+
+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/subanalysis_done.png
+ :alt: Subalaysis complete
+ :align: center
+
+
+Copying sequence to clipboard
+-----------------------------
+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**.
+ * 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
---------------------------------
.. _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
-
+.. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif
\ No newline at end of file
projects / mussa.git / blobdiff