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 # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
25 require 'maasha/patternmatcher'
27 require 'maasha/backtrack'
28 require 'maasha/digest'
30 #require 'maasha/patscan'
35 PROTEIN = %w[f l s y c w p h q r i m t n k v a d e g]
38 # Quality scores bases
44 # Error class for all exceptions to do with Seq.
45 class SeqError < StandardError; end
49 include PatternMatcher
53 attr_accessor :seq_name, :seq, :type, :qual
55 # Class method to instantiate a new Sequence object given
57 def self.new_bp(record)
58 seq_name = record[:SEQ_NAME]
60 type = record[:SEQ_TYPE]
61 qual = record[:SCORES]
63 self.new(seq_name, seq, type, qual)
66 # Class method that generates all possible oligos of a specifed length and type.
67 def self.generate_oligos(length, type)
68 raise SeqError, "Cannot generate negative oligo length: #{length}" if length <= 0
71 when /dna/ then alph = DNA
72 when /rna/ then alph = RNA
73 when /protein/ then alph = PROTEIN
75 raise SeqError, "Unknown sequence type: #{type}"
83 oligos.each do |oligo|
95 # Initialize a sequence object with the following arguments:
96 # - seq_name: Name of the sequence.
97 # - seq: The sequence.
98 # - type: The sequence type - DNA, RNA, or protein
99 # - qual: An Illumina type quality scores string.
100 def initialize(seq_name = nil, seq = nil, type = nil, qual = nil)
107 # Method that guesses and returns the sequence type
108 # by inspecting the first 100 residues.
110 raise SeqError, "Guess failed: sequence is nil" if self.seq.nil?
112 case self.seq[0 ... 100].downcase
113 when /[flpqie]/ then return "protein"
114 when /[u]/ then return "rna"
119 # Method that guesses and sets the sequence type
120 # by inspecting the first 100 residues.
122 self.type = self.type_guess
125 # Returns the length of a sequence.
127 self.seq.nil? ? 0 : self.seq.length
132 # Return the number indels in a sequence.
134 regex = Regexp.new(/[#{Regexp.escape(INDELS.join(""))}]/)
135 self.seq.scan(regex).size
138 # Method to remove indels from seq and qual if qual.
141 self.seq.delete!(Regexp.escape(INDELS.join('')))
143 na_seq = NArray.to_na(self.seq, "byte")
144 na_qual = NArray.to_na(self.qual, "byte")
145 mask = NArray.byte(self.length)
148 mask += na_seq.eq(c.ord)
153 self.seq = na_seq[mask].to_s
154 self.qual = na_qual[mask].to_s
160 # Method that returns true is a given sequence type is DNA.
165 # Method that returns true is a given sequence type is RNA.
170 # Method that returns true is a given sequence type is protein.
172 self.type == 'protein'
175 # Method to transcribe DNA to RNA.
177 raise SeqError, "Cannot transcribe 0 length sequence" if self.length == 0
178 raise SeqError, "Cannot transcribe sequence type: #{self.type}" unless self.is_dna?
180 self.seq.tr!('Tt','Uu')
183 # Method to reverse-transcribe RNA to DNA.
185 raise SeqError, "Cannot reverse-transcribe 0 length sequence" if self.length == 0
186 raise SeqError, "Cannot reverse-transcribe sequence type: #{self.type}" unless self.is_rna?
189 self.seq.tr!('Uu','Tt')
192 # Method that given a Seq entry returns a Biopieces record (a hash).
194 raise SeqError, "Missing seq_name" if self.seq_name.nil?
195 raise SeqError, "Missing seq" if self.seq.nil?
198 record[:SEQ_NAME] = self.seq_name
199 record[:SEQ] = self.seq
200 record[:SEQ_LEN] = self.length
201 record[:SCORES] = self.qual if self.qual
205 # Method that given a Seq entry returns a FASTA entry (a string).
206 def to_fasta(wrap = nil)
207 raise SeqError, "Missing seq_name" if self.seq_name.nil? or self.seq_name == ''
208 raise SeqError, "Missing seq" if self.seq.nil? or self.seq.empty?
210 seq_name = self.seq_name.to_s
214 seq.gsub!(/(.{#{wrap}})/) do |match|
221 ">" + seq_name + $/ + seq + $/
224 # Method that given a Seq entry returns a FASTQ entry (a string).
226 raise SeqError, "Missing seq_name" if self.seq_name.nil?
227 raise SeqError, "Missing seq" if self.seq.nil?
228 raise SeqError, "Missing qual" if self.qual.nil?
230 seq_name = self.seq_name.to_s
232 qual = self.qual.to_s
234 "@" + seq_name + $/ + seq + $/ + "+" + $/ + qual + $/
237 # Method that generates a unique key for a
238 # DNA sequence and return this key as a Fixnum.
242 self.seq.upcase.each_char do |char|
246 when 'A' then key |= 0
247 when 'C' then key |= 1
248 when 'G' then key |= 2
249 when 'T' then key |= 3
250 else raise SeqError, "Bad residue: #{char}"
257 # Method to reverse complement sequence.
258 def reverse_complement
264 alias :revcomp :reverse_complement
266 # Method to reverse the sequence.
269 self.qual.reverse! if self.qual
273 # Method that complements sequence including ambiguity codes.
275 raise SeqError, "Cannot complement 0 length sequence" if self.length == 0
278 self.seq.tr!('AGCUTRYWSMKHDVBNagcutrywsmkhdvbn', 'TCGAAYRWSKMDHBVNtcgaayrwskmdhbvn')
280 self.seq.tr!('AGCUTRYWSMKHDVBNagcutrywsmkhdvbn', 'UCGAAYRWSKMDHBVNucgaayrwskmdhbvn')
282 raise SeqError, "Cannot complement sequence type: #{self.type}"
286 # Method to determine the Hamming Distance between
287 # two Sequence objects (case insensitive).
288 def hamming_distance(seq)
289 self.seq.upcase.hamming_distance(seq.seq.upcase)
292 # Method that generates a random sequence of a given length and type.
293 def generate(length, type)
294 raise SeqError, "Cannot generate sequence length < 1: #{length}" if length <= 0
304 raise SeqError, "Unknown sequence type: #{type}"
307 seq_new = Array.new(length) { alph[rand(alph.size)] }.join("")
309 self.type = type.downcase
313 # Method to shuffle a sequence readomly inline.
315 self.seq = self.seq.split('').shuffle!.join
319 # Method that returns a subsequence of from a given start position
320 # and of a given length.
321 def subseq(start, length = self.length - start)
322 raise SeqError, "subsequence start: #{start} < 0" if start < 0
323 raise SeqError, "subsequence length: #{length} < 1" if length <= 0
324 raise SeqError, "subsequence start + length > Seq.length: #{start} + #{length} > #{self.length}" if start + length > self.length
326 stop = start + length - 1
328 seq = self.seq[start .. stop]
329 qual = self.qual[start .. stop] unless self.qual.nil?
331 Seq.new(self.seq_name, seq, self.type, qual)
334 # Method that replaces a sequence with a subsequence from a given start position
335 # and of a given length.
336 def subseq!(start, length = self.length - start)
337 raise SeqError, "subsequence start: #{start} < 0" if start < 0
338 raise SeqError, "subsequence length: #{length} < 1" if length <= 0
339 raise SeqError, "subsequence start + length > Seq.length: #{start} + #{length} > #{self.length}" if start + length > self.length
341 stop = start + length - 1
343 self.seq = self.seq[start .. stop]
344 self.qual = self.qual[start .. stop] unless self.qual.nil?
347 # Method that returns a subsequence of a given length
348 # beginning at a random position.
349 def subseq_rand(length)
350 if self.length - length + 1 == 0
353 start = rand(self.length - length + 1)
356 self.subseq(start, length)
359 def quality_trim_right(min)
360 raise SeqError, "no sequence" if self.seq.nil?
361 raise SeqError, "no quality score" if self.qual.nil?
362 raise SeqError, "minimum value: #{min} out of range #{SCORE_MIN} .. #{SCORE_MAX}" unless (SCORE_MIN .. SCORE_MAX).include? min
364 regex_right = Regexp.new("[#{(SCORE_ILLUMINA).chr}-#{(SCORE_ILLUMINA + min).chr}]+$")
366 self.qual.match(regex_right) do |m|
367 self.subseq!(0, $`.length) if $`.length > 0
373 def quality_trim_left(min)
374 raise SeqError, "no sequence" if self.seq.nil?
375 raise SeqError, "no quality score" if self.qual.nil?
376 raise SeqError, "minimum value: #{min} out of range #{SCORE_MIN} .. #{SCORE_MAX}" unless (SCORE_MIN .. SCORE_MAX).include? min
378 regex_left = Regexp.new("^[#{(SCORE_ILLUMINA).chr}-#{(SCORE_ILLUMINA + min).chr}]+")
380 self.qual.match(regex_left) do |m|
381 self.subseq!(m.to_s.length, self.length - m.to_s.length) if self.length - m.to_s.length > 0
387 def quality_trim(min)
388 self.quality_trim_right(min)
389 self.quality_trim_left(min)
393 # Method that returns the residue compositions of a sequence in
394 # a hash where the key is the residue and the value is the residue
399 self.seq.upcase.each_char do |char|
406 # Method that returns the length of the longest homopolymeric stretch
407 # found in a sequence.
408 def homopol_max(min = 1)
409 return 0 if self.seq.nil? or self.seq.empty?
413 self.seq.upcase.scan(/A{#{min},}|T{#{min},}|G{#{min},}|C{#{min},}|N{#{min},}/) do |match|
415 min = match.size > min ? match.size : min
418 return 0 unless found
423 # Method that returns the percentage of hard masked residues
424 # or N's in a sequence.
426 ((self.seq.upcase.scan("N").size.to_f / (self.len - self.indels).to_f) * 100).round(2)
429 # Method that returns the percentage of soft masked residues
430 # or lower cased residues in a sequence.
432 ((self.seq.scan(/[a-z]/).size.to_f / (self.len - self.indels).to_f) * 100).round(2)
435 # Hard masks sequence residues where the corresponding quality score
436 # is below a given cutoff.
437 def mask_seq_hard_old(cutoff)
438 seq = self.seq.upcase
442 scores.each_char do |score|
443 seq[i] = 'N' if score.ord - SCORE_ILLUMINA < cutoff
450 # Hard masks sequence residues where the corresponding quality score
451 # is below a given cutoff.
452 def mask_seq_hard!(cutoff)
453 raise SeqError, "seq is nil" if self.seq.nil?
454 raise SeqError, "qual is nil" if self.qual.nil?
455 raise SeqError, "cufoff value: #{cutoff} out of range #{SCORE_MIN} .. #{SCORE_MAX}" unless (SCORE_MIN .. SCORE_MAX).include? cutoff
457 na_seq = NArray.to_na(self.seq, "byte")
458 na_qual = NArray.to_na(self.qual, "byte")
459 mask = (na_qual - SCORE_ILLUMINA) < cutoff
460 mask *= na_seq.ne("-".ord)
462 na_seq[mask] = 'N'.ord
464 self.seq = na_seq.to_s
469 # Soft masks sequence residues where the corresponding quality score
470 # is below a given cutoff.
471 def mask_seq_soft!(cutoff)
472 raise SeqError, "seq is nil" if self.seq.nil?
473 raise SeqError, "qual is nil" if self.qual.nil?
474 raise SeqError, "cufoff value: #{cutoff} out of range #{SCORE_MIN} .. #{SCORE_MAX}" unless (SCORE_MIN .. SCORE_MAX).include? cutoff
476 na_seq = NArray.to_na(self.seq, "byte")
477 na_qual = NArray.to_na(self.qual, "byte")
478 mask = (na_qual - SCORE_ILLUMINA) < cutoff
479 mask *= na_seq.ne("-".ord)
481 na_seq[mask] ^= ' '.ord
483 self.seq = na_seq.to_s
488 # Method to convert the quality scores from a specified base
490 def convert_phred2illumina!
491 self.qual.gsub!(/./) do |score|
492 score_phred = score.ord - SCORE_PHRED
493 raise SeqError, "Bad Phred score: #{score} (#{score_phred})" unless (0 .. 41).include? score_phred
494 score_illumina = score_phred + SCORE_ILLUMINA
495 score = score_illumina.chr
499 # Method to convert the quality scores from Solexa odd/ratio to
501 def convert_solexa2illumina!
502 self.qual.gsub!(/./) do |score|
503 score = solexa_char2illumina_char(score)
509 # Method to convert a Solexa score (odd ratio) to
510 # a phred (probability) integer score.
511 def solexa2phred(score)
512 (10.0 * Math.log(10.0 ** (score / 10.0) + 1.0, 10)).to_i
515 # Method to convert a Solexa score encoded using base
516 # 64 ASCII to a Phred score encoded using base 64 ASCII.
517 def solexa_char2illumina_char(char)
518 score_solexa = char.ord - 64
519 score_phred = solexa2phred(score_solexa)
520 (score_phred + 64).chr