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'
33 PROTEIN = %w[f l s y c w p h q r i m t n k v a d e g]
36 # Translation table 11
37 # (http://www.ncbi.nlm.nih.gov/Taxonomy/taxonomyhome.html/index.cgi?chapter=cgencodes#SG11)
38 # AAs = FFLLSSSSYY**CC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG
39 # Starts = ---M---------------M------------MMMM---------------M------------
40 # Base1 = TTTTTTTTTTTTTTTTCCCCCCCCCCCCCCCCAAAAAAAAAAAAAAAAGGGGGGGGGGGGGGGG
41 # Base2 = TTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGG
42 # Base3 = TCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAG
44 "TTG" => "M", "CTG" => "M", "ATT" => "M", "ATC" => "M",
45 "ATA" => "M", "ATG" => "M", "GTG" => "M"
49 "TTT" => "F", "TCT" => "S", "TAT" => "Y", "TGT" => "C",
50 "TTC" => "F", "TCC" => "S", "TAC" => "Y", "TGC" => "C",
51 "TTA" => "L", "TCA" => "S", "TAA" => "*", "TGA" => "*",
52 "TTG" => "L", "TCG" => "S", "TAG" => "*", "TGG" => "W",
53 "CTT" => "L", "CCT" => "P", "CAT" => "H", "CGT" => "R",
54 "CTC" => "L", "CCC" => "P", "CAC" => "H", "CGC" => "R",
55 "CTA" => "L", "CCA" => "P", "CAA" => "Q", "CGA" => "R",
56 "CTG" => "L", "CCG" => "P", "CAG" => "Q", "CGG" => "R",
57 "ATT" => "I", "ACT" => "T", "AAT" => "N", "AGT" => "S",
58 "ATC" => "I", "ACC" => "T", "AAC" => "N", "AGC" => "S",
59 "ATA" => "I", "ACA" => "T", "AAA" => "K", "AGA" => "R",
60 "ATG" => "M", "ACG" => "T", "AAG" => "K", "AGG" => "R",
61 "GTT" => "V", "GCT" => "A", "GAT" => "D", "GGT" => "G",
62 "GTC" => "V", "GCC" => "A", "GAC" => "D", "GGC" => "G",
63 "GTA" => "V", "GCA" => "A", "GAA" => "E", "GGA" => "G",
64 "GTG" => "V", "GCG" => "A", "GAG" => "E", "GGG" => "G"
67 # Quality scores bases
72 # Error class for all exceptions to do with Seq.
73 class SeqError < StandardError; end
79 attr_accessor :seq_name, :seq, :type, :qual
81 # Class method to instantiate a new Sequence object given
83 def self.new_bp(record)
84 seq_name = record[:SEQ_NAME]
86 type = record[:SEQ_TYPE]
87 qual = record[:SCORES]
89 self.new(seq_name, seq, type, qual)
92 # Class method that generates all possible oligos of a specifed length and type.
93 def self.generate_oligos(length, type)
94 raise SeqError, "Cannot generate negative oligo length: #{length}" if length <= 0
97 when /dna/ then alph = DNA
98 when /rna/ then alph = RNA
99 when /protein/ then alph = PROTEIN
101 raise SeqError, "Unknown sequence type: #{type}"
106 (1 .. length).each do
109 oligos.each do |oligo|
121 # Initialize a sequence object with the following arguments:
122 # - seq_name: Name of the sequence.
123 # - seq: The sequence.
124 # - type: The sequence type - DNA, RNA, or protein
125 # - qual: An Illumina type quality scores string.
126 def initialize(seq_name = nil, seq = nil, type = nil, qual = nil)
133 # Method that guesses and returns the sequence type
134 # by inspecting the first 100 residues.
136 raise SeqError, "Guess failed: sequence is nil" if self.seq.nil?
138 case self.seq[0 ... 100].downcase
139 when /[flpqie]/ then return "protein"
140 when /[u]/ then return "rna"
145 # Method that guesses and sets the sequence type
146 # by inspecting the first 100 residues.
148 self.type = self.type_guess
151 # Returns the length of a sequence.
153 self.seq.nil? ? 0 : self.seq.length
158 # Return the number indels in a sequence.
160 regex = Regexp.new(/[#{Regexp.escape(INDELS.join(""))}]/)
161 self.seq.scan(regex).size
164 # Method to remove indels from seq and qual if qual.
167 self.seq.delete!(Regexp.escape(INDELS.join('')))
169 na_seq = NArray.to_na(self.seq, "byte")
170 na_qual = NArray.to_na(self.qual, "byte")
171 mask = NArray.byte(self.length)
174 mask += na_seq.eq(c.ord)
179 self.seq = na_seq[mask].to_s
180 self.qual = na_qual[mask].to_s
186 # Method that returns true is a given sequence type is DNA.
191 # Method that returns true is a given sequence type is RNA.
196 # Method that returns true is a given sequence type is protein.
198 self.type == 'protein'
201 # Method to transcribe DNA to RNA.
203 raise SeqError, "Cannot transcribe 0 length sequence" if self.length == 0
204 raise SeqError, "Cannot transcribe sequence type: #{self.type}" unless self.is_dna?
206 self.seq.tr!('Tt','Uu')
209 # Method to reverse-transcribe RNA to DNA.
211 raise SeqError, "Cannot reverse-transcribe 0 length sequence" if self.length == 0
212 raise SeqError, "Cannot reverse-transcribe sequence type: #{self.type}" unless self.is_rna?
215 self.seq.tr!('Uu','Tt')
218 # Method to translate a DNA sequence to protein.
219 def translate!(trans_tab = 11)
220 raise SeqError, "Sequence type must be 'dna' - not #{self.type}" unless self.type == 'dna'
221 raise SeqError, "Sequence length must be a multiplum of 3 - was: #{self.length}" unless (self.length % 3) == 0
225 codon_start_hash = TRANS_TAB11_START
226 codon_hash = TRANS_TAB11
228 raise SeqError, "Unknown translation table: #{trans_tab}"
231 codon = self.seq[0 ... 3].upcase
233 aa = codon_start_hash[codon]
235 raise SeqError, "Unknown start codon: #{codon}" if aa.nil?
241 while i < self.length
242 codon = self.seq[i ... i + 3].upcase
244 aa = codon_hash[codon]
246 raise SeqError, "Unknown codon: #{codon}" if aa.nil?
255 self.type = "protein"
260 alias :to_protein! :translate!
262 def translate(trans_tab = 11)
263 self.dup.translate!(trans_tab)
266 alias :to_protein :translate
268 # Method that given a Seq entry returns a Biopieces record (a hash).
270 raise SeqError, "Missing seq_name" if self.seq_name.nil?
271 raise SeqError, "Missing seq" if self.seq.nil?
274 record[:SEQ_NAME] = self.seq_name
275 record[:SEQ] = self.seq
276 record[:SEQ_LEN] = self.length
277 record[:SCORES] = self.qual if self.qual
281 # Method that given a Seq entry returns a FASTA entry (a string).
282 def to_fasta(wrap = nil)
283 raise SeqError, "Missing seq_name" if self.seq_name.nil? or self.seq_name == ''
284 raise SeqError, "Missing seq" if self.seq.nil? or self.seq.empty?
286 seq_name = self.seq_name.to_s
290 seq.gsub!(/(.{#{wrap}})/) do |match|
297 ">" + seq_name + $/ + seq + $/
300 # Method that given a Seq entry returns a FASTQ entry (a string).
302 raise SeqError, "Missing seq_name" if self.seq_name.nil?
303 raise SeqError, "Missing seq" if self.seq.nil?
304 raise SeqError, "Missing qual" if self.qual.nil?
306 seq_name = self.seq_name.to_s
308 qual = self.qual.to_s
310 "@" + seq_name + $/ + seq + $/ + "+" + $/ + qual + $/
313 # Method that generates a unique key for a
314 # DNA sequence and return this key as a Fixnum.
318 self.seq.upcase.each_char do |char|
322 when 'A' then key |= 0
323 when 'C' then key |= 1
324 when 'G' then key |= 2
325 when 'T' then key |= 3
326 else raise SeqError, "Bad residue: #{char}"
333 # Method to reverse complement sequence.
334 def reverse_complement
340 alias :revcomp :reverse_complement
342 # Method to reverse the sequence.
345 self.qual.reverse! if self.qual
349 # Method that complements sequence including ambiguity codes.
351 raise SeqError, "Cannot complement 0 length sequence" if self.length == 0
354 self.seq.tr!('AGCUTRYWSMKHDVBNagcutrywsmkhdvbn', 'TCGAAYRWSKMDHBVNtcgaayrwskmdhbvn')
356 self.seq.tr!('AGCUTRYWSMKHDVBNagcutrywsmkhdvbn', 'UCGAAYRWSKMDHBVNucgaayrwskmdhbvn')
358 raise SeqError, "Cannot complement sequence type: #{self.type}"
362 # Method to determine the Hamming Distance between
363 # two Sequence objects (case insensitive).
364 def hamming_distance(seq)
365 self.seq.upcase.hamming_distance(seq.seq.upcase)
368 # Method that generates a random sequence of a given length and type.
369 def generate(length, type)
370 raise SeqError, "Cannot generate sequence length < 1: #{length}" if length <= 0
380 raise SeqError, "Unknown sequence type: #{type}"
383 seq_new = Array.new(length) { alph[rand(alph.size)] }.join("")
385 self.type = type.downcase
389 # Method to shuffle a sequence readomly inline.
391 self.seq = self.seq.split('').shuffle!.join
395 # Method that returns a subsequence of from a given start position
396 # and of a given length.
397 def subseq(start, length = self.length - start)
398 raise SeqError, "subsequence start: #{start} < 0" if start < 0
399 raise SeqError, "subsequence length: #{length} < 0" if length < 0
400 raise SeqError, "subsequence start + length > Seq.length: #{start} + #{length} > #{self.length}" if start + length > self.length
404 qual = "" unless self.qual.nil?
406 stop = start + length - 1
408 seq = self.seq[start .. stop]
409 qual = self.qual[start .. stop] unless self.qual.nil?
412 Seq.new(self.seq_name, seq, self.type, qual) # TODO changed self.seq_name.dup to self.seq_name -> consequence?
415 # Method that replaces a sequence with a subsequence from a given start position
416 # and of a given length.
417 def subseq!(start, length = self.length - start)
418 s = subseq(start, length)
420 self.seq_name = s.seq_name
428 # Method that returns a subsequence of a given length
429 # beginning at a random position.
430 def subseq_rand(length)
431 if self.length - length + 1 == 0
434 start = rand(self.length - length + 1)
437 self.subseq(start, length)
440 # Method that returns the residue compositions of a sequence in
441 # a hash where the key is the residue and the value is the residue
446 self.seq.upcase.each_char do |char|
453 # Method that returns the length of the longest homopolymeric stretch
454 # found in a sequence.
455 def homopol_max(min = 1)
456 return 0 if self.seq.nil? or self.seq.empty?
460 self.seq.upcase.scan(/A{#{min},}|T{#{min},}|G{#{min},}|C{#{min},}|N{#{min},}/) do |match|
462 min = match.size > min ? match.size : min
465 return 0 unless found
470 # Method that returns the percentage of hard masked residues
471 # or N's in a sequence.
473 ((self.seq.upcase.scan("N").size.to_f / (self.len - self.indels).to_f) * 100).round(2)
476 # Method that returns the percentage of soft masked residues
477 # or lower cased residues in a sequence.
479 ((self.seq.scan(/[a-z]/).size.to_f / (self.len - self.indels).to_f) * 100).round(2)
482 # Hard masks sequence residues where the corresponding quality score
483 # is below a given cutoff.
484 def mask_seq_hard_old(cutoff)
485 seq = self.seq.upcase
489 scores.each_char do |score|
490 seq[i] = 'N' if score.ord - SCORE_BASE < cutoff
497 # Hard masks sequence residues where the corresponding quality score
498 # is below a given cutoff.
499 def mask_seq_hard!(cutoff)
500 raise SeqError, "seq is nil" if self.seq.nil?
501 raise SeqError, "qual is nil" if self.qual.nil?
502 raise SeqError, "cufoff value: #{cutoff} out of range #{SCORE_MIN} .. #{SCORE_MAX}" unless (SCORE_MIN .. SCORE_MAX).include? cutoff
504 na_seq = NArray.to_na(self.seq, "byte")
505 na_qual = NArray.to_na(self.qual, "byte")
506 mask = (na_qual - SCORE_BASE) < cutoff
507 mask *= na_seq.ne("-".ord)
509 na_seq[mask] = 'N'.ord
511 self.seq = na_seq.to_s
516 # Soft masks sequence residues where the corresponding quality score
517 # is below a given cutoff.
518 def mask_seq_soft!(cutoff)
519 raise SeqError, "seq is nil" if self.seq.nil?
520 raise SeqError, "qual is nil" if self.qual.nil?
521 raise SeqError, "cufoff value: #{cutoff} out of range #{SCORE_MIN} .. #{SCORE_MAX}" unless (SCORE_MIN .. SCORE_MAX).include? cutoff
523 na_seq = NArray.to_na(self.seq, "byte")
524 na_qual = NArray.to_na(self.qual, "byte")
525 mask = (na_qual - SCORE_BASE) < cutoff
526 mask *= na_seq.ne("-".ord)
528 na_seq[mask] ^= ' '.ord
530 self.seq = na_seq.to_s
535 # Method that determines if a quality score string can be
536 # absolutely identified as base 33.
538 self.qual.match(/[!-:]/)
541 # Method that determines if a quality score string can be
542 # absolutely identified as base 64.
544 self.qual.match(/[K-h]/)
547 # Method to convert quality scores inbetween formats.
548 # Sanger base 33, range 0-40
549 # 454 base 64, range 0-40
550 # Solexa base 64, range -5-40
551 # Illumina13 base 64, range 0-40
552 # Illumina15 base 64, range 3-40
553 # Illumina18 base 33, range 0-41
554 def convert_scores!(from, to)
556 na_qual = NArray.to_na(self.qual, "byte")
559 when "sanger" then na_qual -= 33
560 when "454" then na_qual -= 64
561 when "solexa" then na_qual -= 64
562 when "illumina13" then na_qual -= 64
563 when "illumina15" then na_qual -= 64
564 when "illumina18" then na_qual -= 33
565 else raise SeqError, "unknown quality score encoding: #{from}"
569 when "sanger" then na_qual += 33
570 when "454" then na_qual += 64
571 when "solexa" then na_qual += 64
572 when "illumina13" then na_qual += 64
573 when "illumina15" then na_qual += 64
574 when "illumina18" then na_qual += 33
575 else raise SeqError, "unknown quality score encoding: #{from}"
578 self.qual = na_qual.to_s
584 # Method to calculate and return the mean quality score.
586 raise SeqError, "Missing qual in entry" if self.qual.nil?
588 na_qual = NArray.to_na(self.qual, "byte")
589 na_qual -= SCORE_BASE
593 # Method to find open reading frames (ORFs).
594 def each_orf(size_min, size_max, start_codons, stop_codons, pick_longest = false)
598 regex_start = Regexp.new(start_codons.join('|'), true)
599 regex_stop = Regexp.new(stop_codons.join('|'), true)
601 while pos_beg and pos_beg < self.length - size_min
602 if pos_beg = self.seq.index(regex_start, pos_beg)
603 if pos_end = self.seq.index(regex_stop, pos_beg)
604 length = (pos_end - pos_beg) + 3
607 if size_min <= length and length <= size_max
608 subseq = self.subseq(pos_beg, length)
610 orfs << [subseq, pos_beg, pos_end + 3]
622 orfs.each { |orf| orf_hash[orf.last] = orf unless orf_hash[orf.last] }
624 orfs = orf_hash.values
628 orfs.each { |orf| yield orf }