NAME

p3treeplot.pl - uses R to create PPP trees from a NEXUS file

SYNOPSIS

p3treeplot.pl NEXUSFileName [charlabel1 charlabel2 ... ]

DESCRIPTION

This is a command-line script that draws all (default) or some (if charlabels are listed) of the posterior probability of presence trees represented in the history block in a NEXUS file.

FEEDBACK

All feedback (bugs, feature enhancements, etc.) are greatly appreciated.

AUTHOR

Tom Hladish

VERSION

$Revision: 1.6 $

SUBROUTINES

parse_ARGV

 Title   : parse_ARGV
 Usage   : (input_filename, output_filename, charlabel_subset) = &parse_ARGV (@ARGV);
 Function: assigns certain variables based on command-line arguments
 Returns : (1) NEXUS source filename, (2) output filename to be created, 
           (3) reference to array of subset of introns to be plotted
 Args    : array of command-line arguments
 Comments: 

read_nexus

 Title   : read_nexus
 Usage   : (character_labels, otu_objects, root_object) = &read_nexus ($NEXUSfile)
 Function: reads the relevant information from a NEXUS History Block
 Returns : references to (1) array of character labels, (2) array of otu objects, 
           (3) root object
 Args    : name of source NEXUS file with History Block, with path if necessary
 Comments: 

read_pres_prob

 Title   : read_pres_prob
 Usage   : probability_of_presence_data_structure = &read_pres_prob (otu_objects, 
           character_labels);
 Function: reads the relevant information from a NEXUS History Block
 Returns : reference to hash (keys = intron names) of hashes (keys = node names) of 
           probability data for all nodes
 Args    : references to (1) otu objects and (2) character labels (i.e. intron names)
 Comments: 

matrix_builder

 Title   : matrix_builder
 Usage   : (nexus_data_matrix, max_branch_length) = &matrix_builder (root_object);
 Function: constructs preliminary nexmatrix, determines maximum branch length
 Returns : reference to array (each element corresponds to one line drawn in R) of arrays 
           (of structure [parentnode, childnode, branchlength]); also returns scalar of 
           maximum distance from root to leaf
 Args    : reference to root object
 Comments: Should be possible to condense the top-level loops into just one 'for' loop (TH)

intron_sorter

 Title   : intron_sorter
 Usage   : sorted_introns = &intron_sorter (intron_names_list);
 Function: sorts intron names numerically rather than as strings (as with the 'sort' 
           function)
 Returns : reference to array of sorted names
 Args    : list or array of intron names
 Comments: Works for introns that match pattern /\d+-\d/.  May not work for other names. (TH)

numerically

 Title   : numerically
 Usage   : array_of_numbers = sort numerically array_of_numbers;
 Function: tells 'sort' function how to sort numbers
 Returns : 0 if $a and $b are equal, 1 if $a is greater, -1 if $b is greater
 Args    : None; or rather, 'sort' idiomatically passes special variables $a and $b
 Comments: 

include_pres_probs

 Title   : include_pres_probs
 Usage   : nexus_data_matrix = &include_pres_probs (nexus_data_matrix, sorted_introns);
 Function: adds probability of presence data to nexus_data_matrix; also unshifts column names 
           into first row of matrix
 Returns : reference to array of arrays (i.e., the updated nexus_data_matrix)
 Args    : reference to array of arrays (preliminary nexus_data_matrix), reference to array 
           of sorted intron names
 Comments: Columns (corresponding to each intron) with probability data for at each node are 
           added to the matrix in the order provided in sorted_introns. 

optimal_layout

 Title   : optimal_layout
 Usage   : (layout, $pagesetup) = &optimal_layout (number_of_plots, $pagesetup);
 Function: determines best way to place N plots on one page; also removes axes labels and 
           shrinks fonts if many plots are on one page
 Returns : reference to [rows_per_page, cols_per_page] array, reference to updated global 
           %pagesetup
 Args    : number of introns to plot, reference to pagesetup hash
 Comments: fits number of introns to number of pages specified by $$pagesetup{'pages'})

write_R

 Title   : write_R
 Usage   : R_commands = &write_R (nexus_data_matrix, probability_of_presence_data_structure, 
           max_branch_length, layout, page_setup_data);
 Function: translates various data structures into R language commands
 Returns : array of R commands
 Args    : references to nexmatrix, presencedata, layout, and pagesetup data structures; 
           maximum distance from root to leaf
 Comments: this subroutine determines all R settings not explicitly laid out in $pagesetup

cpanm Bio::NEXUS

perl -MCPAN -e shell
install Bio::NEXUS