bio 1.2.1 → 1.3.0

data/lib/bio/appl/paml/baseml.rb

@@ -0,0 +1,95 @@
+#
+# = bio/appl/paml/baseml.rb - Wrapper for running PAML program baseml
+#
+# Copyright::  Copyright (C) 2008
+#              Naohisa Goto <ng@bioruby.org>
+#
+# License::    The Ruby License
+#
+# == Description
+#
+# This file contains Bio::PAML::Baseml, a wrapper class running baseml.
+#
+# == References
+#
+# * http://abacus.gene.ucl.ac.uk/software/paml.html
+#
+
+require 'bio/appl/paml/common'
+
+module Bio::PAML
+
+  # == Description
+  #
+  # Bio::PAML::Baseml is a wrapper for running PAML baseml program. 
+  #
+  # Because most of the methods in this class are inherited from
+  # Bio::PAML::Common, see documents of Bio::PAML::Common for details.
+  #
+  # == Examples
+  #
+  # Example 1:
+  #
+  #   require 'bio'
+  #   # Reads multi-fasta formatted file and gets a Bio::Alignment object.
+  #   alignment = Bio::FlatFile.open(Bio::Alignment::MultiFastaFormat,
+  #                                  'example.fst').alignment
+  #   # Reads newick tree from a file
+  #   tree = Bio::FlatFile.open(Bio::Newick, 'example.tree').tree
+  #   # Creates a Baseml object
+  #   baseml = Bio::PAML::Baseml.new
+  #   # Sets parameters
+  #   baseml.parameters[:runmode] = 0
+  #   baseml.parameters[:RateAncestor] = 1
+  #   # You can also set many parameters at a time.
+  #   baseml.parameters.update({ :alpha => 0.5, :fix_alpha => 0 })
+  #   # Executes baseml with the alignment and the tree
+  #   report = baseml.query(alignment, tree)
+  #
+  class Baseml < Common
+
+    autoload  :Report,  'bio/appl/paml/baseml/report'
+
+    # Default program name
+    DEFAULT_PROGRAM = 'baseml'.freeze
+
+    # Default parameters when running baseml.
+    #
+    # The parameters whose values are different from the baseml defalut
+    # value (described in pamlDOC.pdf) in PAML 4.1 are:
+    #  seqfile, outfile, treefile, ndata, noisy, verbose
+    #
+    DEFAULT_PARAMETERS = {
+      # Essential argumemts
+      :seqfile             => nil,
+      :outfile             => nil,
+      # Optional arguments
+      :treefile            => nil,
+      :noisy               => 0,
+      :verbose             => 1,
+      :runmode             => 0,
+      :model               => 5,
+      :Mgene               => 0,
+      :ndata               => 1,
+      :clock               => 0,
+      :fix_kappa           => 0,
+      :kappa               => 2.5,
+      :fix_alpha           => 1,
+      :alpha               => 0.0,
+      :Malpha              => 0,
+      :ncatG               => 5,
+      :fix_rho             => 1,
+      :rho                 => 0.0,
+      :nparK               => 0,
+      :nhomo               => 0,
+      :getSE               => 0,
+      :RateAncestor        => 0,
+      :Small_Diff          => 1e-6,
+      :cleandata           => 1,
+      :fix_blength         => 0,
+      :method              => 0
+    }
+
+  end #class Baseml
+end #module Bio::PAML
+

data/lib/bio/appl/paml/baseml/report.rb

@@ -0,0 +1,32 @@
+#
+# = bio/appl/paml/baseml/report.rb - parser class for PAML program baseml
+#
+# Copyright::  Copyright (C) 2008
+#              Naohisa Goto <ng@bioruby.org>
+#
+# License::    The Ruby License
+#
+# == Description
+#
+# This file contains Bio::PAML::Baseml::Report, a parser class for a result
+# of baseml.
+#
+# == References
+#
+# * http://abacus.gene.ucl.ac.uk/software/paml.html
+#
+
+require 'bio/appl/paml/baseml'
+
+module Bio::PAML
+  class Baseml
+
+    # UNDER CONSTRUCTION.
+    #
+    # Bio::PAML::Baseml::Report is a parser class for a baseml result.
+    #
+    class Report < Bio::PAML::Common::Report
+    end #class Report
+
+  end #class Baseml
+end #module Bio::PAML

data/lib/bio/appl/paml/codeml.rb

