1 # Copyright (C) 2007-2012 Martin A. Hansen.
3 # This program is free software; you can redistribute it and/or
4 # modify it under the terms of the GNU General Public License
5 # as published by the Free Software Foundation; either version 2
6 # of the License, or (at your option) any later version.
8 # This program is distributed in the hope that it will be useful,
9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 # GNU General Public License for more details.
13 # You should have received a copy of the GNU General Public License
14 # along with this program; if not, write to the Free Software
15 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17 # http://www.gnu.org/copyleft/gpl.html
19 # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
21 # This software is part of the Biopieces framework (www.biopieces.org).
23 # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
26 require 'maasha/seq/digest'
27 require 'maasha/seq/trim'
30 autoload :BackTrack, 'maasha/seq/backtrack'
31 autoload :Dynamic, 'maasha/seq/dynamic'
32 autoload :Homopolymer, 'maasha/seq/homopolymer'
33 autoload :Hamming, 'maasha/seq/hamming'
34 autoload :Levenshtein, 'maasha/seq/levenshtein'
35 autoload :Ambiguity, 'maasha/seq/ambiguity'
40 PROTEIN = %w[f l s y c w p h q r i m t n k v a d e g]
43 # Translation table 11
44 # (http://www.ncbi.nlm.nih.gov/Taxonomy/taxonomyhome.html/index.cgi?chapter=cgencodes#SG11)
45 # AAs = FFLLSSSSYY**CC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG
46 # Starts = ---M---------------M------------MMMM---------------M------------
47 # Base1 = TTTTTTTTTTTTTTTTCCCCCCCCCCCCCCCCAAAAAAAAAAAAAAAAGGGGGGGGGGGGGGGG
48 # Base2 = TTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGG
49 # Base3 = TCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAG
51 "TTG" => "M", "CTG" => "M", "ATT" => "M", "ATC" => "M",
52 "ATA" => "M", "ATG" => "M", "GTG" => "M"
56 "TTT" => "F", "TCT" => "S", "TAT" => "Y", "TGT" => "C",
57 "TTC" => "F", "TCC" => "S", "TAC" => "Y", "TGC" => "C",
58 "TTA" => "L", "TCA" => "S", "TAA" => "*", "TGA" => "*",
59 "TTG" => "L", "TCG" => "S", "TAG" => "*", "TGG" => "W",
60 "CTT" => "L", "CCT" => "P", "CAT" => "H", "CGT" => "R",
61 "CTC" => "L", "CCC" => "P", "CAC" => "H", "CGC" => "R",
62 "CTA" => "L", "CCA" => "P", "CAA" => "Q", "CGA" => "R",
63 "CTG" => "L", "CCG" => "P", "CAG" => "Q", "CGG" => "R",
64 "ATT" => "I", "ACT" => "T", "AAT" => "N", "AGT" => "S",
65 "ATC" => "I", "ACC" => "T", "AAC" => "N", "AGC" => "S",
66 "ATA" => "I", "ACA" => "T", "AAA" => "K", "AGA" => "R",
67 "ATG" => "M", "ACG" => "T", "AAG" => "K", "AGG" => "R",
68 "GTT" => "V", "GCT" => "A", "GAT" => "D", "GGT" => "G",
69 "GTC" => "V", "GCC" => "A", "GAC" => "D", "GGC" => "G",
70 "GTA" => "V", "GCA" => "A", "GAA" => "E", "GGA" => "G",
71 "GTG" => "V", "GCG" => "A", "GAG" => "E", "GGG" => "G"
74 # Error class for all exceptions to do with Seq.
75 class SeqError < StandardError; end
78 # Quality scores bases
86 attr_accessor :seq_name, :seq, :type, :qual
88 # Class method to instantiate a new Sequence object given
90 def self.new_bp(record)
91 seq_name = record[:SEQ_NAME]
93 type = record[:SEQ_TYPE].to_sym if record[:SEQ_TYPE]
94 qual = record[:SCORES]
96 self.new(seq_name, seq, type, qual)
99 # Class method that generates all possible oligos of a specifed length and type.
100 def self.generate_oligos(length, type)
101 raise SeqError, "Cannot generate negative oligo length: #{length}" if length <= 0
104 when :dna then alph = DNA
105 when :rna then alph = RNA
106 when :protein then alph = PROTEIN
108 raise SeqError, "Unknown sequence type: #{type}"
113 (1 .. length).each do
116 oligos.each do |oligo|
128 # Initialize a sequence object with the following arguments:
129 # - seq_name: Name of the sequence.
130 # - seq: The sequence.
131 # - type: The sequence type - DNA, RNA, or protein
132 # - qual: An Illumina type quality scores string.
133 def initialize(seq_name = nil, seq = nil, type = nil, qual = nil)
140 raise SeqError, "Sequence length and score length mismatch: #{@seq.length} != #{@qual.length}" if @seq.length != @qual.length
144 # Method that guesses and returns the sequence type
145 # by inspecting the first 100 residues.
147 raise SeqError, "Guess failed: sequence is nil" if self.seq.nil?
149 case self.seq[0 ... 100].downcase
150 when /[flpqie]/ then return :protein
151 when /[u]/ then return :rna
156 # Method that guesses and sets the sequence type
157 # by inspecting the first 100 residues.
159 self.type = self.type_guess
163 # Returns the length of a sequence.
165 self.seq.nil? ? 0 : self.seq.length
170 # Return the number indels in a sequence.
172 regex = Regexp.new(/[#{Regexp.escape(INDELS.join(""))}]/)
173 self.seq.scan(regex).size
176 # Method to remove indels from seq and qual if qual.
179 self.seq.delete!(Regexp.escape(INDELS.join('')))
181 na_seq = NArray.to_na(self.seq, "byte")
182 na_qual = NArray.to_na(self.qual, "byte")
183 mask = NArray.byte(self.length)
186 mask += na_seq.eq(c.ord)
191 self.seq = na_seq[mask].to_s
192 self.qual = na_qual[mask].to_s
198 # Method that returns true is a given sequence type is DNA.
203 # Method that returns true is a given sequence type is RNA.
208 # Method that returns true is a given sequence type is protein.
210 self.type == :protein
213 # Method to transcribe DNA to RNA.
215 raise SeqError, "Cannot transcribe 0 length sequence" if self.length == 0
216 raise SeqError, "Cannot transcribe sequence type: #{self.type}" unless self.is_dna?
218 self.seq.tr!('Tt','Uu')
221 # Method to reverse-transcribe RNA to DNA.
223 raise SeqError, "Cannot reverse-transcribe 0 length sequence" if self.length == 0
224 raise SeqError, "Cannot reverse-transcribe sequence type: #{self.type}" unless self.is_rna?
226 self.seq.tr!('Uu','Tt')
229 # Method to translate a DNA sequence to protein.
230 def translate!(trans_tab = 11)
231 raise SeqError, "Sequence type must be 'dna' - not #{self.type}" unless self.type == :dna
232 raise SeqError, "Sequence length must be a multiplum of 3 - was: #{self.length}" unless (self.length % 3) == 0
236 codon_start_hash = TRANS_TAB11_START
237 codon_hash = TRANS_TAB11
239 raise SeqError, "Unknown translation table: #{trans_tab}"
242 codon = self.seq[0 ... 3].upcase
244 aa = codon_start_hash[codon]
246 raise SeqError, "Unknown start codon: #{codon}" if aa.nil?
252 while i < self.length
253 codon = self.seq[i ... i + 3].upcase
255 aa = codon_hash[codon]
257 raise SeqError, "Unknown codon: #{codon}" if aa.nil?
271 alias :to_protein! :translate!
273 def translate(trans_tab = 11)
274 self.dup.translate!(trans_tab)
277 alias :to_protein :translate
279 # Method that given a Seq entry returns a Biopieces record (a hash).
281 raise SeqError, "Missing seq_name" if self.seq_name.nil?
282 raise SeqError, "Missing seq" if self.seq.nil?
285 record[:SEQ_NAME] = self.seq_name
286 record[:SEQ] = self.seq
287 record[:SEQ_LEN] = self.length
288 record[:SCORES] = self.qual if self.qual
292 # Method that given a Seq entry returns a FASTA entry (a string).
293 def to_fasta(wrap = nil)
294 raise SeqError, "Missing seq_name" if self.seq_name.nil? or self.seq_name == ''
295 raise SeqError, "Missing seq" if self.seq.nil? or self.seq.empty?
297 seq_name = self.seq_name.to_s
301 seq.gsub!(/(.{#{wrap}})/) do |match|
308 ">" + seq_name + $/ + seq + $/
311 # Method that given a Seq entry returns a FASTQ entry (a string).
313 raise SeqError, "Missing seq_name" if self.seq_name.nil?
314 raise SeqError, "Missing seq" if self.seq.nil?
315 raise SeqError, "Missing qual" if self.qual.nil?
317 seq_name = self.seq_name.to_s
319 qual = self.qual.to_s
321 "@" + seq_name + $/ + seq + $/ + "+" + $/ + qual + $/
324 # Method that generates a unique key for a
325 # DNA sequence and return this key as a Fixnum.
329 self.seq.upcase.each_char do |char|
333 when 'A' then key |= 0
334 when 'C' then key |= 1
335 when 'G' then key |= 2
336 when 'T' then key |= 3
337 else raise SeqError, "Bad residue: #{char}"
344 # Method to reverse the sequence.
346 Seq.new(self.seq_name, self.seq.reverse, self.type, self.qual ? self.qual.reverse : self.qual)
349 # Method to reverse the sequence.
352 self.qual.reverse! if self.qual
356 # Method that complements sequence including ambiguity codes.
358 raise SeqError, "Cannot complement 0 length sequence" if self.length == 0
361 entry.seq_name = self.seq_name
362 entry.type = self.type
363 entry.qual = self.qual
366 entry.seq = self.seq.tr('AGCUTRYWSMKHDVBNagcutrywsmkhdvbn', 'TCGAAYRWSKMDHBVNtcgaayrwskmdhbvn')
368 entry.seq = self.seq.tr('AGCUTRYWSMKHDVBNagcutrywsmkhdvbn', 'UCGAAYRWSKMDHBVNucgaayrwskmdhbvn')
370 raise SeqError, "Cannot complement sequence type: #{self.type}"
376 # Method that complements sequence including ambiguity codes.
378 raise SeqError, "Cannot complement 0 length sequence" if self.length == 0
381 self.seq.tr!('AGCUTRYWSMKHDVBNagcutrywsmkhdvbn', 'TCGAAYRWSKMDHBVNtcgaayrwskmdhbvn')
383 self.seq.tr!('AGCUTRYWSMKHDVBNagcutrywsmkhdvbn', 'UCGAAYRWSKMDHBVNucgaayrwskmdhbvn')
385 raise SeqError, "Cannot complement sequence type: #{self.type}"
391 # Method to determine the Hamming Distance between
392 # two Sequence objects (case insensitive).
393 def hamming_distance(entry, options = nil)
394 if options and options[:ambiguity]
395 Hamming.distance(self.seq, entry.seq)
397 self.seq.upcase.hamming_distance(entry.seq.upcase)
401 # Method to determine the Edit Distance between
402 # two Sequence objects (case insensitive).
403 def edit_distance(entry)
404 Levenshtein.distance(self.seq, entry.seq)
407 # Method that generates a random sequence of a given length and type.
408 def generate(length, type)
409 raise SeqError, "Cannot generate sequence length < 1: #{length}" if length <= 0
412 when :dna then alph = DNA
413 when :rna then alph = RNA
414 when :protein then alph = PROTEIN
416 raise SeqError, "Unknown sequence type: #{type}"
419 seq_new = Array.new(length) { alph[rand(alph.size)] }.join("")
425 # Method to return a new Seq object with shuffled sequence.
427 Seq.new(self.seq_name, self.seq.split('').shuffle!.join, self.type, self.qual)
430 # Method to shuffle a sequence randomly inline.
432 self.seq = self.seq.split('').shuffle!.join
436 # Method to add two Seq objects.
438 new_entry = Seq.new()
439 new_entry.seq = self.seq + entry.seq
440 new_entry.type = self.type if self.type == entry.type
441 new_entry.qual = self.qual + entry.qual if self.qual and entry.qual
445 # Method to concatenate sequence entries.
447 raise SeqError, "sequences of different types" unless self.type == entry.type
448 raise SeqError, "qual is missing in one entry" unless self.qual.class == entry.qual.class
450 self.seq << entry.seq
451 self.qual << entry.qual unless entry.qual.nil?
456 # Index method for Seq objects.
459 entry.seq_name = self.seq_name
460 entry.seq = self.seq[*args]
461 entry.type = self.type
462 entry.qual = self.qual[*args] unless self.qual.nil?
467 # Index assignment method for Seq objects.
468 def []=(*args, entry)
469 self.seq[*args] = entry.seq[*args]
470 self.qual[*args] = entry.qual[*args] unless self.qual.nil?
475 # Method that returns a subsequence of from a given start position
476 # and of a given length.
477 def subseq(start, length = self.length - start)
478 raise SeqError, "subsequence start: #{start} < 0" if start < 0
479 raise SeqError, "subsequence length: #{length} < 0" if length < 0
480 raise SeqError, "subsequence start + length > Seq.length: #{start} + #{length} > #{self.length}" if start + length > self.length
484 qual = "" unless self.qual.nil?
486 stop = start + length - 1
488 seq = self.seq[start .. stop]
489 qual = self.qual[start .. stop] unless self.qual.nil?
492 seq_name = self.seq_name.nil? ? nil : self.seq_name.dup
494 Seq.new(seq_name, seq, self.type, qual)
497 # Method that replaces a sequence with a subsequence from a given start position
498 # and of a given length.
499 def subseq!(start, length = self.length - start)
500 s = subseq(start, length)
502 self.seq_name = s.seq_name
510 # Method that returns a subsequence of a given length
511 # beginning at a random position.
512 def subseq_rand(length)
513 if self.length - length + 1 == 0
516 start = rand(self.length - length + 1)
519 self.subseq(start, length)
522 # Method that returns the residue compositions of a sequence in
523 # a hash where the key is the residue and the value is the residue
528 self.seq.upcase.each_char do |char|
535 # Method that returns the percentage of hard masked residues
536 # or N's in a sequence.
538 ((self.seq.upcase.scan("N").size.to_f / (self.len - self.indels).to_f) * 100).round(2)
541 # Method that returns the percentage of soft masked residues
542 # or lower cased residues in a sequence.
544 ((self.seq.scan(/[a-z]/).size.to_f / (self.len - self.indels).to_f) * 100).round(2)
547 # Hard masks sequence residues where the corresponding quality score
548 # is below a given cutoff.
549 def mask_seq_hard!(cutoff)
550 raise SeqError, "seq is nil" if self.seq.nil?
551 raise SeqError, "qual is nil" if self.qual.nil?
552 raise SeqError, "cufoff value: #{cutoff} out of range #{SCORE_MIN} .. #{SCORE_MAX}" unless (SCORE_MIN .. SCORE_MAX).include? cutoff
554 na_seq = NArray.to_na(self.seq, "byte")
555 na_qual = NArray.to_na(self.qual, "byte")
556 mask = (na_qual - SCORE_BASE) < cutoff
557 mask *= na_seq.ne("-".ord)
559 na_seq[mask] = 'N'.ord
561 self.seq = na_seq.to_s
566 # Soft masks sequence residues where the corresponding quality score
567 # is below a given cutoff.
568 def mask_seq_soft!(cutoff)
569 raise SeqError, "seq is nil" if self.seq.nil?
570 raise SeqError, "qual is nil" if self.qual.nil?
571 raise SeqError, "cufoff value: #{cutoff} out of range #{SCORE_MIN} .. #{SCORE_MAX}" unless (SCORE_MIN .. SCORE_MAX).include? cutoff
573 na_seq = NArray.to_na(self.seq, "byte")
574 na_qual = NArray.to_na(self.qual, "byte")
575 mask = (na_qual - SCORE_BASE) < cutoff
576 mask *= na_seq.ne("-".ord)
578 na_seq[mask] ^= ' '.ord
580 self.seq = na_seq.to_s
585 # Method that determines if a quality score string can be
586 # absolutely identified as base 33.
588 self.qual.match(/[!-:]/) ? true : false
591 # Method that determines if a quality score string may be base 64.
593 self.qual.match(/[K-h]/) ? true : false
596 # Method to determine if a quality score is valid accepting only 0-40 range.
597 def qual_valid?(encoding)
598 raise SeqError, "Missing qual" if self.qual.nil?
601 when :base_33 then return true if self.qual.match(/^[!-I]*$/)
602 when :base_64 then return true if self.qual.match(/^[@-h]*$/)
603 else raise SeqError, "unknown quality score encoding: #{encoding}"
609 # Method to coerce quality scores to be within the 0-40 range.
610 def qual_coerce!(encoding)
611 raise SeqError, "Missing qual" if self.qual.nil?
614 when :base_33 then self.qual.tr!("[J-~]", "I")
615 when :base_64 then self.qual.tr!("[i-~]", "h")
616 else raise SeqError, "unknown quality score encoding: #{encoding}"
622 # Method to convert quality scores.
623 def qual_convert!(from, to)
624 raise SeqError, "unknown quality score encoding: #{from}" unless from == :base_33 or from == :base_64
625 raise SeqError, "unknown quality score encoding: #{to}" unless to == :base_33 or to == :base_64
627 if from == :base_33 and to == :base_64
628 na_qual = NArray.to_na(self.qual, "byte")
630 self.qual = na_qual.to_s
631 elsif from == :base_64 and to == :base_33
632 self.qual.tr!("[;-?]", "@") # Handle negative Solexa values from -5 to -1 (set these to 0).
633 na_qual = NArray.to_na(self.qual, "byte")
635 self.qual = na_qual.to_s
641 # Method to calculate and return the mean quality score.
643 raise SeqError, "Missing qual in entry" if self.qual.nil?
645 na_qual = NArray.to_na(self.qual, "byte")
646 na_qual -= SCORE_BASE
651 # Method to find open reading frames (ORFs).
652 def each_orf(size_min, size_max, start_codons, stop_codons, pick_longest = false)
656 regex_start = Regexp.new(start_codons.join('|'), true)
657 regex_stop = Regexp.new(stop_codons.join('|'), true)
659 while pos_beg and pos_beg < self.length - size_min
660 if pos_beg = self.seq.index(regex_start, pos_beg)
661 if pos_end = self.seq.index(regex_stop, pos_beg)
662 length = (pos_end - pos_beg) + 3
665 if size_min <= length and length <= size_max
666 subseq = self.subseq(pos_beg, length)
668 orfs << [subseq, pos_beg, pos_end + 3]
680 orfs.each { |orf| orf_hash[orf.last] = orf unless orf_hash[orf.last] }
682 orfs = orf_hash.values
686 orfs.each { |orf| yield orf }