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