Class | Bio::PAML::Codeml
In: | lib/bio/appl/paml/codeml.rb lib/bio/appl/paml/codeml/rates.rb lib/bio/appl/paml/codeml/report.rb
Parent: | Common

## 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)

### Methods

create_config_file create_control_file options options= query query_by_string

### Classes and Modules

Class Bio::PAML::Codeml::Rates
Class Bio::PAML::Codeml::Report

### Constants

DEFAULT_PROGRAM | = | 'codeml'.freeze |  | Default program name
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 |  | 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

### Public Class methods

create_config_file(parameters, filename)

OBSOLETE. This method will soon be removed. Instead, use create_control_file(parameters, filename).

[Source]

         # File lib/bio/appl/paml/codeml.rb, line 160
    160:     def self.create_config_file(parameters, filename)
    161:       warn "The method Codeml.create_config_file(parameters, filename) will soon be removed. Instead, use Codeml.create_control_file(filename, parameters)."
    162:       create_control_file(parameters, filename)
    163:     end

create_control_file(parameters, filename)

Obsolete. This method will be removed in the future. Helper method for creating a codeml control file. Note that default parameters are automatically merged.

[Source]

         # File lib/bio/appl/paml/codeml.rb, line 148
    148:     def self.create_control_file(parameters, filename)
    149:       parameters = DEFAULT_PARAMETERS.merge(parameters)
    150:       File.open(filename, 'w') do |file|
    151:         parameters.each do |key, value|
    152:           file.puts "#{key.to_s} = #{value.to_s}" if value
    153:         end
    154:       end
    155:       filename
    156:     end

### Public Instance methods

options()

OBSOLETE. This method should not be used. Instead, use parameters.

[Source]

         # File lib/bio/appl/paml/codeml.rb, line 133
    133:     def options
    134:       warn 'The method Codeml#options will be changed to be used for command line arguments in the future. Instead, use Codeml#parameters.'
    135:       parameters
    136:     end

options=(hash)

OBSOLETE. This method should not be used. Instead, use parameters=(hash).

[Source]

         # File lib/bio/appl/paml/codeml.rb, line 140
    140:     def options=(hash)
    141:       warn 'The method Codeml#options=() will be changed to be used for command line arguments in the future. Instead, use Codeml#parameters=().'
    142:       self.parameters=(hash)
    143:     end

query(alignment, tree = nil, aarate = nil)

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

[Source]

         # File lib/bio/appl/paml/codeml.rb, line 183
    183:     def query(alignment, tree = nil, aarate = nil)
    184:       begin
    185:         aaratefile = prepare_aaratefile(aarate)
    186:         ret = super(alignment, tree)
    187:       ensure
    188:         finalize_aaratefile(aaratefile)
    189:       end
    190:       ret
    191:     end

query_by_string(alignment = nil, tree = nil, aarate = nil)

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)

[Source]

         # File lib/bio/appl/paml/codeml.rb, line 212
    212:     def query_by_string(alignment = nil, tree = nil, aarate = nil)
    213:       begin
    214:         aaratefile = prepare_aaratefile(aarate)
    215:         ret = super(alignment, tree)
    216:       ensure
    217:         finalize_aaratefile(aaratefile)
    218:       end
    219:       ret
    220:     end

[Validate]