ms-mascot 0.2.0 → 0.2.2

data/lib/ms/mascot/dat/proteins.rb

@@ -1,4 +1,76 @@
 require 'ms/mascot/dat/section'
 
-class Ms::Mascot::Dat::Proteins < Ms::Mascot::Dat::Section
+module Ms::Mascot::Dat
+  
+  # Proteins represent supplementary protein information in a dat file.
+  #
+  #   Content-Type: application/x-Mascot; name="proteins"
+  #   
+  #   "ZN711_HUMAN"=87153.77,"Zinc finger protein 711 (Zinc finger protein 6) - Homo sapiens (Human)"
+  #   "Y986_MYCTU"=27356.31,"Hypothetical ABC transporter ATP-binding protein Rv0986/MT1014 - Mycobacterium tuberculosis"
+  #   "Y5G0_ENCCU"=33509.30,"Hypothetical protein ECU05_1600/ECU11_0130 - Encephalitozoon cuniculi"
+  #
+  # Proteins is (almost) a standard Section and defines methods for convenient
+  # access.
+  class Proteins < Section
+    
+    # === Protein
+    #
+    # Represents protein data.
+    #
+    #   # 87153.77,"Zinc finger protein 711 (Zinc finger protein 6) - Homo sapiens (Human)"
+    #
+    #   index  example              meaning
+    #   0      87153.77             protein mass in Da
+    #   1      "Zinc finger..."     a description string
+    #
+    Protein = Struct.new(
+      :mass,
+      :description
+    )
+    
+    # A format string used to format parameters as a string.
+    TO_S_FORMAT = "\"%s\"=%s\n"
+    
+    class << self
+      
+      # Parses a new instance from str.  Special parsing is required to quickly
+      # remove the quotes from protein keys.
+      def parse(str, archive=nil)
+        params = {}
+        scanner = StringScanner.new(str)
+        
+        # skip whitespace and content type declaration
+        unless scanner.scan(Section::CONTENT_TYPE_REGEXP)
+          raise "unknown content type: #{content_type}"
+        end
+        section_name = scanner[1]
+        
+        # scan each pair removing quotes from keys
+        while true
+          scanner.skip(/"/)
+          break unless key = scanner.scan(/[^"]+/)
+          scanner.skip(/"\=/)
+          params[key] = scanner.scan(/[^\n]*/)
+          scanner.skip(/\n/)
+        end
+        
+        new(params, section_name, archive)
+      end
+    end
+    
+    # Returns a Protein for the specified protein id.
+    def protein(id)
+      parse_protein(data[id])
+    end 
+    
+    private
+    
+    # Parses a Protein from the protien data string.
+    def parse_protein(str)
+      return nil unless str
+      mass, description = str.split(',')
+      Protein.new(mass.to_f, description[1...-1])
+    end
+  end
 end

data/lib/ms/mascot/dat/query.rb

@@ -1,12 +1,147 @@
 require 'ms/mascot/dat/section'
+require 'ms/mascot/mgf/entry'
+require 'rack'
 
-class Ms::Mascot::Dat::Query < Ms::Mascot::Dat::Section
+module Ms::Mascot::Dat
   
-  attr_reader :index
+  # Query is a generic section for all queryN sections.  Query contains query
+  # data that has different meaning depending on the type of search performed.
+  # Here is data from an MS/MS search:
+  #
+  #   Content-Type: application/x-Mascot; name="query60"
+  #   
+  #   charge=3+
+  #   mass_min=50.175000
+  #   mass_max=1998.960000
+  #   int_min=0.0364
+  #   int_max=7366
+  #   num_vals=3411
+  #   num_used1=-1
+  #   Ions1=129.098825:384.8,187.070000:461.5...
+  #   ...
+  #
+  # Query is a standard Section and simply defines methods for convenient
+  # access.  See Section for parsing details.
+  class Query < Ms::Mascot::Dat::Section
   
-  def initialize(data={}, section_name=self.class.section_name)
-    super(data, section_name)
-    @index = section_name.strip[5..-1].to_i
-  end
+    module Utils
+      module_function
+      
+      # Scans an ion string for values, yielding each number as a string and the
+      # a flag signaling whether or not the number marks the end of a datapoint
+      # (ie the number is the intensity).
+      #
+      #   str = "\nReformatted Ions\n"
+      #   Query.scan_ions('1.23:4.56,7.8:9') do |num, end_point|
+      #     str << num
+      #     str << (end_point ? "\n" : " ")
+      #   end
+      #
+      #   str
+      #   # => %q{
+      #   # Reformatted Ions
+      #   # 1.23 4.56
+      #   # 7.8 9
+      #   # }
+      #
+      def scan_ions(str) # :yields: num, end_point
+        scanner = StringScanner.new(str)
+        while num = scanner.scan(/[^:,]+/)
+          if scanner.skip(/:/)
+            yield(num, false)
+          else
+            scanner.skip(/,/)
+            yield(num, true)
+          end 
+        end
+      end
+    
+      # Parses an ion string into a simple data array.  Parse ions requires
+      # data points be separated with a comma and mz/intensity values with a
+      # semicolon, but is tolerant to integer and floats.
+      #
+      #   Query.parse_ions('1.23:4.56,7.8:9')     # => [[1.23, 4.56], [7.8, 9]]
+      #
+      # All ions are cast to floats; see scan_ions for scanning the string
+      # values.
+      def parse_ions(str)
+        ions = []
+        current = []
+      
+        scan_ions(str) do |num, end_point|
+          current << num.to_f
+        
+          if end_point
+            ions << current
+            current = []
+          end
+        end
+        ions
+      end
+    end
+    
+    include Utils
+    
+    # Returns the query index for self (ie 60 when section_name is 'query60')
+    attr_reader :index
+  
+    def initialize(data={}, section_name=self.class.section_name, dat=nil)
+      super(data, section_name, dat)
+      data['title'] = Rack::Utils.unescape(data['title'].to_s)
+      @index = section_name.strip[5..-1].to_i
+      @ions=[]
+    end
+  
+    # Returns the nth ion string in self.
+    def ion_str(n=1)
+      data["Ions#{n}"]
+    end
+  
+    # Returns a simple array of the parsed nth ion string.
+    def ions(n=1)
+      @ions[n] ||= parse_ions(ion_str(n))
+    end
 
+    def title
+      data['title']
+    end
+
+    # allows access to values in data with method calls
+    #def method_missing(*args)
+    #  if args.size == 1 && (val = data[arg.to_s])
+    #    val
+    #  else
+    #    super(*args)
+    #  end
+    #end
+
+    # returns a Ms::Mascot::Mgf::Entry object.  
+    # pepmass may be a Numeric OR a PeptideHit object (extracting the pepmass
+    # by PeptideHit#peptide_mass + PeptideHit#delta_mass
+    # options are:
+    #
+    #     :valid_headers = true (default) | false
+    def to_mgf(pepmass, opts={})
+      opts = {:valid_headers => true}.merge(opts)
+      valid_headers = opts[:valid_headers]
+      header = {}
+      header['PEPMASS'] = 
+        if pepmass.is_a? Numeric
+          pepmass
+        else
+          hit = pepmass
+          hit.peptide_mass + hit.delta_mass
+        end
+      data.each_pair do |key,value|
+        up = key.to_s.upcase
+        next if key =~ /Ions/ 
+        next if valid_headers && !Ms::Mascot::Mgf::VALID_LOCAL_HEADERS.include?(up)
+        header[up] = value
+      end
+      # note that we sort the ions because I think I've seen files without
+      # them being sorted
+      Ms::Mascot::Mgf::Entry.new(header, self.ions.sort)
+    end
+
+  end
 end

data/lib/ms/mascot/dat/section.rb

@@ -30,7 +30,7 @@ module Ms
           # Parses a new instance from str.  Section after then content-type
           # declaration are parsed into the parameters hash.  Section follow
           # a simple "key=value\n" pattern.
-          def parse(str)
+          def parse(str, archive=nil)
             params = {}
             scanner = StringScanner.new(str)
             
@@ -42,12 +42,12 @@ module Ms
             
             # scan each pair.
             while key = scanner.scan(/[^=]+/)
-              scanner.skip(/=/)
+              scanner.skip(/\=/)
               params[key] = scanner.scan(/[^\n]*/)
               scanner.skip(/\n/)
             end
             
-            new(params, section_name)
+            new(params, section_name, archive)
           end
           
           # Returns the name of the section represented by this class.  Section
@@ -67,9 +67,13 @@ module Ms
         # The class section_name.
         attr_reader :section_name
         
-        def initialize(data={}, section_name=self.class.section_name)
+        # A backreference to the dat containing self.
+        attr_reader :dat
+        
+        def initialize(data={}, section_name=self.class.section_name, dat=nil)
           @data = data
           @section_name = section_name
+          @dat = dat
         end
         
         # Formats self as a string with the content-type header.
@@ -78,7 +82,7 @@ module Ms
 
 Content-Type: application/x-Mascot; name="#{section_name}"
 
-#{data.to_a.collect {|entry| TO_S_FORMAT % entry}.join}}
+#{data.to_a.collect {|entry| self.class::TO_S_FORMAT % entry}.join}}
         end
       end
     end

data/lib/ms/mascot/dat/summary.rb

@@ -1,8 +1,226 @@
 require 'ms/mascot/dat/section'
 
-# Summaries differ in their meaning depending on the type of search but the
-# content is in the same format.  The best way to add a sensible api and to
-# keep the basic archive lookup structure is to define modules that extend
-# a summary with, say an MS/MS ion search api.
-class Ms::Mascot::Dat::Summary < Ms::Mascot::Dat::Section
+module Ms::Mascot::Dat
+  
+  # Summary represent summary identification information in a dat file.
+  # Summaries differ in their meaning depending on the type of search but the
+  # content is in the same format.  Currently the APIs for each of these
+  # distinct searches are mashed together although a saner approach would be
+  # to separate them.
+  #
+  #   Content-Type: application/x-Mascot; name="summary"
+  #   
+  #   qmass1=497.265612
+  #   qexp1=498.272888,1+
+  #   qmatch1=5360
+  #   qplughole1=0.000000
+  #   qmass2=499.248736
+  #   qexp2=500.256012,1+
+  #   qmatch2=5759
+  #   qplughole2=16.873721
+  #   ...
+  #   h1=CH60_HUMAN,1.40e+03,0.48,61016.38
+  #   h1_text=60 kDa heat shock protein, mitochondrial precursor (Hsp60) (60 kDa chaperonin) (CPN60) (Heat shock 
+  #   h1_q1=-1
+  #   h1_q2=-1
+  #   ...
+  #   h1_q11=0,832.382767,-0.032939,302,309,6.00,APGFGDNR,16,0000000000,45.35,1,0000002000000000000,0,0,3481.990000
+  #   h1_q11_terms=K,K
+  #   h1_q12=0,843.506577,-0.034557,345,352,7.00,VGEVIVTK,24,0000000000,45.74,2,0001002000000000000,0,0,1662.450000
+  #   h1_q12_terms=K,D
+  #   ...
+  #
+  # Summary is a standard Section and simply defines methods for convenient
+  # access.  See Section for parsing details.
+  #
+  # === Interpretation
+  #
+  # Deciphering the protein hit information requires some cross-referencing with
+  # online results.  Note that each hit references each query.
+  #
+  #   hN=protein                       # protein hit N
+  #   hN_text=description              # description for hit N
+  #   hN_qM=-1                         # no peptide from query
+  #   hN_qM=query                      # match for hit N from query M
+  #   hN_qM=A,B:C,D                    # n and c-termini residues for each protein match
+  #
+  # See the ProteinHit and QueryHit structures for interpretation of the
+  # specific hit data.
+  #--
+  #
+  class Summary < Section
+    
+    # === ProteinHit
+    #
+    # Represents protein hit data, infered by inspection of the MS/MS sample
+    # results, esp {F981123.dat}[http://www.matrixscience.com/cgi/peptide_view.pl?file=../data/F981123.dat&query=2&hit=1&index=&px=1&section=5&ave_thresh=38].
+    #   
+    #   # str:  CH60_HUMAN,1.40e+03,0.48,61016.38
+    #   # desc: 60 kDa heat shock protein...
+    # 
+    #   index  example              meaning
+    #   0      CH60_HUMAN           id
+    #   1      1.40e+03             
+    #   2      0.48                 
+    #   3      61016.38             mass
+    #   4      60 kDa heat...       text
+    #
+    ProteinHit = Struct.new(
+      :id,
+      :unknown1,
+      :unknown2,
+      :mass,
+      :text,
+      :query_hits
+    )
+    
+    # Indicies of ProteinHit terms that will be cast to floats.
+    ProteinHitFloatIndicies = [1,2,3]
+    
+    # === QueryHit
+    #
+    # Represents query data, infered by inspection of the MS/MS sample
+    # results, esp {F981123.dat}[http://www.matrixscience.com/cgi/peptide_view.pl?file=../data/F981123.dat&query=2&hit=1&index=&px=1&section=5&ave_thresh=38].
+    #   
+    #   # str:   0,832.382767,-0.032939,302,309,6.00,APGFGDNR,16,0000000000,45.35,1,0000002000000000000,0,0,3481.990000
+    #   # terms: K,R
+    #
+    #   index  example              meaning
+    #   0      0                    n Missed Cleavages
+    #   1      832.382767           Monoisotopic mass of neutral peptide Mr(calc)
+    #   2      -0.032939            actual - theoretical delta mass
+    #   3      302                  peptide start index
+    #   4      309                  peptide end index
+    #   5      6.00
+    #   6      APGFGDNR             peptide sequence
+    #   7      16
+    #   8      0000000000           modification sites (including n,c residues; number indicates mod)
+    #   9      45.35                score
+    #   10     1
+    #   11     0000002000000000000
+    #   12     0
+    #   13     0
+    #   14     3481.990000
+    #   15     K                    nterm
+    #   16     R                    cterm
+    #
+    # The dat file is said to be generate by Mascot version 1.0, but the headers
+    # section records 2.1.119.
+    QueryHit = Struct.new(
+      :n_missed_cleavages,
+      :peptide_mass,
+      :delta_mass,
+      :peptide_start,
+      :peptide_end,
+      :unknown5,
+      :sequence,
+      :unknown7,
+      :modifications,
+      :score,
+      :unknown10,
+      :unknown11,
+      :unknown12,
+      :unknown13,
+      :unknown14,
+      :nterm,
+      :cterm
+    )
+    
+    # Indicies of QueryHit terms that will be cast to floats.
+    QueryHitFloatIndicies = [1,2,5,9,14]
+    
+    # Indicies of QueryHit terms that will be cast to integers.
+    QueryHitIntIndicies = [0,3,4,7,10,12,13]
+    
+    module Utils
+      module_function
+      
+      # Parses a ProteinHit from the hit string.
+      def parse_protein_hit(str, desc, query_hits)
+        data = str.split(",")
+        ProteinHitFloatIndicies.each do |index|
+          data[index] = data[index].to_f
+        end
+        data << desc
+        data << query_hits
+        
+        ProteinHit.new(*data)
+      end
+      
+      # Parses a QueryHit from the hit-query string.
+      def parse_query_hit(str, terms)
+        return nil if str == nil || str == "-1"
+        
+        data = str.split(",") + terms.split(",")
+        QueryHitFloatIndicies.each do |index|
+          data[index] = data[index].to_f
+        end
+        QueryHitIntIndicies.each do |index|
+          data[index] = data[index].to_i
+        end
+        
+        QueryHit.new(*data)
+      end
+    end
+    
+    include Utils
+    
+    def initialize(data={}, section_name=self.class.section_name, dat=nil)
+      super(data, section_name, dat)
+      @protein_hits = []
+      @query_hits = []
+    end
+    
+    # An array of protein hits.  Specify resolve=false to return just the
+    # currently parsed hits.
+    #
+    # Note that the hits array is indexed the same as in Mascot, ie the 
+    # ProteinHit for h1 is located at hits[1], meaning there is always
+    # an empty cell at hits[0].
+    def protein_hits(resolve=true)
+      return @protein_hits unless resolve
+      
+      hit = 1
+      hit += 1 while protein_hit(hit)
+      @protein_hits
+    end
+    
+    # Returns a ProteinHit at the hit index, or nil if no such hit exists.
+    def protein_hit(hit)
+      key = "h#{hit}"
+      return nil unless str = data[key]
+      @protein_hits[hit] ||= parse_protein_hit(str, data["#{key}_text"], query_hits(hit))
+    end
+    
+    # Returns an array of QueryHits for the specified hit, or nil if no
+    # such hit exists.
+    def query_hits(hit)
+      query = 1
+      while data.has_key?("h#{hit}_q#{query}")
+        query_hit(hit, query)
+        query += 1 
+      end
+      
+      @query_hits[hit]
+    end
+    
+    # Returns the QueryHit at the hit and query index, or nil if no such query
+    # exists.
+    def query_hit(hit, query)
+      key = "h#{hit}_q#{query}"
+      return nil unless data.has_key?(key)
+      
+      queries = @query_hits[hit] ||= []
+      if existing_query = queries[query]
+        return existing_query
+      end
+      
+      if parsed_query = parse_query_hit(data[key], data["#{key}_terms"])
+        queries[query] = parsed_query
+        return parsed_query
+      end
+      
+      nil
+    end
+  end
 end