Rutger Vos > Bio-Phylo-Beagle-0.03 > Bio::Phylo::Beagle

Download:
Bio-Phylo-Beagle-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  

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

syntax highlighting: