# see Bio::Tools::Phylo::PAML for example usage
  use Bio::Tools::Phylo::PAML;
  my $parser = new Bio::Tools::Phylo::PAML
    (-file => "./results/mlc", -dir => "./results/");

  # get the first/next result; a Bio::Tools::Phylo::PAML::Result object,
  # which isa Bio::SeqAnalysisResultI object.
  my $result = $parser->next_result();

  my @seqs         = $result->get_seqs;
  my %input_params = $result->get_input_parameters;
  my @basfreq      = $result->get_codon_pos_basefreq;
  my $MLmatrix     = $result->get_MLmatrix; # get MaxLikelihood Matrix
  my $NGmatrix     = $result->get_NGmatrix; # get Nei-Gojoburi Matrix

  # for AAML runs
  my $AAmatrix   = $result->get_AADistMatrix;
  my $AAMLmatrix   = $result->get_AAMLDistMatrix;

  # if -dir contains an rst file get list of
  # Bio::PrimarySeq ancestral state reconstructions of the sequences
  my @rsts          = $result->get_rst_seqs; 

  # if you want to print the changes on the tree
  # this will print out the 
  # anc_aa       => ANCESTRAL AMINO ACID
  # anc_prob     => ANCESTRAL AA PROBABILITY 
  # derived_aa   => DERIVED AA
  # derived_prob => DERIVE AA PROBABILITY (where appropriate - NA for extant/tip taxas)
  # site         => which codon site this in the alignment
    @trees = $result->get_rst_trees;
    for my $t ( @trees ) {
	for my $node ( $t->get_nodes ) {	
	    next unless $node->ancestor; # skip root node
	    my @changes = $node->get_tag_values('changes');
	    my $chgstr = '';
	    for my $c ( @changes ) { 
		for my $k ( sort keys %$c ) {
		    $chgstr .= "$k => $c->{$k} ";
		}
		$chgstr .= "\n\t";
	    }

	    printf "node:%s n=%s s=%s\n\t%s\n",
	    $node->id, 
	    $node->get_tag_values('n'),
	    $node->get_tag_values('s'),
	    $chgstr;
	}
    }

  # Persite probabilities
  my $persite = $result->get_rst_persite;
  # let's score site 1
  $site = $persite->[2]; 
  # so site 2, node 2 (extant node, node 2)
  print $site->[2]->{'codon'}, ' ',$site->[2]->{'aa'},"\n";
  # site 2, node 3
  print $site->[3]->{'codon'}, ' ',$site->[3]->{'aa'}, "\n";

  # ancestral node 9, codon, aa, marginal probabilities; Yang95 is listed as 
  #  (eqn. 4 in Yang et al. 1995 Genetics 141:1641-1650) in PAML rst file.
  print $site->[9]->{'codon'}, ' ',$site->[9]->{'aa'}, ' ', $site->[9]->{'prob'}, ' ',
        $site->[9]->{'Yang95_aa'},' ', $site->[9]->{'Yang95_aa_prob'},"\n";

  my($class,@args) = @_;

  my $self = $class->SUPER::new(@args);
  my ($trees,$mlmat,$seqs,$ngmatrix,
      $codonpos,$codonfreq,$version,
      $model,$patterns, $stats,
      $aafreq, $aadistmat, 
      $aamldistmat,
      $ntfreqs, $seqfile, $kappa_mat, $alpha_mat,
      $NSSitesresults,$input_params,$rst,$rst_persite,$rst_trees ) = 
	  $self->_rearrange([qw
			     (TREES MLMATRIX 
			      SEQS NGMATRIX
			      CODONPOS CODONFREQ
			      VERSION MODEL PATTERNS
			      STATS AAFREQ AADISTMAT
			      AAMLDISTMAT 
			      NTFREQ SEQFILE
			      KAPPA_DISTMAT
			      ALPHA_DISTMAT
			      NSSITESRESULTS
			      INPUT_PARAMS
			      RST RST_PERSITE RST_TREES)], 
			    @args);
  $self->reset_seqs;
  if( $trees ) {
      if(ref($trees) !~ /ARRAY/i ) { 
	  $self->warn("Must have provided a valid array reference to initialize trees");
      } else { 
	  foreach my $t ( @$trees ) {
	      $self->add_tree($t);
	  }
      }
  }
  $self->{'_treeiterator'} = 0;

  if( $mlmat ) {
      if( ref($mlmat) !~ /ARRAY/i ) {
	  $self->warn("Must have provided a valid array reference to initialize MLmatrix");
      } else { 
	  $self->set_MLmatrix($mlmat);
      }
  } 
  if( $seqs ) { 
      if( ref($seqs) !~ /ARRAY/i ) {
	  $self->warn("Must have provided a valid array reference to initialize seqs");
      } else {
	  foreach my $s ( @$seqs ) {
	      $self->add_seq($s);
	  }
      }
  }
  if( $ngmatrix ) {
      if( ref($ngmatrix) !~ /ARRAY/i ) {
	  $self->warn("Must have provided a valid array reference to initialize NGmatrix");
      } else { 
	  $self->set_NGmatrix($ngmatrix);
      }
  } 
  if( $codonfreq ) {
      if( ref($codonfreq) =~ /ARRAY/i ) {
	  $self->set_CodonFreqs($codonfreq);
      } else { 
	  $self->warn("Must have provided a valid array reference to initialize codonfreq");
      }
  }

  if( $codonpos ) {
      if( ref($codonpos) !~ /ARRAY/i ) {
	  $self->warn("Must have provided a valid array reference to initialize codonpos");
      } else { 
	  $self->set_codon_pos_basefreq(@$codonpos);
      }
  }

  $self->version($version)   if defined $version;
  $self->seqfile($seqfile)   if defined $seqfile;
  $self->model($model)       if defined $model;
  if( defined $patterns ) {
      if( ref($patterns) =~ /HASH/i ) {
	  $self->patterns($patterns);
      } else {
	  $self->warn("Must have provided a valid array reference to initialize patterns");
      }
  }

  $self->{'_aafreqs'} = {};
  if( $aafreq ) {
      if( ref($aafreq) =~ /HASH/i ) {
	  $self->set_AAFreqs($aafreq);
      } else { 
	  $self->warn("Must have provided a valid hash reference to initialize aafreq");
      }
  }
  if( $stats ) {
      if( ref($stats) =~ /HASH/i ) {
	  while( my ($stat,$val) = each %$stats) {
	      $self->add_stat($stat,$val);
	  }
      } else { 
	  $self->warn("Must have provided a valid hash reference initialize stats");
      }
  }
  $self->set_AADistMatrix($aadistmat) if defined $aadistmat;
  $self->set_AAMLDistMatrix($aamldistmat) if defined $aamldistmat;

  if( defined $NSSitesresults ) {
      if( ref($NSSitesresults) !~ /ARRAY/i ) {
	  $self->warn("expected an arrayref for -NSSitesresults");
      } else { 
	  foreach my $m ( @$NSSitesresults ) {
	      $self->add_NSSite_result($m);
	  }
      }
  }

  $self->{'_ntfreqs'} = {};
  if( $ntfreqs ) {
      if( ref($ntfreqs) =~ /HASH/i ) {
	  $self->set_NTFreqs($ntfreqs);
      } else { 
	  $self->warn("Must have provided a valid hash reference to initialize ntfreq");
      }
  }

  if( $kappa_mat ) {
      $self->set_KappaMatrix($kappa_mat);
  } 
  if( $alpha_mat ) {
      $self->set_AlphaMatrix($alpha_mat);
  }

  if( $input_params ) {
      if(  ref($input_params) !~ /HASH/i ) {
	  $self->warn("need a valid HASH object for input_params\n");
      } else {
	  while( my ($p,$v) = each %$input_params ) {
	      $self->set_input_parameter($p,$v);
	  }
      }
      
  }
  $self->reset_rst_seqs;
  if( $rst ) {
      if( ref($rst) =~ /ARRAY/i ) {	  
	  for ( @$rst ) {
	      $self->add_rst_seq($_);
	  }
      } else {
	  $self->warn("Need a valid array ref for -rst option\n");
      }
  }
  if( defined $rst_persite ) {
      $self->set_rst_persite($rst_persite);
  }
  $self->reset_rst_trees;
  if( $rst_trees ) {
      if( ref($rst_trees) =~ /ARRAY/i ) {	  
	  for ( @$rst_trees ) {
	      $self->add_rst_tree($_);
	  }
      } else {
	  $self->warn("Need a valid array ref for -rst_trees option\n");
      }
  }

  return $self;

   my ($self,@args) = @_;
   return $self->{'_trees'}->[$self->{'_treeiterator'}++] || undef;

   my ($self) = @_;
   return @{$self->{'_trees'} || []};

    shift->{'_treeiterator'} = 0;

   my ($self,$tree) = @_;
   if( $tree && ref($tree) && $tree->isa('Bio::Tree::TreeI') ) {
       push @{$self->{'_trees'}},$tree;
   }
   return scalar @{$self->{'_trees'}};

   my ($self,$mat) = @_;
   return unless ( defined $mat );
   if( ref($mat) !~ /ARRAY/i ) {
       $self->warn("Did not provide a valid 2D Array reference for set_MLmatrix");
       return;
   }
   $self->{'_mlmatrix'} = $mat;

   my ($self,@args) = @_;
   return $self->{'_mlmatrix'};

   my ($self,$mat) = @_;
   return unless ( defined $mat );
   if( ref($mat) !~ /ARRAY/i ) {
       $self->warn("Did not provide a valid 2D Array reference for set_NGmatrix");
       return;
   }
   $self->{'_ngmatrix'} = $mat;

   my ($self,@args) = @_;
   return $self->{'_ngmatrix'};

   my ($self,$seq) = @_;
   if( $seq ) { 
       unless( $seq->isa("Bio::PrimarySeqI") ) {
	   $self->warn("Must provide a valid Bio::PrimarySeqI to add_seq");
	   return;
       }
       push @{$self->{'_seqs'}},$seq;
   }

   my ($self) = @_;
   $self->{'_seqs'} = [];

   my ($self) = @_;
   return @{$self->{'_seqs'}};

    my ($self,@codonpos) = @_;
    if( scalar @codonpos != 3 ) { 
	$self->warn("invalid array to set_codon_pos_basefreq, must be an array of length 3");
	return;
    }
    foreach my $pos ( @codonpos ) { 
	if( ref($pos) !~ /HASH/i ||
	    ! exists $pos->{'A'} ) { 
	    $self->warn("invalid array to set_codon_pos_basefreq, must be an array with hashreferences keyed on DNA bases, C,A,G,T");
	}
    }
    $self->{'_codonposbasefreq'} = [@codonpos];

   my ($self) = @_;
   return @{$self->{'_codonposbasefreq'}};

   my $self = shift;
   $self->{'_version'} = shift if @_;
   return $self->{'_version'};

   my $self = shift;
   $self->{'_seqfile'} = shift if @_;
   return $self->{'_seqfile'};

    my $self = shift;

    return $self->{'_model'} = shift if @_;
    return $self->{'_model'};

    my $self = shift;
    return $self->{'_patterns'} = shift if @_;
    return $self->{'_patterns'};

   my ($self,$aafreqs) = @_;
   
   if( $aafreqs && ref($aafreqs) =~ /HASH/i ) {
       foreach my $seqname ( keys %{$aafreqs} ) {
	   $self->{'_aafreqs'}->{$seqname} = $aafreqs->{$seqname};
       }
   }

   my ($self,$seqname) = @_;
   if( $seqname ) {
       return $self->{'_aafreqs'}->{$seqname} || {};
   } else { 
       return $self->{'_aafreqs'};
   }

   my ($self,$freqs) = @_;
   
   if( $freqs && ref($freqs) =~ /HASH/i ) {
       foreach my $seqname ( keys %{$freqs} ) {
	   $self->{'_ntfreqs'}->{$seqname} = $freqs->{$seqname};
       }
   }

   my ($self,$seqname) = @_;
   if( $seqname ) {
       return $self->{'_ntfreqs'}->{$seqname} || {};
   } else { 
       return $self->{'_ntfreqs'};
   }

   my ($self,$stat,$value) = @_;
   return if( ! defined $stat || !defined $value );
   $self->{'_stats'}->{$stat} = $value;
   return;

   my ($self,$statname) = @_;
   return $self->{'_stats'}->{$statname};

   my ($self) = @_;
   return keys %{$self->{'_stats'} || {}};

    my $self = shift;
    return $self->{'_AADistMatix'};

   my ($self,$d) = @_;
   if( ! $d || 
       ! ref($d) ||
       ! $d->isa('Bio::Matrix::PhylipDist') ) {
       $self->warn("Must provide a valid Bio::Matrix::MatrixI for set_AADistMatrix");
   }
   $self->{'_AADistMatix'} = $d;
   return;

    my $self = shift;
    return $self->{'_AAMLDistMatix'};

   my ($self,$d) = @_;
   if( ! $d || 
       ! ref($d) ||
       ! $d->isa('Bio::Matrix::PhylipDist') ) {
       $self->warn("Must provide a valid Bio::Matrix::MatrixI for set_AAMLDistMatrix");
   }
   $self->{'_AAMLDistMatix'} = $d;
   return;

   my ($self,$model) = @_;
   if( defined $model ) {
       push @{$self->{'_nssiteresult'}}, $model;
   }
   return scalar @{$self->{'_nssiteresult'}};

   my ($self) = @_;
   return @{$self->{'_nssiteresult'} || []};

    my $self = shift;

    return $self->{'_codonfreqs'} = shift if @_;
    return $self->{'_codonfreqs'};

   my ($self) = @_;
   return @{$self->{'_codonfreqs'} || []};

    my $self = shift;
    return $self->{'_KappaMatix'};

   my ($self,$d) = @_;
   if( ! $d || 
       ! ref($d) ||
       ! $d->isa('Bio::Matrix::PhylipDist') ) {
       $self->warn("Must provide a valid Bio::Matrix::MatrixI for set_NTDistMatrix");
   }
   $self->{'_KappaMatix'} = $d;
   return;

    my $self = shift;
    return $self->{'_AlphaMatix'};

   my ($self,$d) = @_;
   if( ! $d || 
       ! ref($d) ||
       ! $d->isa('Bio::Matrix::PhylipDist') ) {
       $self->warn("Must provide a valid Bio::Matrix::MatrixI for set_NTDistMatrix");
   }
   $self->{'_AlphaMatix'} = $d;
   return;

   my ($self,$p,$v) = @_;
   return unless defined $p;
   $self->{'_input_parameters'}->{$p} = $v;

   my ($self) = @_;
   return %{$self->{'_input_parameters'} || {}};

   my ($self) = @_;
   $self->{'_input_parameters'} = {};

   my ($self,$seq) = @_;
   if( $seq ) { 
       unless( $seq->isa("Bio::PrimarySeqI") ) {
	   $self->warn("Must provide a valid Bio::PrimarySeqI to add_rst_seq");
	   return;
       }
       push @{$self->{'_rstseqs'}},$seq;
   }

   my ($self) = @_;
   $self->{'_rstseqs'} = [];

   my ($self) = @_;
   return @{$self->{'_rstseqs'} || []};

   my ($self,$tree) = @_;
   if( $tree ) { 
       unless( $tree->isa("Bio::Tree::TreeI") ) {
	   $self->warn("Must provide a valid Bio::Tree::TreeI to add_rst_tree not $tree");
	   return;
       }
       push @{$self->{'_rsttrees'}},$tree;
   }

   my ($self) = @_;
   $self->{'_rsttrees'} = [];

   my ($self) = @_;
   return @{$self->{'_rsttrees'} || []};

    my $self = shift;

    return $self->{'_rstpersite'} = shift if @_;
    return $self->{'_rstpersite'};

   my ($self) = @_;
   return $self->{'_rstpersite'} || [];

  bioperl-l@bioperl.org                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

  http://bugzilla.open-bio.org/

 Email jason-at-bioperl-dot-org
 Email amackey-at-virginia-dot-edu

 Title   : rewind_tree_iterator
 Usage   : $result->rewind_tree()
 Function: Rewinds the tree iterator so that next_tree can be 
           called again from the beginning
 Returns : none
 Args    : none