Class: Bio::PAML::Common

Inherits:
Object
  • Object
show all
Defined in:
lib/bio/appl/paml/common.rb,
lib/bio/appl/paml/common_report.rb

Overview

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.

Direct Known Subclasses

Baseml, Codeml, Yn00

Defined Under Namespace

Classes: Report

Constant Summary collapse

DEFAULT_PARAMETERS =

Default parameters. Should be redefined in subclass.

{}
DEFAULT_PROGRAM =

Default program. Should be redifined in subclass.

nil
DEFAULT_PARAMETERS_ORDER =

Preferred order of parameters.

%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 }

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(program = nil, params = {}) ⇒ Common

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)



74
75
76
77
78
 
# File 'lib/bio/appl/paml/common.rb', line 74

def initialize(program = nil, params = {})
  @program = program || self.class::DEFAULT_PROGRAM
  set_default_parameters
  self.parameters.update(params)
end

Instance Attribute Details

#command ⇒ Object (readonly)

the last executed command (Array of String)



236
237
238
 
# File 'lib/bio/appl/paml/common.rb', line 236

def command
  @command
end

#data_stdout ⇒ Object (readonly)

the last output to the stdout (String)



233
234
235
 
# File 'lib/bio/appl/paml/common.rb', line 233

def data_stdout
  @data_stdout
end

#exit_status ⇒ Object (readonly)

the last exit status of the program



230
231
232
 
# File 'lib/bio/appl/paml/common.rb', line 230

def exit_status
  @exit_status
end

#output ⇒ Object (readonly)

the last result of the program (String)



224
225
226
 
# File 'lib/bio/appl/paml/common.rb', line 224

def output
  @output
end

#parameters ⇒ Object

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.



55
56
57
 
# File 'lib/bio/appl/paml/common.rb', line 55

def parameters
  @parameters
end

#report ⇒ Object (readonly)

Report object created from the last result



227
228
229
 
# File 'lib/bio/appl/paml/common.rb', line 227

def report
  @report
end

#supplemental_outputs ⇒ Object (readonly)

contents of supplemental output files (Hash). Each key is a file name and value is content of the file.



240
241
242
 
# File 'lib/bio/appl/paml/common.rb', line 240

def supplemental_outputs
  @supplemental_outputs
end

Instance Method Details

#dump_parameters ⇒ Object

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

Returns

string representation of the parameters (String)



271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/bio/appl/paml/common.rb', line 271

def dump_parameters
  keyorder = DEFAULT_PARAMETERS_ORDER
  keys = parameters.keys
  str = String.new
  keys.sort do |x, y|
    (keyorder.index(x) || (keyorder.size + keys.index(x))) <=>
      (keyorder.index(y) || (keyorder.size + keys.index(y)))
  end.each do |key|
    value = parameters[key]
    # Note: spaces are required in both side of the "=".
    str.concat "#{key.to_s} = #{value.to_s}\n" if value
  end
  str
end

#load_parameters(str) ⇒ Object

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)



249
250
251
252
253
254
255
256
 
# File 'lib/bio/appl/paml/common.rb', line 249

def load_parameters(str)
  hash = {}
  str.each_line do |line|
    param, value = parse_parameter(line)
    hash[param] = value if param
  end
  self.parameters = hash
end

#query(alignment, tree = nil) ⇒ Object

Runs the program on the internal parameters with the specified sequence alignment and tree.

Note that parameters and parameters are always modified, and parameters 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



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/bio/appl/paml/common.rb', line 118

def query(alignment, tree = nil)
  astr = alignment.output(:phylipnon)
  if tree then
    tstr = [ sprintf("%3d %2d\n", tree.leaves.size, 1), "\n",
             tree.output(:newick,
                         { :indent => false,
                           :bootstrap_style => :disabled,
                           :branch_length_style => :disabled })
           ].join('')
  else
    tstr = nil
  end
  str = _query_by_string(astr, tstr)
  @report = self.class::Report.new(str)
  @report
end

#query_by_string(alignment = nil, tree = nil) ⇒ Object

Runs the program on the internal parameters with the specified sequence alignment data string and tree data string.

Note that parameters is always modified, and parameters and parameters 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)



152
153
154
 
# File 'lib/bio/appl/paml/common.rb', line 152

def query_by_string(alignment = nil, tree = nil)
  _query_by_string(alignment, tree)
end

#run(control_file) ⇒ Object

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)



96
97
98
 
# File 'lib/bio/appl/paml/common.rb', line 96

def run(control_file)
  exec_local([ control_file ])
end

#set_default_parameters ⇒ Object

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

Returns

parameters (Hash)



263
264
265
 
# File 'lib/bio/appl/paml/common.rb', line 263

def set_default_parameters
  self.parameters = self.class::DEFAULT_PARAMETERS.merge(Hash.new)
end