8 Last updated: Oct 17th, 2006
10 Updated to Mussagl build: (In process to 424)
14 * New features / change log
15 * Comment out anything isn't implemented yet.
16 * (DONE) List of features that will be implemented in the future.
17 * Look into the homology mapping of UCSC.
18 * Add toggle to genomes.
19 * Document why one fast record per region.
20 * How to deal with the hazards of small utrs vis motif finder. (Add warning)
21 * Add warning about saving FASTA file.
22 * Add a general principles section near the top
23 * Using comparison algorithm which will pickup all repeats
24 * Add info about repeatmasking
25 * Checking upstream and downstream genes for make sure you are in the right regions.
26 * Later on: look into Ensembl
27 * Look into method of homology instead of blating.
28 * Mention advantages of using mupa.
29 * Mention the difference between using arrows and scroll bar
30 * Document the color for motifs
31 * Update for Mac user left-click
33 * Wormbase/Flybase/mirBASE tutorials
46 * Analysis "Save As" feature
51 .. INSERT CHANGE LOG HERE
52 .. END INSERT CHANGE LOG
54 Features to be Implemented
55 --------------------------
57 * Motif editor supporting more than 10 motifs
58 (Status: http://woldlab.caltech.edu/cgi-bin/mussa/ticket/122)
59 * Save motifs from Mussagl
60 (Status: http://woldlab.caltech.edu/cgi-bin/mussa/ticket/133)
62 For an up-to-date list of features to be implemented visit:
63 http://woldlab.caltech.edu/cgi-bin/mussa/roadmap
72 Mussa is an N-way version of the FamilyRelations (which is a part of
73 the Cartwheel project) 2-way comparative sequence analysis
74 software. Given DNA sequence from N species, Mussa uses all possible
75 pairwise comparions to derive an N-wise comparison. For example, given
76 sequences 1,2,3, and 4, Mussa makes 6 2-way comparisons: 1vs2, 1vs3,
77 1vs4, 2vs3, 2vs4, and 3vs4. It then compares all the links between
78 these comparisons, saving those that satisfy a transitivity
79 requirement. The saved paths are then displayed in an interactive
82 Short History of Mussa
83 ----------------------
85 Mussa Python/PMW Prototype
86 ~~~~~~~~~~~~~~~~~~~~~~~~~~
88 First Python/PMW based protoype.
93 A rewrite for speed purposes using C++ and FLTK GUI toolkit.
98 Refactored version using the more elegant Qt GUI framework and
99 OpenGL for hardware acceleration for those who have better graphics
108 Mussagl has been released open source under the `GPL v2
116 You have the option of building from source or downloading prebuilt
117 binaries. Most people will want the prebuilt versions.
121 * Mac OS X (binary or source)
122 * Windows XP (binary or source)
128 Mussagl in binary form for OS X and Windows and/or source can be
129 downloaded from http://mussa.caltech.edu/.
136 Once you have downloaded the .dmg file, double click on it and follow
137 the install instructions.
139 FIXME: Mention how to launch the program.
144 Once you have downloaded the Mussagl installer, double click on the
145 installer and follow the install instructions.
147 To start Mussagl, launch the program from Start > Programs > Mussagl >
153 Currently we do not have a binary installer for Linux. You will have
154 to build from source. See the 'build from source' section below.
160 Instructions for building from source can be found `build page
161 <http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild>`_ on the
170 If you already have your data, you can skip ahead to the the `Using
173 Let's say you have a gene of interest called 'SMN1' and you want to
174 know how the sequence surrounding the gene in multiple species is
175 conserved. Guess what, that's what we are going to do, retrieve the
176 DNA sequence for SMN1 and prepare it for using in Mussa.
178 For more information about SMN1 visit `NCBI's OMIM
179 <http://www.ncbi.nlm.nih.gov/entrez/dispomim.cgi?id=609682>`_.
181 The SMN1 data retrieved in this section can be downloaded from the
183 <http://woldlab.caltech.edu/cgi-bin/mussa/wiki/ExampleData>`_ page if
184 you prefer to skip this section of the manual.
187 UCSC Genome Browser Method
188 --------------------------
190 There are many methods of retrieving DNA sequence, but for this
191 example we will retrieve SMN1 through the UCSC genome browser located
192 at http://genome.ucsc.edu/.
195 .. image:: images/ucsc_genome_browser_home.png
196 :alt: UCSC Genome Browser
202 The first step in finding SMN1 is to use the **Gene Sorter** menu
203 option which I have highlighted in orange below:
205 .. image:: images/ucsc_menu_bar_gene_sorter.png
206 :alt: Gene Sorter Menu Option
211 .. image:: images/ucsc_gene_sorter.png
215 We will start by looking for SMN1 in the **Human Genome** and **sorting by name similarity**.
217 .. image:: images/ucsc_gs_sort_name_sim.png
218 :alt: Gene Sorter - Name Similarity
221 After you have selected **Human Genome** and **sorting by name similarity**, type *SMN1* into the search box.
223 .. image:: images/ucsc_gs_smn1.png
227 Press **Go!** and you should see the following page:
229 .. image:: images/ucsc_gs_found.png
233 Click on **SMN1** and you will be taking the gene expression atlas
236 .. image:: images/ucsc_gs_genome_position.png
237 :alt: Gene expression atlas
240 Click on **chr5 70,270,558** found in the **SMN1 row**, **Genome
243 Now we have found the location of SMN1 on human!
245 .. image:: images/ucsc_gb_smn1_human.png
246 :alt: Genome Browser - SMN1 (human)
250 Step 2 - Download CDS/UTR sequence for annotations
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253 Since we have found **SMN1**, this would be a convenient time to extract
254 the DNA sequence for the CDS and UTRs of the gene to use it as an
255 annotation_ in Mussa.
257 **Click on SMN1** shown **between** the **two orange arrows** shown
260 .. image:: images/ucsc_gb_smn1_human_click_smn1.png
261 :alt: Genome Browser - SMN1 (human) - Orange Arrows
264 You should find yourself at the SMN1 description page.
266 .. image:: images/ucsc_gb_smn1_description_page.png
267 :alt: Genome Browser - SMN1 (human) - Description page
270 **Scroll down** until you get to the **Sequence section** and click on
271 **Genomic (chr5:70,256,524-70,284,592)**.
273 .. image:: images/ucsc_gb_smn1_human_sequence.png
274 :alt: Genome Browser - SMN1 (human) - Sequence
277 You should now be at the **Genomic sequence near gene** page:
279 .. image:: images/ucsc_gb_smn1_human_get_genomic_sequence.png
280 :alt: Genome Browser - SMN1 (human) - Get genomic sequence
283 Make the following changes (highlighted in orange in the screenshot
286 1. UNcheck **introns**.
287 (We only want to annotate CDS and UTRs.)
288 2. Select **one FASTA record** per **region**.
289 (Mussa needs each CDS and UTR represented by one FASTA record per CDS/UTR).
290 3. Select **CDS in upper case, UTR in lower case.**
292 .. image:: images/ucsc_gb_smn1_human_get_genomic_sequence_diff.png
293 :alt: Genome Browser - SMN1 (human) - Get genomic sequence setup
296 Now click the **submit** button. You will then see a FASTA file with
297 many FASTA records representing the CDS and UTRS.
299 .. image:: images/ucsc_gb_smn1_human_get_genomic_sequence_submit.png
300 :alt: Genome Browser - SMN1 (human) - CDS/UTR sequence
303 Now you need to save the FASTA records to a **text file**. If you are
304 using **Firefox** or **Internet Explorer 6+** click on the **File >
305 Save As** menu option.
307 **IMPORTANT:** Make sure you select **Text Files** and **NOT**, I
308 repeat **NOT Webpage Complete** (see screenshot below.)
310 Type in **smn1_human_annot.txt** for the file name.
312 .. image:: images/smn1_human_annot.png
313 :alt: Genome Browser - SMN1 (human) - sequence annotation file
316 **IMPORTANT:** You should open the file with a text editor and make
317 sure **no HTML** was saved... If you find any HTML markup, delete
318 the markup and save the file.
320 Now we are going to **modify the file** you just saved to **add the
321 name of the species** to the **annotation file**. All you have to do
322 is **add a new line** at the **top of the file** with the word **'Human'** as
325 .. image:: images/smn1_human_annot_plus_human.png
326 :alt: Genome Browser - SMN1 (human) - sequence annotation file
329 You can add more annotations to this file if you wish. See the
330 `annotation file format`_ section for details of the file format. By
331 including FASTA records in the annotation_ file, Mussa searches your
332 DNA sequence for an exact match of the sequence in the annotation_
333 file. If found, it will be marked as an annotation_ within Mussa.
336 Step 3 - Download gene and upstream/downstream sequence
337 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
339 Use the back button in your web browser to get back the **genome
340 browser view** of **SMN1** as shown below.
342 .. image:: images/ucsc_gb_smn1_human.png
343 :alt: Genome Browser - SMN1 (human)
346 There are two options for getting additional sequence around your
347 gene. The more complex way is to zoom out so that you have the
348 sequence you want being shown in the genome browser and then follow
349 the directions for the following method.
351 The second option, which we will choose, is to leave the genome
352 browser zoomed exactly at the location of SMN1 and click on the
353 **DNA** option on the menu bar (shown with orange arrows in the
356 .. image:: images/ucsc_gb_smn1_human_dna_option.png
357 :alt: Genome Browser - SMN1 (human) - DNA Option
360 Now in the **get dna in window** page, let's add an arbitrary amount of
361 extra sequence on to each end of the gene, let's say 5000 base pairs.
363 .. image:: images/ucsc_gb_smn1_human_get_dna.png
364 :alt: Genome Browser - SMN1 (human) - Get DNA
367 Click the **get DNA** button.
369 .. image:: images/ucsc_gb_smn1_human_dna.png
370 :alt: Genome Browser - SMN1 (human) - DNA
373 Save the DNA sequence to a text file called 'smn1_human_dna.fa' as we
374 did in step 2 with the annotation file.
376 **IMPORTANT:** Make sure the file is saved as a text file and not an
377 HTML file. Open the file with a text editor and remove any HTML markup
381 Step 4 - Same/similar/related gene other species.
382 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
384 What good is a multiple sequence alignment viewer without multiple
385 sequences? Let'S find a similar gene in a few more species.
387 Use the back button on your web browser until you get the **genome
388 browser view** of **SMN1** as shown below.
390 .. image:: images/ucsc_genome_browser_home.png
391 :alt: UCSC Genome Browser
394 **Click on SMN1** shown **between** the **two orange arrows** shown
397 .. image:: images/ucsc_gb_smn1_human_click_smn1.png
398 :alt: Genome Browser - SMN1 (human) - Orange Arrows
401 You should find yourself at the SMN1 description page.
403 .. image:: images/ucsc_gb_smn1_description_page.png
404 :alt: Genome Browser - SMN1 (human) - Description page
407 **Scroll down** until you get to the **Sequence section** and click on
408 **Protein (262 aa)**.
410 .. image:: images/ucsc_gb_smn1_human_sequence.png
411 :alt: Genome Browser - SMN1 (human) - Sequence
414 Copy the SMN1 protein seqeunce by highlighting it and selecting **Edit
415 > Copy** option from the menu.
417 .. image:: images/smn1_human_protein.png
418 :alt: Genome Browser - SMN1 (human) - Protein
421 Press the back button on the web browser once and then scroll to the
422 top of the page and click on the **BLAT** option on the menu bar
423 (shown below with orange arrows).
425 .. image:: images/ucsc_gb_smn1_human_blat.png
426 :alt: Genome Browser - SMN1 (human) - Blat
429 **Paste** in the **protein sequence** and **change** the **genome** to
430 **mouse** as shown below and then click **submit**.
432 .. image:: images/ucsc_gb_smn1_human_blat_paste.png
433 :alt: Genome Browser - SMN1 (human) - Blat paste protein
436 Notice that we have two hits, one of which looks pretty good at 89.9%
439 .. image:: images/ucsc_gb_smn1_human_blat_hits.png
440 :alt: Genome Browser - SMN1 (human) - Blat hits
443 **Click** on the **brower** link next to the 89.9% match. Notice in
444 the genome browser (shown below) that there is an annotated gene
445 called SMN1 for mouse which matches the line called **your sequence
446 from blat search**. This means we are fairly confidant we found the
447 right location in the mouse genome.
449 .. image:: images/ucsc_gb_smn1_human_blat_to_browser.png
450 :alt: Genome Browser - SMN1 (human) - Blat to browser
453 Follow steps 1 through 3 for mouse and then repeat step 4 with the
454 human protein sequence to find **SMN1** in the following species (if
465 Make sure to save the extended DNA sequence and annotation file for
474 Launch Mussagl... It should look similar to the screen shot below.
476 .. image:: images/opened.png
483 ----------------------
485 Currently there are three ways to load a Mussa experiment.
487 1. `Create a new analysis`_
488 2. `Load a mussa parameter file`_ (.mupa)
489 3. `Load an analysis`_
493 Create a new analysis
494 ~~~~~~~~~~~~~~~~~~~~~
496 To create a new analysis select 'Define analysis' from the 'File'
497 menu. You should see a dialog box similar to the one below. For this
498 demo we will use the example sequences that come with Mussagl.
500 .. image:: images/define_analysis.png
501 :alt: Define Analysis
506 1. **Give the experiment a name**, for this demo, we'll use
507 'demo_w30_t20'. Mussa will create a folder with this name to store
508 the analysis files in once it has been run.
510 2. Choose a threshold_... for this demo **choose 20**. See the
511 Threshold_ section for more detailed information.
513 3. Choose a `window size`_. For this demo **choose 30**.
516 4. Choose the number of sequences_ you would like. For this demo
519 .. image:: images/define_analysis_step1a.png
523 First enter the species name of "Human" in the first "Species" text
524 box. Now click on the 'Browse' button next to the sequence input box
525 and then select /examples/seq/human_mck_pro.fa file. Do the same in
526 the next two sequence input boxes selecting mouse_mck_pro.fa and
527 rabbit_mck_pro.fa as shown below. Make sure to give them a species
528 name as well. Note that you can create annotation files using the
529 mussa `Annotation File Format`_ to add annotations to your sequence.
531 .. image:: images/define_analysis_step2.png
532 :alt: Choose sequences
535 Click the **create** button and in a few moments you should see
536 something similar to the following screen shot.
538 .. image:: images/demo.png
542 By default your analysis is NOT saved. If you try to close an analysis
543 without saving, you will be prompted with a dialog box asking you if
544 you would like to save your analysis. The `Saving`_ section for
545 details on saving your analysis. When saving, choose directory and
546 give the analysis the name **demo_w30_t20**. If you close and reopen
547 Mussagl, you will then be able to load the saved analysis. See `Load
548 an analysis`_ section below for details.
551 Load a mussa parameter file
552 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
554 If you prefer, you can define your Mussa analysis using the Mussa
555 parameter file. See the `Parameter File Format`_ section for details
556 on creating a .mupa file.
558 Once you have a .mupa file created, load Mussagl and select the **File >
559 Create Analysis from File** menu option. Select the .mupa file and click
562 .. image:: images/load_mupa_menu.png
563 :alt: Load Mussa Parameters
566 If you would like to see an example, you can load the
567 **mck3test.mupa** file in the examples directory that comes with
570 .. image:: images/load_mupa_dialog.png
571 :alt: Load Mussa Parameters Dialog
578 To load a previously run analysis open Mussagl and select the **File >
579 Open Existing Analysis** menu option. Select an analysis **directory** and
582 .. image:: images/load_analysis_menu.png
583 :alt: Load Analysis Menu
592 .. Screen-shot with numbers showing features.
594 .. image:: images/window_overview.png
600 1. `DNA Sequence (Black bars)`_
606 4. `Red conservation tracks`_
608 5. `Blue conservation tracks`_
610 6. `Zoom Factor`_ (Base pairs per pixel)
612 7. `Dynamic Threshold`_
614 8. `Sequence Information Bar`_
616 9. `Sequence Scroll Bar`_
619 DNA Sequence (black bars)
620 ~~~~~~~~~~~~~~~~~~~~~~~~~
622 .. image:: images/sequence_bar.png
626 Each of the black bars represents one of the loaded sequences, in this
627 case the sequence around the gene 'MCK' in human, mouse, and rabbit.
633 .. figure:: images/annotation.png
637 Annotation shown in green on sequence bar.
640 Annotations can be included on any of the sequences using the `Load a
641 mussa parameter file`_ or `Create a new analysis`_ method of loading
642 your sequences. You can define annotations by location or using an
643 exact sub-sequence or a FASTA sequence of the section of DNA you wish
644 to annotate. See the `Annotation File Format`_ section for details.
650 .. figure:: images/motif.png
654 Motif shown in light blue on sequence bar.
656 The only real difference between an annotation and motif in Mussagl is
657 that you can define motifs and choose a color from within the GUI. See
658 the `Motifs`_ section for more information.
661 Red conservation tracks
662 ~~~~~~~~~~~~~~~~~~~~~~~
664 .. figure:: images/conservation_tracks.png
665 :alt: Conservation Tracks
668 Conservations tracks shown as red and blue lines between sequence
671 The **red lines** between the sequence bars represent conservation
672 between the sequences (i.e. not reverse complement matches)
674 The amount of sequence conservation shown will depend on how much your
675 sequences are related and the `dynamic threshold`_ you are using.
678 Blue conservation tracks
679 ~~~~~~~~~~~~~~~~~~~~~~~~
681 .. figure:: images/conservation_tracks.png
682 :alt: Conservation Tracks
685 Conservations tracks shown as red and blue lines between sequence
688 **Blue lines** represent **reverse complement** conservation relative
689 to the sequence attached to the top of the blue line.
691 The amount of sequence conservation shown will depend on how much your
692 sequences are related and the `dynamic threshold`_ you are using.
698 .. image:: images/zoom_factor.png
702 The zoom factor represents the number of base pairs represented per
703 pixel. When you zoom in far enough the sequence will switch from
704 seeing a black bar, representing the sequence, to the actual sequence
705 (well, ASCII representation of sequence).
711 .. image:: images/dynamic_threshold.png
712 :alt: Dynamic Threshold
715 You can dynamically change the threshold for how strong a match you
716 consider the conservation to be by changing the value in the dynamic
719 The value you enter is the minimum number of base pairs that have to
720 be matched in order to be considered conserved. The second number that
721 you can't change is the `window size`_ you used when creating the
722 experiment. The last number is the percent match.
724 See the Threshold_ section for more information.
727 Sequence Information Bar
728 ~~~~~~~~~~~~~~~~~~~~~~~~
730 .. image:: images/seq_info_bar.png
731 :alt: Sequence Information Bar
734 The sequence information bars can be found to the left and right sides
735 of Mussagl. Next to each sequence you will find the following
738 1. Species (If it has been defined)
739 2. Total Size of Sequence
740 3. Current base pair position
742 Note that you can **update the species** text box. Make sure to **save your
743 experiment** after making this change by selecting **File > Save
744 Analysis** from the menu.
749 .. image:: images/scroll_bar.png
750 :alt: Sequence Scroll Bar
753 The scroll bar allows you to scroll through the sequence which is
754 useful when you have zoomed in using the `zoom factor`_.
768 After making changes, such as updating species names or adding/editing
769 motifs, you can save these changes by selecting the **File > Save
770 analysis** menu option or pressing **CTRL + S** (PC) or
771 **Apple/Command Key + S** (on Mac).
773 .. image:: images/save_analysis.png
780 To save a copy of your analysis to a new location, select the **File >
781 Save analysis as** menu option and choose a new location and name for
784 .. image:: images/save_analysis_as.png
791 See `Save Motifs to File`_ in the `Motifs`_ section.
800 Currently annotations can be added to a sequence using the mussa
801 `annotation file format`_ and can be loaded by selecting the
802 annotation file when defining a new analysis (see `Create a new
803 analysis`_ section) or by defining a .mupa file pointing to your
804 annotation file (see `Load a mussa parameter file`_ section).
809 Load Motifs from File
810 *********************
812 It is possible to load motifs from a file which was saved from a
813 previous run or by defining your own motif file. See the `Motif File
814 Format`_ section for details.
816 NOTE: Valid motif list file extensions are:
821 To load a motif file, select **Load Motif List** item from the
822 **File** menu and select a motif list file.
824 .. image:: images/load_motif.png
825 :alt: Load Motif List
832 Motifs from the `Motif Dialog`_ can be saved to file for use with
833 other analyses. If you just want your motifs to be saved with your
834 analysis, see the `save analysis`_ section for details.
836 To save a motif list, select **File > Save Motifs** menu option.
838 .. image:: images/save_motifs.png
846 Mussa has the ability to find lab motifs using the `IUPAC Nucleotide
847 Code`_ for defining a motif. To define a motif, select **Edit > Edit
848 Motifs** menu item as shown below.
850 .. image:: images/view_edit_motifs.png
851 :alt: "View > Edit Motifs" Menu
854 You will see a dialog box appear with a "apply" button in the bottom
855 right and one rows for defining motifs and the color that will be
856 displayed on the sequence. When you start adding your first motif, an
857 additional row will be added. The check box in the first column
858 defines whether the motif is displayed or not. The second column is
859 the motif display color. The third column is for the name of your
860 motif and finally, the fourth column is motif itself.
862 .. image:: images/motif_dialog_start.png
866 Now let's make a motif **'AT[C or G]CT'**. Using the `IUPAC Nucleotide
867 Code`_, type in **'ATSCT'** into the motif field and **'My Motif'** for
868 the name in the name field as shown below.
870 Notice how a second row appeared when you started to add the first
871 motif. Every time you add a new motif, a new row will appear allowing
872 you to add as many motifs as you need.
874 .. image:: images/motif_dialog_enter_motif.png
878 Now choose a color for your motif by clicking on the colored area to
879 the left of the name field. Remember to choose a color that will show
880 up well with a black bar as the background. A good tool for picking a
881 color is the `Colour Contrast Analyser
882 <http://juicystudio.com/services/colourcontrast.php>`_ by
883 `juicystudio.com <http://juicystudio.com/>`_.
885 .. image:: images/color_chooser.png
889 Once you have selected the color for your motif, click on the
890 **'apply'** button. Notice that if Mussa finds matches to your motif
891 will now show up in the main Mussa window.
895 .. image:: images/motif_dialog_bar_before.png
896 :alt: Sequence bar before motif
901 .. image:: images/motif_dialog_bar_after.png
902 :alt: Sequence bar after motif
905 To save your motifs with your analysis, see the `save analysis`_
906 section. To save your motifs to a file, see the `save motifs to file`_
910 View Mussa Alignments
911 ---------------------
913 Mussagl allows you to zoom in on Mussa alignments by selecting the set
914 of alignment(s) of interest. To do this, move the mouse near the
915 alignment you are interested in viewing and then **PRESS** and
916 **HOLD** the **LEFT mouse button** and **drag the mouse** to the other
917 side of the conservation track so that you see a bounding box
918 overlaping the alienment(s) of interest and then **let go** of the
921 In the example below, I started by left-clicking on the area marked by
922 a red dot (upper left corner of bounding box) and dragging the mouse to
923 the area marked by a blue dot (lower right corner of the bounding box)
924 and letting go of the left mouse button.
926 .. image:: images/select_sequence.png
927 :alt: Select Sequence
930 All of the lines which were not selected should be washed out as shown
933 .. image:: images/washed_out.png
934 :alt: Tracks washed out
937 With a selection made, goto the **View** menu and select **View mussa alignment**.
939 .. image:: images/view_mussa_alignment.png
940 :alt: View mussa alignment
943 You should see the alignment at the base-pair level as shown below.
945 .. image:: images/mussa_alignment.png
946 :alt: Mussa alignment
953 To run a sub-analysis **highlight** a section of sequence and *right
954 click* on it and select **Add to subanalysis**. To the same for the
955 sequences shown in orange in the screenshot below. Note that you **are
956 NOT limited** to selecting more than one subsequence from the same
959 .. image:: images/subanalysis_select_seqs.png
960 :alt: Subanalysis sequence selection
963 Once you have added your sequences for subanalysis, choose a `window size`_ and `threshold`_ and click **Ok**.
965 .. image:: images/subanalysis_dialog.png
966 :alt: Subanalysis Dialog
969 A new Mussa window will appear with the subanalysis of your sequences
970 once it's done running. This may take a while if you selected large
971 chunks of sequence with a loose threshold.
973 .. image:: images/subanalysis_done.png
974 :alt: Subalaysis complete
978 Copying sequence to clipboard
979 -----------------------------
981 To copy a sequence to the clipboard, highlight a section of sequence,
982 as shown in the screen shot below, and do one of the following:
984 * Select **Copy as FASTA** from the **Edit** menu.
985 * **Right-Click (Left-click + Apple/Command Key on Mac)** on the highlighted sequence and select **Copy as FASTA**.
986 * Press **Ctrl + C (on PC)** or **Apple/Command Key + C (on Mac)** on the keyboard.
988 .. image:: images/copy_sequence.png
993 ---------------------------------
995 * Updated to build 419.
997 To save your current mussa view to an image, select **File > Save to
998 image...** as shown below.
1000 .. image:: images/save_to_image_menu.png
1001 :alt: File > Save to image...
1004 You can define the width and the height of the image to save. By
1005 default it will use the same size of your current view. Since the
1006 Mussa view is implemented using vectors, if you choose a larger size
1007 then your current view, Mussa will redraw at the higher resolution
1008 when saving. In other words, you get higher quality images when saving
1009 at a higher resolution.
1011 If you check the "Lock aspect ratio" check box, which I have circled
1012 in red, then when you change one value, say width, the other, height,
1013 will update automatically to keep the same aspect ratio.
1015 .. image:: images/save_to_image_dialog.png
1016 :alt: Save to image dialog
1019 Click save and choose a location and filename for your file.
1021 The valid image formats are:
1023 * .png (default if no extension specified.)
1027 Detailed Information
1028 --------------------
1033 The threshold of an analysis is in minimum number of base pair matches
1034 must be meet to in order to be kept as a match. Note that you can vary
1035 the threshold from within Mussagl. For example, if you choose a
1036 `window size`_ of **30** and a **threshold** of **20** the mussa nway
1037 transitive algorithm will store all matches that are 20 out of 30 bp
1038 matches or better and pass it on to Mussagl. Mussagl will then allow
1039 you to dynamically choose a threshold from 20 to 30 base pairs. A
1040 threshold of 30 bps would only show 30 out of 30 bp matches. A
1041 threshold of 20 bps would show all matches of 20 out of 30 bps or
1042 better. If you would like to see results for matches lower than 20 out
1043 of 30, you will need to rerun the analysis with a lower threshold.
1048 The typical sizes people tend to choose are between 20 and 30. You
1049 will likely need to experiment with this setting depending on your
1050 needs and input sequence.
1056 Mussa reads in sequences which are formatted in the FASTA_
1057 format. Mussa may take a long time to run (>10 minutes) if the total
1058 bp length near 280Kb. Once mussa has run once, you can reload
1059 previously run analyzes.
1061 FIXME: We have learned more about how much sequence and how many to
1062 put in Mussagl, this information should be documented here.
1070 Parameter File Format
1071 ~~~~~~~~~~~~~~~~~~~~~
1073 **File Format (.mupa):**
1077 # name of analysis directory and stem for associated files
1078 ANA_NAME <analysis_name>
1080 # if APPEND vars true, a _wXX and/or _tYY added to analysis name
1081 # where XX = WINDOW and YY = THRESHOLD
1082 # Highly recommeded with use of command line override of WINDOW or THRESHOLD
1083 APPEND_WIN <true/false>
1084 APPEND_THRES <true/false>
1086 # how many sequences are being analyzed
1089 # first sequence info
1090 SEQUENCE <FASTA_file_path>
1091 ANNOTATION <annotation_file_path>
1092 SEQ_START <sequence_start>
1094 # the second sequence info
1095 SEQUENCE <FASTA_file_path>
1096 # ANNOTATION <annotation_file_path>
1097 SEQ_START <sequence_start>
1098 # SEQ_END <sequence_end>
1100 # third sequence info
1101 SEQUENCE <FASTA_file_path>
1102 # ANNOTATION <annotation_file_path>
1104 # analyzes parameters: command line args -w -t will override these
1108 .. csv-table:: Parameter File Options:
1109 :header: "Option Name", "Value", "Default", "Required", "Description"
1110 :widths: 30 30 30 30 60
1112 "ANA_NAME", "string", "N/A", "true", "Name of analysis (Also
1113 name of directory where analysis will be saved."
1114 "APPEND_WIN", "true/false", "?", "?", "Appends _w## to ANA_NAME"
1115 "APPEND_THRES", "true or false", "?", "?", "Appends _t## to ANA_NAME"
1116 "SEQUENCE_NUM", "integer", "N/A", "true", "The number of sequences
1118 "SEQUENCE", "/FASTA/filepath.fa", "N/A", "true", "Must define one
1119 sequence per SEQUENCE_NUM."
1120 "ANNOTATION", "/annotation/filepath.txt", "N/A", "false", "Optional
1121 annotation file. See `annotation file format`_ section for more
1123 "SEQ_START", "integer", "1", "false", "Optional index into FASTA file"
1124 "SEQ_END", "integer", "1", "false", "Optional index into FASTA file"
1125 "WINDOW", "integer", "N/A", "true", "`Window Size`_"
1126 "THRESHOLD", "integer", "N/A", "true", "`Threshold`_"
1130 Annotation File Format
1131 ~~~~~~~~~~~~~~~~~~~~~~
1133 The first line in the file is the sequence name. Each line there after
1134 is a **space** separated annotation.
1136 New as of build 198:
1138 * The annotation format now supports FASTA sequences embedded in the
1139 annotation file as shown in the format example below. Mussagl will
1140 take this sequence and look for an exact match of this sequence in
1141 your sequences. If a match is found, it will label it with the name
1142 of from the FASTA header.
1148 <species/sequence_name>
1149 <start> <stop> <annotation_name> <annotation_type>
1150 <start> <stop> <annotation_name> <annotation_type>
1151 <start> <stop> <annotation_name> <annotation_type>
1152 <start> <stop> <annotation_name> <annotation_type>
1154 ACTGACTGACGTACGTAGCTAGCTAGCTAGCACG
1155 ACGTACGTACGTACGTAGCTGTCATACGCTAGCA
1156 TGCGTAGAGGATCTCGGATGCTAGCGCTATCGAT
1157 ACGTACGGCAGTACGCGGTCAGA
1158 <start> <stop> <annotation_name> <annotation_type>
1166 251 500 Glorp Glorptype
1167 751 1000 Glorp Glorptype
1168 1251 1500 Glorp Glorptype
1169 >My favorite DNA sequence
1171 1751 2000 Glorp Glorptype
1174 .. _motif_file_format:
1181 <motif> <red> <green> <blue>
1189 IUPAC Nucleotide Code
1190 ~~~~~~~~~~~~~~~~~~~~~~
1192 For your convenience, below is a table of the IUPAC Nucleotide Code.
1194 The following table is table 1 from "Nomenclature for Incompletely
1195 Specified Bases in Nucleic Acid Sequences" which can be found at
1196 http://www.chem.qmul.ac.uk/iubmb/misc/naseq.html.
1198 ====== ================= ===================================
1199 Symbol Meaning Origin of designation
1200 ====== ================= ===================================
1209 S G or C Strong interaction (3 H bonds)
1210 W A or T Weak interaction (2 H bonds)
1211 H A or C or T not-G, H follows G in the alphabet
1212 B G or T or C not-A, B follows A
1213 V G or C or A not-T (not-U), V follows U
1214 D G or A or T not-C, D follows C
1215 N G or A or T or C aNy
1216 ====== ================= ===================================
1219 .. Define links below
1222 .. _GPL: http://www.opensource.org/licenses/gpl-license.php
1223 .. _wiki: http://mussa.caltech.edu
1224 .. _build: http://woldlab.caltech.edu/cgi-bin/mussa/wiki/MussaglBuild
1225 .. _FASTA: http://en.wikipedia.org/wiki/fasta_format
1226 .. _wpDnaMotif: http://en.wikipedia.org/wiki/DNA_motif