Bio::Phylo::Generator(3)

NAME
Bio::Phylo::Generator - Generator of tree topologies

SYNOPSIS
 use Bio::Phylo::Factory;
 my $fac = Bio::Phylo::Factory->new;
 my $gen = $fac->create_generator;
 my $trees = $gen->gen_rand_pure_birth(
     '-tips'  => 10,
     '-model' => 'yule',
     '-trees' => 10,
 );

 # prints 'Bio::Phylo::Forest'
 print ref $trees;

DESCRIPTION
The generator module is used to simulate trees under various models.

METHODS

  CONSTRUCTOR

new()
    Generator constructor.

     Type    : Constructor
     Title   : new
     Usage   : my $gen = Bio::Phylo::Generator->new;
     Function: Initializes a Bio::Phylo::Generator object.
     Returns : A Bio::Phylo::Generator object.
     Args    : NONE

  GENERATOR

gen_rand_pure_birth()
    This method generates a Bio::Phylo::Forest object populated with Yule/Hey trees.

     Type    : Generator
     Title   : gen_rand_pure_birth
     Usage   : my $trees = $gen->gen_rand_pure_birth(
                   '-tips'  => 10,
                   '-model' => 'yule',
                   '-trees' => 10,
               );
     Function: Generates markov tree shapes,
               with branch lengths sampled
               from a user defined model of
               clade growth, for a user defined
               number of tips.
     Returns : A Bio::Phylo::Forest object.
     Args    : -tips  => number of terminal nodes (default: 10),
               -model => either 'yule' or 'hey',
               -trees => number of trees to generate (default: 10)
               Optional: -factory => a Bio::Phylo::Factory object

gen_rand_birth_death()
    This method generates a Bio::Phylo::Forest object populated under a birth/death model

     Type    : Generator
     Title   : gen_rand_birth_death
     Usage   : my $trees = $gen->gen_rand_birth_death(
                   '-tips'     => 10,
                   '-killrate' => 0.2,
                   '-trees'    => 10,
               );
     Function: Generates trees where any growing lineage is equally
               likely to split at any one time, and is equally likely
               to go extinct at '-killrate'
     Returns : A Bio::Phylo::Forest object.
     Args    : -tips  => number of terminal nodes (default: 10),
               -killrate => extinction over speciation rate (default: 0.2)
               -trees => number of trees to generate (default: 10)
               Optional: -factory => a Bio::Phylo::Factory object
     Comments: Past extinction events are retained as unbranched internal
               nodes in the produced trees.

gen_exp_pure_birth()
    This method generates a Bio::Phylo::Forest object populated with Yule/Hey trees whose branch lengths are proportional to the expected waiting times (i.e. not sampled from a distribution).

     Type    : Generator
     Title   : gen_exp_pure_birth
     Usage   : my $trees = $gen->gen_exp_pure_birth(
                   '-tips'  => 10,
                   '-model' => 'yule',
                   '-trees' => 10,
               );
     Function: Generates markov tree shapes,
               with branch lengths following
               the expectation under a user
               defined model of clade growth,
               for a user defined number of tips.
     Returns : A Bio::Phylo::Forest object.
     Args    : -tips  => number of terminal nodes (default: 10),
               -model => either 'yule' or 'hey'
               -trees => number of trees to generate (default: 10)
               Optional: -factory => a Bio::Phylo::Factory object

gen_coalescent()
    This method generates coalescent trees for a given effective population size (popsize) and number of alleles (tips) such that the probability of coalescence in the previous generation for any pair of alleles is 1 / ( 2 * popsize ).

     Type    : Generator
     Title   : gen_coalescent
     Usage   : my $trees = $gen->gen_coalescent(
                   '-tips'    => 10,
                   '-popsize' => 100,
                   '-trees'   => 10,
               );
     Function: Generates coalescent trees.
     Returns : A Bio::Phylo::Forest object.
     Args    : -tips    => number of terminal nodes (default: 10)
               -popsize => effective population size (default: 100)
               -trees   => number of trees to generate (default: 10)
               Optional: -factory => a Bio::Phylo::Factory object

gen_equiprobable()
    This method draws tree shapes at random, such that all shapes are equally probable.

     Type    : Generator
     Title   : gen_equiprobable
     Usage   : my $trees = $gen->gen_equiprobable( '-tips' => 10 );
     Function: Generates an equiprobable tree
               shape, with branch lengths = 1;
     Returns : A Bio::Phylo::Forest object.
     Args    : Optional: -tips  => number of terminal nodes (default: 10),
               Optional: -trees => number of trees to generate (default: 1),
               Optional: -factory => a Bio::Phylo::Factory object

gen_balanced()
    This method creates the most balanced topology possible given the number of tips

     Type    : Generator
     Title   : gen_balanced
     Usage   : my $trees = $gen->gen_balanced( '-tips'  => 10 );
     Function: Generates the most balanced topology
               possible, with branch lengths = 1;
     Returns : A Bio::Phylo::Forest object.
     Args    : Optional: -tips  => number of terminal nodes (default: 10),
               Optional: -trees => number of trees to generate (default: 1),
               Optional: -factory => a Bio::Phylo::Factory object

gen_ladder()
    This method creates a ladder tree for the number of tips

     Type    : Generator
     Title   : gen_ladder
     Usage   : my $trees = $gen->gen_ladder( '-tips'  => 10 );
     Function: Generates the least balanced topology
               (a ladder), with branch lengths = 1;
     Returns : A Bio::Phylo::Forest object.
     Args    : Optional: -tips  => number of terminal nodes (default: 10),
               Optional: -trees => number of trees to generate (default: 1),
               Optional: -factory => a Bio::Phylo::Factory object

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>