NAME

Bio::Phylo::Beagle - Perl wrapper around BEAGLE

SYNOPSIS

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

DESCRIPTION

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.

METHODS

FACTORY METHODS

create_instance()

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

create_table()

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

MUTATORS

set_pattern_weights()

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)

set_state_frequencies()

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)

set_matrix()

Type    : Mutator
Title   : set_matrix
Usage   : $beagle->set_matrix($matrix);
Function: Sets matrix to analyze
Returns : $self
Args    : Bio::Phylo::Matrices::Matrix object

set_tree()

Type    : Mutator
Title   : set_tree
Usage   : $beagle->set_tree($tree);
Function: Sets tree to analyze
Returns : $self
Args    : Bio::Phylo::Forest::Tree object

set_model()

Type    : Mutator
Title   : set_model
Usage   : $beagle->set_model($model);
Function: Sets model
Returns : $self
Args    : Bio::Phylo::Models::Substitution::Dna object

set_category_weights()

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

set_category_rates()

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)

set_eigen_decomposition()

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

ACCESSORS

get_matrix()

Gets the matrix

Type    : Accessor
Title   : get_matrix
Usage   : my $matrix = $beagle->get_matrix;
Function: Gets matrix
Returns : Bio::Phylo::Matrices::Matrix
Args    : NONE

get_instance()

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

get_tree()

Gets tree

Type    : Accessor
Title   : get_tree
Usage   : my $tree = $beagle->get_tree;
Function: Gets tree
Returns : Bio::Phylo::Forest::Tree
Args    : NONE

get_model()

Gets model

Type    : Accessor
Title   : get_model
Usage   : my $model = $beagle->get_model;
Function: Gets model
Returns : Bio::Phylo::Models::Substitution::Dna
Args    : NONE

METHODS

update_transition_matrices()

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

update_partials()

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)

calculate_root_log_likelihoods()

This function calculates a list of transition probabilities matrices and their first and second derivatives (if requested).

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

SEE ALSO

beagle

It is very instructive to study the code SWIG generates from beagle.i

Bio::Phylo::Manual

Also see the manual: Bio::Phylo::Manual and http://biophylo.blogspot.com.

CITATION

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