@@ -0,0 +1,242 @@
+#
+# = bio/appl/paml/codeml.rb - Wrapper for running PAML program codeml
+#
+# Copyright::  Copyright (C) 2008
+#              Michael D. Barton <mail@michaelbarton.me.uk>,
+#              Naohisa Goto <ng@bioruby.org>
+#
+# License::    The Ruby License
+#
+# == Description
+#
+# This file contains a wrapper for running the CODEML tool for estimating evolutionary rate 
+#
+# == References
+#
+# * http://abacus.gene.ucl.ac.uk/software/paml.html
+#
+
+require 'bio/appl/paml/common'
+
+module Bio
+module PAML
+
+  # == Description
+  #
+  # Bio::PAML::Codeml is a wrapper for estimating evolutionary rate using the CODEML 
+  # tool. The class provides methods for generating the necessary configuration 
+  # file, and running codeml with the specified binary. Codeml output is 
+  # returned when codeml is run. Bio::PAML::Codeml::Report and Bio::PAML::Codeml::Rates
+  # provide simple classes for parsing and accessing the Codeml report and
+  # rates files respectively.
+  #
+  # == Examples
+  #
+  # Example 1:
+  #
+  #   require 'bio'
+  #   # Reads multi-fasta formatted file and gets a Bio::Alignment object.
+  #   alignment = Bio::FlatFile.open(Bio::Alignment::MultiFastaFormat,
+  #                                  'example.fst').alignment
+  #   # Reads newick tree from a file
+  #   tree = Bio::FlatFile.open(Bio::Newick, 'example.tree').tree
+  #   # Creates a Codeml object
+  #   codeml = Bio::PAML::Codeml.new
+  #   # Sets parameters
+  #   codeml.parameters[:runmode] = 0
+  #   codeml.parameters[:RateAncestor] = 1
+  #   # You can also set many parameters at a time.
+  #   codeml.parameters.update({ :alpha => 0.5, :fix_alpha => 0 })
+  #   # Executes codeml with the alignment and the tree
+  #   report = codeml.query(alignment, tree)
+  #       
+  # Example 2 (Obsolete usage):
+  #
+  #   # Create a control file, setting some Codeml options
+  #   # Default parameters are used otherwise, see RDoc for defaults
+  #   # The names of the parameters correspond to those specified
+  #   # in the Codeml documentation
+  #   control_file = Tempfile.new('codeml_ctl')
+  #   control_file.close(false)
+  #   # Prepare output file as a temporary file
+  #   output_file = Tempfile.new('codeml_test')
+  #   output_file.close(false)
+  #   Bio::PAML::Codeml.create_control_file(config_file.path, {
+  #     :model       => 1,
+  #     :fix_kappa   => 1,
+  #     :aaRatefile  => TEST_DATA + '/wag.dat',
+  #     :seqfile     => TEST_DATA + '/abglobin.aa',
+  #     :treefile    => TEST_DATA + '/abglobin.trees',
+  #     :outfile     => output_file.path,
+  #   })
+  #   
+  #   # Create an instance of Codeml specifying where the codeml binary is
+  #   codeml = Bio::PAML::Codeml.new('/path/to/codeml')
+  #   
+  #   # Run codeml using a control file
+  #   # Returns the command line output
+  #   codeml_output = codeml.run(control_file)
+  #
+  class Codeml < Common
+
+    autoload  :Report,  'bio/appl/paml/codeml/report'
+    autoload  :Rates,   'bio/appl/paml/codeml/rates'
+
+    # Default program name
+    DEFAULT_PROGRAM = 'codeml'.freeze
+
+    # Default parameters when running codeml.
+    #
+    # The parameters whose values are different from the codeml defalut
+    # value (described in pamlDOC.pdf) in PAML 4.1 are:
+    #  seqfile, outfile, treefile, ndata, noisy, verbose, cleandata
+    #
+    DEFAULT_PARAMETERS = {
+      # Essential argumemts
+      :seqfile             => nil,
+      :outfile             => nil,
+      # Optional arguments
+      :treefile            => nil,
+      :noisy               => 0,
+      :verbose             => 1,
+      :runmode             => 0,
+      :seqtype             => 2,
+      :CodonFreq           => 2,
+      :ndata               => 1,
+      :clock               => 0,
+      :aaDist              => 0,
+      :aaRatefile          => 'wag.dat',
+      :model               => 2,
+      :NSsites             => 0,
+      :icode               => 0,
+      :Mgene               => 0,
+      :fix_kappa           => 0,
+      :kappa               => 2,
+      :fix_omega           => 0,
+      :omega               => 0.4,
+      :fix_alpha           => 0,
+      :alpha               => 0.0,
+      :Malpha              => 0,
+      :ncatG               => 3,
+      :fix_rho             => 1,
+      :rho                 => 0.0,
+      :getSE               => 0,
+      :RateAncestor        => 0,
+      :Small_Diff          => 0.5e-6,
+      :cleandata           => 1,
+      :fix_blength         => 0,
+      :method              => 0
+    }
+
+    # OBSOLETE. This method should not be used. 
+    # Instead, use parameters.
+    def options
+      warn 'The method Codeml#options will be changed to be used for command line arguments in the future. Instead, use Codeml#parameters.'
+      parameters
+    end
+
+    # OBSOLETE. This method should not be used. 
+    # Instead, use parameters=(hash).
+    def options=(hash)
+      warn 'The method Codeml#options=() will be changed to be used for command line arguments in the future. Instead, use Codeml#parameters=().'
+      self.parameters=(hash)
+    end
+
+    # Obsolete. This method will be removed in the future.
+    # Helper method for creating a codeml control file.
+    # Note that default parameters are automatically merged.
+    def self.create_control_file(parameters, filename)
+      parameters = DEFAULT_PARAMETERS.merge(parameters)
+      File.open(filename, 'w') do |file|
+        parameters.each do |key, value|
+          file.puts "#{key.to_s} = #{value.to_s}" if value
+        end
+      end
+      filename
+    end
+
+    # OBSOLETE. This method will soon be removed.
+    # Instead, use create_control_file(parameters, filename).
+    def self.create_config_file(parameters, filename)
+      warn "The method Codeml.create_config_file(parameters, filename) will soon be removed. Instead, use Codeml.create_control_file(filename, parameters)."
+      create_control_file(parameters, filename)
+    end
+
+
+    # Runs the program on the internal parameters with the specified
+    # sequence alignment and tree.
+    #
+    # Note that parameters[:seqfile] and parameters[:outfile]
+    # are always modified, and parameters[:treefile] and
+    # parameters[:aaRatefile] are modified when tree and aarate are
+    # specified respectively.
+    #
+    # For other important information, see the document of
+    # Bio::PAML::Common#query.
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _alignment_: Bio::Alignment object or similar object
+    # * (optional) _tree_: Bio::Tree object
+    # * (optional) _aarate_: String or nil
+    # *Returns*:: Report object
+    def query(alignment, tree = nil, aarate = nil)
+      begin
+        aaratefile = prepare_aaratefile(aarate)
+        ret = super(alignment, tree)
+      ensure
+        finalize_aaratefile(aaratefile)
+      end
+      ret
+    end
+
+    # Runs the program on the internal parameters with the specified
+    # sequence alignment data string and tree data string.
+    #
+    # Note that parameters[:outfile] is always modified, and
+    # parameters[:seqfile], parameters[:treefile], and
+    # parameters[:aaRatefile] are modified when
+    # alignment, tree, and aarate are specified respectively.
+    #
+    # It raises RuntimeError if seqfile is not specified in the argument
+    # or in the parameter.
+    #
+    # For other important information, see the document of query method.
+    # 
+    # ---
+    # *Arguments*:
+    # * (optional) _alignment_: String
+    # * (optional) _tree_: String or nil
+    # * (optional) _aarate_: String or nil
+    # *Returns*:: contents of output file (String)
+    def query_by_string(alignment = nil, tree = nil, aarate = nil)
+      begin
+        aaratefile = prepare_aaratefile(aarate)
+        ret = super(alignment, tree)
+      ensure
+        finalize_aaratefile(aaratefile)
+      end
+      ret
+    end
+
+    private
+
+    # (private) prepares temporary file for aaRatefile if needed
+    def prepare_aaratefile(aarate)
+      if aarate then
+        aaratefile = Tempfile.new('codeml_aarate')
+        aaratefile.print aarate
+        aaratefile.close(false)
+        self.parameters[:aaRatefile] = aaratefile.path
+      end
+      aaratefile
+    end
+
+    # (private) removes temporary file for aaRatefile if needed
+    def finalize_aaratefile(aaratefile)
+      aaratefile.close(true) if aaratefile
+    end
+
+  end # End class Codeml
+end # End module PAML
+end # End module Bio

