NAME

Bio::Phylo::Models::Substitution::Dna - DNA substitution model

SYNOPSIS

    use Bio::Phylo::Models::Substitution::Dna;

    # create a DNA substitution model from scratch
    my $model = Bio::Phylo::Models::Substitution::Dna->new(
        '-type'   => 'GTR',
        '-pi'     => [ 0.23, 0.27, 0.24, 0.26 ],
        '-kappa'  => 2,
        '-alpha'  => 0.9,
        '-pinvar' => 0.5,
        '-ncat'   => 6,
        '-median' => 1,
        '-rate'   => [
            [ 0.23, 0.23, 0.23, 0.23 ],
            [ 0.23, 0.26, 0.26, 0.26 ],
            [ 0.27, 0.26, 0.26, 0.26 ],
            [ 0.24, 0.26, 0.26, 0.26 ]
        ]
    );

    # get substitution rate from A to C
    my $rate = $model->get_rate('A', 'C');

    # get model representation that can be used by Garli
    my $modelstr = $model->to_string( '-format' => 'garli' )

DESCRIPTION

This is a superclass for models of DNA evolution. Classes that inherit from this class provide methods for retreiving general parameters such as substitution rates or the number of states as well as model-specific parameters. Currently most of the popular models are implemented. The static function "modeltest" determines the substitution model from a Bio::Phylo::Matrices::Matrix object and returns the appropriate instance of the subclass. This class also provides serialization of a model to standard phylogenetics file formats.

METHODS

CONSTRUCTOR

new

Dna model constructor.

 Type    : Constructor
 Title   : new
 Usage   : my $model = Bio::Phylo::Models::Substitution::Dna->new(%args);
 Function: Instantiates a Bio::Phylo::Models::Substitution::Dna object.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : Optional:
                   -type       => type of model, one of GTR, F81, HKY85, JC69, K80
                   -pi         => base frequencies of bases A, C, G, T
                   -kappa      => ratio transitions/transversions
                   -alpha      => shape parameter (for models of GTR family)
                   -mu         => overall mutation rate
                   -pinvar     => proportion of invariant sites
                   -ncat       => number of distinct rate categories
                   -median     => median for gamma-modeled rate categories
                   -rate       => Array of Arrays (4x4) giving substitution rates betwen A, C, T, G
                   -catweights => weights for rate categories

get_catrates

Getter for rate categories, implemented by child classes.

 Type    : method
 Title   : get_catrates
 Usage   : $model->get_catrates;
 Function: Getter for rate categories.
 Returns : scalar or array
 Args    : None.

get_nst

Getter for number of transition rate parameters.

 Type    : method
 Title   : get_nst
 Usage   : $model->get_nst;
 Function: Getter for number of transition rate parameters.
 Returns : scalar
 Args    : None.

get_rate

Getter for substitution rate. If bases are given as arguments, returns corresponding rate. If no arguments given, returns rate matrix or overall rate, dependent on model.

 Type    : method
 Title   : get_rate
 Usage   : $model->get_rate('A', 'C');
 Function: Getter for transition rate between nucleotides.
 Returns : scalar or array
 Args    : Optional:
           base1: scalar
           base2: scalar

get_nstates

Getter for number of states (bases).

 Type    : method
 Title   : get_nstates
 Usage   : $model->get_nstates;
 Function: Getter for transition rate between nucleotides.
 Returns : scalar
 Args    : None

get_ncat

Getter for number of rate categories.

 Type    : method
 Title   : get_ncat
 Usage   : $model->get_ncat;
 Function: Getter for number of rate categories.
 Returns : scalar
 Args    : None

get_catweights

Getter for weights on rate categories.

 Type    : method
 Title   : get_catweights
 Usage   : $model->get_catweights;
 Function: Getter for number of rate categories.
 Returns : array
 Args    : None

get_kappa

Getter for transition/transversion ratio.

 Type    : method
 Title   : get_kappa
 Usage   : $model->get_kappa;
 Function: Getter for transition/transversion ratio.
 Returns : scalar
 Args    : None

get_alpha

