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