data/lib/bio/appl/paml/codeml/rates.rb

@@ -0,0 +1,67 @@
+#
+# = bio/appl/paml/codeml/rates.rb - Codeml rates report file parser
+#
+# Copyright::  Copyright (C) 2008 Michael D. Barton <mail@michaelbarton.me.uk>
+#
+# License::    The Ruby License
+#
+# == Description
+#
+# This file contains a class that implement a simple interface to Codeml rates estimation file
+#
+# == References
+#
+# * http://abacus.gene.ucl.ac.uk/software/paml.html
+#
+
+require 'delegate'
+require 'bio/appl/paml/codeml'
+
+module Bio::PAML
+  class Codeml
+
+    # == Description
+    # 
+    # A simple class for parsing the codeml rates file.
+    #
+    # WARNING: The order of the parsed data should be correct, however will
+    # not necessarily correspond to the position in the alignment. For instance
+    # codeml ignores columns that contains gaps, and therefore there will not
+    # be any estimated rate data.
+    #
+    # == Usage
+    #
+    # site_rates = Bio::PAML::Codeml::Rates.new(File.open(@tmp_dir + "/rates").read)
+    # site_rate.first[:freq] # => Number of times that column appears
+    # site_rate.[5][:rate] # => Estimated rate of evolution
+    # site_rate.last[:data] # => The content of the column, as a string
+    #
+    # # This class delegates to an array, so will respond to all array methods
+    # site_rates.max {|x,y| x[:rate] <=> y[:rate] } # => Fastest evolving column
+    # site_rates.detect {|x| x[:freq] > 1 } # => Columns appearing more than once
+    class Rates < DelegateClass(Array)
+
+      def initialize(rates)
+        super(parse_rates(rates))
+      end
+
+      private
+
+      def parse_rates(text)
+        re = /\s+(\d+)\s+(\d+)\s+([A-Z\*]+)\s+(\d+\.\d+)\s+(\d)/
+        array = Array.new
+        text.each_line do |line|
+          if re =~ line
+            match = Regexp.last_match
+            array[match[1].to_i] = {
+              :freq => match[2].to_i, 
+              :data => match[3], 
+              :rate => match[4].to_f }
+          end
+        end
+        array.compact
+      end
+
+    end
+  end
+end

