622deb16df0b02bf70d87e39079df5c8935ae6cd
[jalview.git] / wiki / PhyloBioRuby.wiki
1 #summary Tutorial for multiple sequence alignments and phylogenetic methods in BioRuby -- under development!
2
3
4
5 = Introduction =
6
7 Under development!
8
9 Tutorial for multiple sequence alignments and phylogenetic methods in [http://bioruby.open-bio.org/ BioRuby].
10
11 Eventually, this is expected to be placed on the official !BioRuby page.
12
13 Author: [http://www.cmzmasek.net/ Christian M Zmasek], Sanford-Burnham Medical Research Institute
14
15  
16 Copyright (C) 2011 Christian M Zmasek
17
18
19 = Multiple Sequence Alignments =
20
21
22 == Multiple Sequence Alignment Input and Output ==
23
24 === Reading in a Multiple Sequence Alignment from a File ===
25
26 The follow example shows how to read in a *ClustalW*-formatted multiple sequence alignment.
27
28 {{{
29 #!/usr/bin/env ruby
30 require 'bio'
31
32 # Reads in a ClustalW-formatted multiple sequence alignment
33 # from a file named "infile_clustalw.aln" and stores it in 'report'.
34 report = Bio::ClustalW::Report.new(File.read('infile_clustalw.aln'))
35
36 # Accesses the actual alignment.
37 msa = report.alignment
38
39 # Goes through all sequences in 'msa' and prints the
40 # actual molecular sequence.
41 msa.each do |entry|
42   puts entry.seq
43 end
44 }}}
45
46  
47
48 === Writing a Multiple Sequence Alignment to a File ===
49
50
51 The following example shows how to write a multiple sequence alignment in *FASTA*-format. It first creates a file named "outfile.fasta" for writing ('w') and then writes the multiple sequence alignment referred to by variable 'msa' to it in FASTA-format (':fasta').
52
53 {{{
54 #!/usr/bin/env ruby
55 require 'bio'
56
57 # Creates a new file named "outfile.fasta" and writes
58 # multiple sequence alignment 'msa' to it in fasta format.
59 File.open('outfile.fasta', 'w') do |f|
60   f.write(msa.output(:fasta))
61 end
62 }}}
63
64 ==== Setting the Output Format ====
65
66 The following constants determine the output format.
67
68   * ClustalW: `:clustal`
69   * FASTA:    `:fasta`
70   * PHYLIP interleaved (will truncate sequence names to no more than 10 characters): `:phylip`
71   * PHYLIP non-interleaved (will truncate sequence names to no more than 10 characters): `:phylipnon`
72   * MSF: `:msf`
73   * Molphy: `:molphy`
74
75
76 For example, the following writes PHYLIP's non-interleaved format:
77
78 {{{
79 f.write(align.output(:phylipnon))
80 }}}
81
82
83
84 == Calculating Multiple Sequence Alignments ==
85
86 !BioRuby can be used to execute a variety of multiple sequence alignment
87 programs (such as [http://mafft.cbrc.jp/alignment/software/ MAFFT], [http://probcons.stanford.edu/ Probcons], [http://www.clustal.org/ ClustalW], [http://www.drive5.com/muscle/ Muscle], and [http://www.tcoffee.org/Projects_home_page/t_coffee_home_page.html T-Coffee]). 
88 In the following, examples for using the MAFFT and Muscle are shown.
89
90
91 === MAFFT ===
92
93 The following example uses the MAFFT program to align four sequences
94 and then prints the result to the screen.
95 Please note that if the path to the MAFFT executable is properly set `mafft=Bio::MAFFT.new(options)` can be used instead of explicitly indicating the path as in the example. 
96
97 {{{
98 #!/usr/bin/env ruby
99 require 'bio'
100
101 # 'seqs' is either an array of sequences or a multiple sequence 
102 # alignment. In general this is read in from a file as described in ?.
103 # For the purpose of this tutorial, it is generated in code.
104 seqs = ['MFQIPEFEPSEQEDSSSAER',
105         'MGTPKQPSLAPAHALGLRKS',
106         'PKQPSLAPAHALGLRKS',
107         'MCSTSGCDLE'] 
108
109
110 # Calculates the alignment using the MAFFT program on the local
111 # machine with options '--maxiterate 1000 --localpair'
112 # and stores the result in 'report'.
113 options = ['--maxiterate', '1000', '--localpair']
114 mafft = Bio::MAFFT.new('path/to/mafft', options)
115 report = mafft.query_align(seqs)
116
117 # Accesses the actual alignment.
118 align = report.alignment
119
120 # Prints each sequence to the console.
121 align.each { |s| puts s.to_s }
122
123 }}}
124
125 References:
126
127  * Katoh, Toh (2008) "Recent developments in the MAFFT multiple sequence alignment program" Briefings in Bioinformatics 9:286-298 
128
129  * Katoh, Toh 2010 (2010) "Parallelization of the MAFFT multiple sequence alignment program" Bioinformatics 26:1899-1900 
130
131
132
133 === Muscle ===
134
135 {{{
136 #!/usr/bin/env ruby
137 require 'bio'
138
139 # 'seqs' is either an array of sequences or a multiple sequence 
140 # alignment. In general this is read in from a file as described in ?.
141 # For the purpose of this tutorial, it is generated in code.
142 seqs = ['MFQIPEFEPSEQEDSSSAER',
143         'MGTPKQPSLAPAHALGLRKS',
144         'PKQPSLAPAHALGLRKS',
145         'MCSTSGCDLE']  
146
147 # Calculates the alignment using the Muscle program on the local
148 # machine with options '-quiet -maxiters 64'
149 # and stores the result in 'report'.
150 options = ['-quiet', '-maxiters', '64']
151 muscle = Bio::Muscle.new('path/to/muscle', options)
152 report = muscle.query_align(seqs)
153
154 # Accesses the actual alignment.
155 align = report.alignment
156
157 # Prints each sequence to the console.
158 align.each { |s| puts s.to_s }
159
160 }}}
161
162 References:
163
164  * Edgar, R.C. (2004) "MUSCLE: multiple sequence alignment with high accuracy and high throughput" Nucleic Acids Res 32(5):1792-1797
165
166 === Other Programs ===
167
168 _need more detail here..._
169
170 [http://probcons.stanford.edu/ Probcons], [http://www.clustal.org/ ClustalW], and [http://www.tcoffee.org/Projects_home_page/t_coffee_home_page.html T-Coffee] can be used in the same manner as the programs above. 
171
172
173
174 == Manipulating Multiple Sequence Alignments ==
175
176 Oftentimes, multiple sequence to be used for phylogenetic inference are 'cleaned up' in some manner. For instance, some researchers prefer to delete columns with more than 50% gaps. The following code is an example of how to do that in !BioRuby.
177
178
179 _... to be done_
180
181 {{{
182 #!/usr/bin/env ruby
183 require 'bio'
184
185 }}}
186
187
188 ----
189
190 = Phylogenetic Trees =
191
192
193 == Phylogenetic Tree Input and Output ==
194
195
196 === Reading in of Phylogenetic Trees ===
197
198
199
200 ====Newick or New Hampshire Format====
201
202 _... to be done_
203
204 {{{
205 #!/usr/bin/env ruby
206 require 'bio'
207
208 }}}
209
210 ====phyloXML Format====
211
212 Partially copied from [https://www.nescent.org/wg_phyloinformatics/BioRuby_PhyloXML_HowTo_documentation Diana Jaunzeikare's documentation].
213
214 In addition to !BioRuby, a libxml Ruby binding is also required. This can be installed with the following command: 
215
216 {{{
217 % gem install -r libxml-ruby
218 }}}
219
220 This example reads file "example.xml" and stores its [http://www.phyloxml.org/ phyloXML]-formatted trees in variable 'trees'.
221
222 {{{
223 #!/usr/bin/env ruby
224 require 'bio'
225
226 # This creates new phyloXML parser.
227 trees = Bio::PhyloXML::Parser.new('example.xml')
228
229 # This prints the names of all trees in the file.
230 trees.each do |tree|
231   puts tree.name
232 end
233
234 # If there are several trees in the file, you can access the one you wish via index.
235 tree = trees[3]
236
237 }}}
238
239
240
241 === Writing of Phylogenetic Trees ===
242
243 ====Newick or New Hampshire Format====
244
245 _... to be done_
246
247 {{{
248 #!/usr/bin/env ruby
249 require 'bio'
250
251 }}}
252
253 ====phyloXML Format====
254
255 Partially copied from [https://www.nescent.org/wg_phyloinformatics/BioRuby_PhyloXML_HowTo_documentation Diana Jaunzeikare's documentation].
256
257 In addition to !BioRuby, a libxml Ruby binding is also required. This can be installed with the following command: 
258
259 {{{
260 % gem install -r libxml-ruby
261 }}}
262
263 This example writes trees 'tree1' and 'tree2' to file "tree.xml" in [http://www.phyloxml.org/ phyloXML] format.
264
265 {{{
266 #!/usr/bin/env ruby
267 require 'bio'
268
269 # this creates new phyloXML writer.
270 writer = Bio::PhyloXML::Writer.new('tree.xml')
271
272 # Writes tree to the file "tree.xml".
273 writer.write(tree1)
274
275 # Adds another tree to the file.
276 writer.write(tree2)
277
278
279 }}}
280
281
282
283 == Phylogenetic Inference ==
284
285 _Currently !BioRuby does not contain wrappers for phylogenetic inference programs, thus I am progress of writing a RAxML wrapper followed by a wrapper for FastME..._
286
287 _What about pairwise distance calculation?_
288
289
290
291 == Maximum Likelihood ==
292
293 === RAxML ===
294
295 _... to be done_
296
297 {{{
298 #!/usr/bin/env ruby
299 require 'bio'
300
301 }}}
302
303
304 === PhyML ===
305
306 _... to be done_
307
308 {{{
309 #!/usr/bin/env ruby
310 require 'bio'
311
312 }}}
313
314 == Pairwise Distance Based Methods ==
315
316 === FastME ===
317
318 _... to be done_
319
320 {{{
321 #!/usr/bin/env ruby
322 require 'bio'
323
324 }}}
325
326
327
328 === PHYLIP? ===
329
330
331
332 == Support Calculation? ==
333
334 === Bootstrap Resampling? ===
335
336
337 ----
338
339 = Analyzing Phylogenetic Trees =
340
341 == PAML ==
342
343
344 == Gene Duplication Inference ==
345
346 _need to further test and then import GSoC 'SDI' work..._
347
348
349 == Others? ==
350
351
352 ----
353
354 = Putting It All Together =
355
356 Example of a small "pipeline"-type program running a mininal phyogenetic analysis: starting with a set of sequences and ending with a phylogenetic tree.
357