Bio::Phylo::Beagle - Perl wrapper around BEAGLE
use Test::More 'no_plan'; use strict; use warnings; use Math::Round; use Bio::Phylo::Beagle; use Bio::Phylo::IO 'parse'; use Bio::Phylo::Models::Substitution::Dna::JC69; # parse the FASTA matrix at the bottom of this file my $matrix = parse( '-format' => 'fasta', '-type' => 'dna', '-handle' => \*DATA, )->[0]; # parse a NEWICK string my $tree = parse( '-format' => 'newick', '-string' => '((homo:0.1,pan:0.1):0.2,gorilla:0.1);', )->first; # instantiate a JC69 model my $model = Bio::Phylo::Models::Substitution::Dna::JC69->new; # instantiate the beagle wrapper my $beagle = Bio::Phylo::Beagle->new; # create a beagle instance my $instance = $beagle->create_instance( '-tip_count' => $matrix->get_ntax, # tipCount '-partials_buffer_count' => 2, # partialsBufferCount '-compact_buffer_count' => 3, # compactBufferCount '-state_count' => 4, # stateCount '-pattern_count' => $matrix->get_nchar, # patternCount '-eigen_buffer_count' => 1, # eigenBufferCount '-matrix_buffer_count' => 4, # matrixBufferCount '-category_count' => 1, # categoryCount ); # assign a character state matrix $beagle->set_matrix($matrix); # assign a substitution model $beagle->set_model($model); # set category weights $beagle->set_category_weights( -weights => [1.0] ); # set category rates $beagle->set_category_rates( 1.0 ); # set eigen decomposition $beagle->set_eigen_decomposition( '-vectors' => [ 1.0, 2.0, 0.0, 0.5, 1.0, -2.0, 0.5, 0.0, 1.0, 2.0, 0.0, -0.5, 1.0, -2.0, -0.5, 0.0 ], '-inverse_vectors' => [ 0.25, 0.25, 0.25, 0.25, 0.125, -0.125, 0.125, -0.125, 0.0, 1.0, 0.0, -1.0, 1.0, 0.0, -1.0, 0.0 ], '-values' => [ 0.0, -1.3333333333333333, -1.3333333333333333, -1.3333333333333333 ] ); # assign a tree object $beagle->set_tree($tree); # update transition matrices $beagle->update_transition_matrices; # create operation array my $operations = Bio::Phylo::BeagleOperationArray->new(2); # create operations my $op0 = Bio::Phylo::BeagleOperation->new( '-destination_partials' => 3, '-destination_scale_write' => $Bio::Phylo::Beagle::BEAGLE_OP_NONE, '-destination_scale_read' => $Bio::Phylo::Beagle::BEAGLE_OP_NONE, '-child1_partials' => 0, '-child1_transition_matrix' => 0, '-child2_partials' => 1, '-child2_transition_matrix' => 1 ); my $op1 = Bio::Phylo::BeagleOperation->new( '-destination_partials' => 4, '-destination_scale_write' => $Bio::Phylo::Beagle::BEAGLE_OP_NONE, '-destination_scale_read' => $Bio::Phylo::Beagle::BEAGLE_OP_NONE, '-child1_partials' => 2, '-child1_transition_matrix' => 2, '-child2_partials' => 3, '-child2_transition_matrix' => 3 ); # insert operations in array $operations->set_item( -index => 0, -op => $op0 ); $operations->set_item( -index => 1, -op => $op1 ); # update partials $beagle->update_partials( '-operations' => $operations, '-count' => 2, '-index' => $Bio::Phylo::Beagle::BEAGLE_OP_NONE, ); my $lnl = $beagle->calculate_root_log_likelihoods; ok( round($lnl) == -85, "-lnL: $lnl" ); __DATA__ >homo CCGAG-AGCAGCAATGGAT-GAGGCATGGCG >pan GCGCGCAGCTGCTGTAGATGGAGGCATGACG >gorilla GCGCGCAGCAGCTGTGGATGGAAGGATGACG
This is a wrapper around the Beagle library (http://dx.doi.org/10.1093/sysbio/syr100) that accepts Bio::Phylo objects to simplify data handling.
This function creates a single instance of the BEAGLE library and can be called multiple times to create multiple data partition instances each returning a unique identifier.
Type : Factory method Title : create_instance Usage : $beagle->create_instance( %args ) Function: Create a single instance Returns : the unique instance identifier (<0 if failed, see @ref BEAGLE_RETURN_CODES "BeagleReturnCodes") Args : -tip_count => Number of tip data elements (input) -partials_buffer_count => Number of partials buffers to create (input) -compact_buffer_count => Number of compact state representation buffers to create (input) -state_count => Number of states in the continuous-time Markov chain (input) -pattern_count => Number of site patterns to be handled by the instance (input) -eigen_buffer_count => Number of rate matrix eigen-decomposition, category weight, and state frequency buffers to allocate (input) -matrix_buffer_count => Number of transition probability matrix buffers (input) -category_count => Number of rate categories (input) -scale_buffer_count => Number of scale buffers to create, ignored for auto scale or always scale (input) -resource_list => List of potential resources on which this instance is allowed (input, NULL implies no restriction) -resource_count => Length of resourceList list (input) -preference_flags => Bit-flags indicating preferred implementation characteristics, see BeagleFlags (input) -requirement_flags => Bit-flags indicating required implementation characteristics, see BeagleFlags (input) -return_info => Pointer to return implementation and resource details
Creates a case-insensitive mapping from the state symbols (usually A, C, G, T) in the matrix to integers
Type : Factory method Title : create_table Usage : $beagle->create_table( $matrix ) Function: Creates symbol to int mapping Returns : HASH Args : Optional: a character state matrix, otherwise $beagle->get_matrix is used
Type : Mutator Title : set_pattern_weights Usage : $beagle->set_pattern_weights( 1,1,1,1,1 ) Function: Set a category weights buffer Returns : error code Args : Array containing patternCount weights (input)
This function copies a state frequency array into an instance buffer.
Type : Mutator Title : set_state_frequencies Usage : $beagle->set_state_frequencies Function: Set a state frequency buffer Returns : error code Args : Optional: Index of state frequencies buffer (input)
Type : Mutator Title : set_matrix Usage : $beagle->set_matrix($matrix); Function: Sets matrix to analyze Returns : $self Args : Bio::Phylo::Matrices::Matrix object
Type : Mutator Title : set_tree Usage : $beagle->set_tree($tree); Function: Sets tree to analyze Returns : $self Args : Bio::Phylo::Forest::Tree object
Type : Mutator Title : set_model Usage : $beagle->set_model($model); Function: Sets model Returns : $self Args : Bio::Phylo::Models::Substitution::Dna object
This function copies a category weights array into an instance buffer.
Type : Mutator Title : set_category_weights Usage : $beagle->set_category_weights( -weights => [1.0] ) Function: Set a category weights buffer Returns : error code Args : -weights => [ Category weights array (categoryCount) (input) ] -index => Optional: index of category weights buffer
This function sets the vector of category rates for an instance.
Type : Mutator Title : set_category_rates Usage : $beagle->set_category_rates( 1.0 ) Function: Set category rates Returns : error code Args : Array containing categoryCount rate scalers (input)
This function copies an eigen-decomposition into an instance buffer.
Type : Mutator Title : set_eigen_decomposition Usage : $beagle->set_eigen_decomposition( %args ) Function: Set an eigen-decomposition buffer Returns : error code Args : -index => Optional: index of eigen-decomposition buffer -vectors => Flattened matrix (stateCount x stateCount) of eigen-vectors (input) -inverse_vectors => Flattened matrix (stateCount x stateCount) of inverse-eigen- vectors (input) -values => Vector of eigenvalues
Gets the matrix
Type : Accessor Title : get_matrix Usage : my $matrix = $beagle->get_matrix; Function: Gets matrix Returns : Bio::Phylo::Matrices::Matrix Args : NONE
Gets underlying beagle instance
Type : Accessor Title : get_instance Usage : my $instance = $beagle->get_instance; Function: Gets instance index Returns : beagle instance index Args : NONE
Gets tree
Type : Accessor Title : get_tree Usage : my $tree = $beagle->get_tree; Function: Gets tree Returns : Bio::Phylo::Forest::Tree Args : NONE
Gets model
Type : Accessor Title : get_model Usage : my $model = $beagle->get_model; Function: Gets model Returns : Bio::Phylo::Models::Substitution::Dna Args : NONE
This function calculates a list of transition probabilities matrices and their first and second derivatives (if requested).
Type : Mutator Title : update_transition_matrices Usage : $beagle->update_transition_matrices( %args ) Function: Calculate a list of transition probability matrices Returns : error code Args : -index => Optional: Index of eigen-decomposition buffer -deriv1 => Optional: List of indices of first derivative matrices to update -deriv2 => Optional: List of indices of second derivative matrices to update
This function either calculates or queues for calculation a list partials. Implementations supporting ASYNCH may queue these calculations while other implementations perform these operations immediately and in order.
Type : Mutator Title : update_partials Usage : $beagle->update_partials( %args ) Function: Calculate or queue for calculation partials using a list of operations Returns : error code Args : -operations => Bio::Phylo::BeagleOperations::Array -count => Number of operations (input) -index => Index number of scaleBuffer to store accumulated factors (input)
Type : Mutator Title : calculate_root_log_likelihoods Usage : $beagle->calculate_root_log_likelihoods Function: Calculate site log likelihoods at a root node Returns : log likelihood Args : -category_weights_indices => Optional: List of weights to apply to each partialsBuffer (input). There should be one categoryCount sized set for each of parentBufferIndices -state_frequencies_indices => Optional: List of state frequencies for each partialsBuffer (input). There should be one set for each of parentBufferIndices -count => Optional: Number of partialsBuffer to integrate (input) -cumulative_scale_indices => Optional: List of scaleBuffers containing accumulated factors to apply to each partialsBuffer (input). There should be one index for each of parentBufferIndices
It is very instructive to study the code SWIG generates from beagle.i
beagle.i
Also see the manual: Bio::Phylo::Manual and http://biophylo.blogspot.com.
If you use Bio::Phylo in published research, please cite it:
Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. http://dx.doi.org/10.1186/1471-2105-12-63
To install Bio::Phylo::Beagle, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bio::Phylo::Beagle
CPAN shell
perl -MCPAN -e shell install Bio::Phylo::Beagle
For more information on module installation, please visit the detailed CPAN module installation guide.