data/lib/bio/appl/paml/codeml/report.rb

@@ -0,0 +1,67 @@
+#
+# = bio/appl/paml/codeml/report.rb - Codeml report parser
+#
+# Copyright::  Copyright (C) 2008 Michael D. Barton <mail@michaelbarton.me.uk>
+#
+# License::    The Ruby License
+#
+# == Description
+#
+# This file contains a class that implement a simple interface to Codeml output file
+#
+# == References
+#
+# * http://abacus.gene.ucl.ac.uk/software/paml.html
+#
+
+require 'bio/appl/paml/codeml'
+
+module Bio::PAML
+  class Codeml
+
+    # == Description
+    #
+    # A simple class for parsing codeml output.
+    #
+    # WARNING: This data is parsed using a regex from the output file, and
+    # so will take the first result found. If using multiple tree's, your
+    # milage may vary. See the source for the regular expressions.
+    #
+    # require 'bio'
+    #
+    # report = Bio::PAML::Codeml::Report.new(File.open(codeml_output_file).read)
+    # report.gene_rate  # => Rate of gene evolution as defined be alpha
+    # report.tree_lengh # => Estimated phylogetic tree length
+    class Report < Bio::PAML::Common::Report
+
+      attr_reader :tree_log_likelihood, :tree_length, :alpha, :tree
+
+      def initialize(codeml_report)
+        @tree_log_likelihood = pull_tree_log_likelihood(codeml_report)
+        @tree_length = pull_tree_length(codeml_report)
+        @alpha = pull_alpha(codeml_report)
+        @tree = pull_tree(codeml_report)
+      end
+
+      private
+
+      def pull_tree_log_likelihood(text)
+        text[/lnL\(.+\):\s+(-?\d+(\.\d+)?)/,1].to_f
+      end
+
+      
+      def pull_tree_length(text)
+        text[/tree length\s+=\s+ (-?\d+(\.\d+)?)/,1].to_f
+      end
+
+      def pull_alpha(text)
+        text[/alpha .+ =\s+(-?\d+(\.\d+)?)/,1].to_f
+      end
+
+      def pull_tree(text)
+        text[/([^\n]+)\n\nDetailed/m,1]
+      end
+
+    end # End Report
+  end # End Codeml
+end # End Bio::PAML