Class | Bio::PAML::Common
In: | lib/bio/appl/paml/common.rb lib/bio/appl/paml/common_report.rb
Parent: | Object

## Description

Bio::PAML::Common is a basic wrapper class for PAML programs. The class provides methods for generating the necessary configuration file, and running a program.

### Methods

dump_parameters load_parameters new query query_by_string run set_default_parameters

### Classes and Modules

Class Bio::PAML::Common::Report

### Constants

DEFAULT_PARAMETERS | = | {} |  | Default parameters. Should be redefined in subclass.
DEFAULT_PROGRAM | = | nil |  | Default program. Should be redifined in subclass.
DEFAULT_PARAMETERS_ORDER | = | %w( seqfile outfile treefile noisy verbose runmode seqtype CodonFreq ndata clock aaDist aaRatefile model NSsites icode Mgene fix_kappa kappa fix_omega omega fix_alpha alpha Malpha ncatG fix_rho rho nparK nhomo getSE RateAncestor Small_Diff cleandata fix_blength method ).collect { |x| x.to_sym } |  | Preferred order of parameters.

### Attributes

command | [R] | the last executed command (Array of String)
data_stdout | [R] | the last output to the stdout (String)
exit_status | [R] | the last exit status of the program
output | [R] | the last result of the program (String)
parameters | [RW] | Parameters described in the control file. (Hash) Each key of the hash must be a Symbol object, and each value must be a String object or nil.
report | [R] | Report object created from the last result
supplemental_outputs | [R] | contents of supplemental output files (Hash). Each key is a file name and value is content of the file.

### Public Class methods

new(program = nil, params = {})

Creates a wrapper instance, which will run using the specified binary location or the command in the PATH. If program is specified as nil, DEFAULT_PROGRAM is used. Default parameters are automatically loaded and merged with the specified parameters.

Arguments:

- (optional) program: path to the program, or command name (String)
- (optional) params: parameters (Hash)

[Source]

        # File lib/bio/appl/paml/common.rb, line 73
    73:     def initialize(program = nil, params = {})
    74:       @program = program || self.class::DEFAULT_PROGRAM
    75:       set_default_parameters
    76:       self.parameters.update(params)
    77:     end

### Public Instance methods

dump_parameters()

Shows parameters (content of control file) as a string. The string can be used for control file.

Returns: | string representation of the parameters (String)

[Source]

         # File lib/bio/appl/paml/common.rb, line 270
    270:     def dump_parameters
    271:       keyorder = DEFAULT_PARAMETERS_ORDER
    272:       keys = parameters.keys
    273:       str = ''
    274:       keys.sort do |x, y|
    275:         (keyorder.index(x) || (keyorder.size + keys.index(x))) <=>
    276:           (keyorder.index(y) || (keyorder.size + keys.index(y)))
    277:       end.each do |key|
    278:         value = parameters[key]
    279:         # Note: spaces are required in both side of the "=".
    280:         str.concat "#{key.to_s} = #{value.to_s}\n" if value
    281:       end
    282:       str
    283:     end

load_parameters(str)

Loads parameters from the specified string. Note that all previous parameters are erased. Returns the parameters as a hash.

Arguments:

- (required) str: contents of a PAML control file (String)

Returns: | parameters (Hash)

[Source]

         # File lib/bio/appl/paml/common.rb, line 248
    248:     def load_parameters(str)
    249:       hash = {}
    250:       str.each_line do |line|
    251:         param, value = parse_parameter(line)
    252:         hash[param] = value if param
    253:       end
    254:       self.parameters = hash
    255:     end

query(alignment, tree = 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] is modified when tree is specified.

To prevent overwrite of existing files by PAML, this method automatically creates a temporary directory and the program is run inside the directory. After the end of the program, the temporary directory is automatically removed.

Arguments:

- (required) alignment: Bio::Alignment object or similar object
- (optional) tree: Bio::Tree object

Returns: | Report object

[Source]

         # File lib/bio/appl/paml/common.rb, line 117
    117:     def query(alignment, tree = nil)
    118:       astr = alignment.output(:phylipnon)
    119:       if tree then
    120:         tstr = [ sprintf("%3d %2d\n", tree.leaves.size, 1), "\n",
    121:                  tree.output(:newick,
    122:                              { :indent => false,
    123:                                :bootstrap_style => :disabled,
    124:                                :branch_length_style => :disabled })
    125:                ].join('')
    126:       else
    127:         tstr = nil
    128:       end
    129:       str = _query_by_string(astr, tstr)
    130:       @report = self.class::Report.new(str)
    131:       @report
    132:     end

query_by_string(alignment = nil, tree = 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] and parameters[:treefile] are modified when alignment and tree are specified respectively.

It raises RuntimeError if seqfile is not specified in the argument or in the parameter.

For other information, see the document of query method.

Arguments:

- (optional) alignment: String
- (optional) tree: String or nil

Returns: | contents of output file (String)

[Source]

         # File lib/bio/appl/paml/common.rb, line 151
    151:     def query_by_string(alignment = nil, tree = nil)
    152:       _query_by_string(alignment, tree)
    153:     end

run(control_file)

Runs the program on the parameters in the passed control file. No parameters checks are performed. All internal parameters are ignored and are kept untouched. The output and report attributes are cleared in this method.

Warning about PAML‘s behavior: PAML writes supplemental output files in the current directory with fixed file names which can not be changed with parameters or command-line options, for example, rates, rst, and rub. This behavior may ovarwrite existing files, especially previous supplemental results.

Arguments:

- (optional) control_file: file name of control file (String)

Returns: | messages printed to the standard output (String)

[Source]

        # File lib/bio/appl/paml/common.rb, line 95
    95:     def run(control_file)
    96:       exec_local([ control_file ])
    97:     end

set_default_parameters()

Loads system-wide default parameters. Note that all previous parameters are erased. Returns the parameters as a hash.

Returns: | parameters (Hash)

[Source]

         # File lib/bio/appl/paml/common.rb, line 262
    262:     def set_default_parameters
    263:       self.parameters = self.class::DEFAULT_PARAMETERS.merge(Hash.new)
    264:     end

[Validate]