Getter for shape parameter.

 Type    : method
 Title   : get_alpha
 Usage   : $model->get_alpha;
 Function: Getter for shape parameter.
 Returns : scalar
 Args    : None

get_mu

Getter for overall mutation rate.

 Type    : method
 Title   : get_mu
 Usage   : $model->get_mu;
 Function: Getter for overall mutation rate.
 Returns : scalar
 Args    : None

get_pinvar

Getter for proportion of invariant sites.

 Type    : method
 Title   : get_pinvar
 Usage   : $model->get_pinvar;
 Function: Getter for proportion of invariant sites.
 Returns : scalar
 Args    : None

get_pi

Getter for base frequencies.

 Type    : method
 Title   : get_pi
 Usage   : $model->get_pi;
 Function: Getter for base frequencies.
 Returns : array
 Args    : Optional:
           Base (A, C, T or G)

get_median

Getter for median for gamma-modeled rate categories.

 Type    : method
 Title   : get_median
 Usage   : $model->get_median;
 Function: Getter for median.
 Returns : scalar
 Args    : None

set_rate

Setter for substitution rate.

 Type    : method
 Title   : set_rate
 Usage   : $model->set_rate(1);
 Function: Set nucleotide transition rates.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : scalar or array of arrays (4x4)

set_ncat

Setter for number of rate categories.

 Type    : method
 Title   : set_ncat
 Usage   : $model->set_ncat(6);
 Function: Set the number of rate categoeries.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : scalar

set_catweights

Setter for weights on rate categories.

 Type    : method
 Title   : set_catweights
 Usage   : $model->get_catweights;
 Function: Set number of rate categories.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : array

set_kappa

Setter for weights on rate categories.

 Type    : method
 Title   : set_kappa
 Usage   : $model->set_kappa(2);
 Function: Set transition/transversion ratio.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : scalar

set_alpha

Setter for shape parameter.

 Type    : method
 Title   : set_alpha
 Usage   : $model->set_alpha(1);
 Function: Set shape parameter.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : scalar

set_mu

Setter for overall mutation rate.

 Type    : method
 Title   : set_mu
 Usage   : $model->set_mu(0.5);
 Function: Set overall mutation rate.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : scalar

set_pinvar

Set for proportion of invariant sites.

 Type    : method
 Title   : set_pinvar
 Usage   : $model->set_pinvar(0.1);
 Function: Set proportion of invariant sites.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : scalar

set_pi

Setter for base frequencies.

 Type    : method
 Title   : get_pi
 Usage   : $model->set_pi((0.2, 0.2, 0.3, 0.3));
 Function: Set base frequencies.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : array of four base frequencies (A, C, G, T)
 Comments: Base frequencies must sum to one

set_median

Setter for median for gamma-modeled rate categories.

 Type    : method
 Title   : set_median
 Usage   : $model->set_median(1);
 Function: Setter for median.
 Returns : A Bio::Phylo::Models::Substitution::Dna object.
 Args    : scalar

modeltest

Performing a modeltest using the package 'phangorn' in R (Schliep, Bioinformatics (2011) 27 (4): 592-593) from an DNA alignment. If no tree is given as argument, a neighbor-joining tree is generated from the alignment to perform model testing. Selects the model with the minimum AIC.

 Type    : method
 Title   : modeltest
 Usage   : $model->modeltest(-matrix=>$matrix);
 Function: Determine DNA substitution model from alignment.
 Returns : An object which is subclass of Bio::Phylo::Models::Substitution::Dna.
 Args    : -matrix: A Bio::Phylo::Matrices::Matrix object
           Optional:
           -tree: A Bio::Phylo::Forest::Tree object
           -timeout: Timeout in seconds to prevent getting stuck in an R process.
 Comments: Prerequisites: Statistics::R, R, and the R package phangorn.

to_string

Get string representation of model in specified format (paup, phyml, mrbayes or garli)

 Type    : method
 Title   : to_string
 Usage   : $model->to_string(-format=>'mrbayes');
 Function: Write model to string.
 Returns : scalar
 Args    : scalar
 Comments: format must be either paup, phyml, mrbayes or garli

CITATION

If you use Bio::Phylo in published research, please cite it: