Bio::Phylo::Models::Substitution::Dna(3)

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

SEE ALSO
There is a mailing list at <https://groups.google.com/forum/#!forum/bio-phylo> for any user or developer questions and discussions.

Bio::Phylo::Manual
    Also see the manual: Bio::Phylo::Manual and <http://rutgervos.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>