README for the Early Bird "tree_convert" folder

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
FILES:

Hackett_etal2008_cladogram.tre
Hackett_etal2008_cladogramEB.tre
Hackett_etal_2008_taxa.xlsx
README
authority_dupnames.txt
authority_eb2short.txt
authority_long2eb.txt
renametaxa.pl
renametree.pl
rooted_Hackett_Fig2.tre
rooted_Hackett_Fig2shortname.tre
rooted_Hackett_Fig3.tre
rooted_Hackett_etal_2008_trees.tre
unrooted_Hackett_Fig2.tre
unrooted_Hackett_Fig3.tre
unrooted_Hackett_etal_2008_trees.tre

Hackett_etal2008_cladogram.tre and Hackett_etal2008_cladogramEB.tre are
cladograms with full names and "Early Bird" names, respectively. Both are
nexus files with two trees corresponding to both Figures 2 and 3 in Hackett
et al. (2008).

Hackett_etal_2008_taxa.xlsx excel file with the full taxon names, "Early
Bird" (shortened) taxon names, and suggested short (<8 character) names.

README is this file.

authority_xxx.txt files are examples of authority files.

rooted_Hackett_xxx.tre files are trees from Hackett et al. (2008) with
the crocodilian outgroups included. Names are the "Early Bird" names.
rooted_Hackett_etal_2008_trees.tre is a nexus format tree and it includes
both the Figure 2 and the Figure 3 topology, along with parameter estimates
for the GTR+I+G model given the Hackett et al. (2008) dataset. The other
trees are newick format trees.

renametree.pl and renametaxa.pl are simple perl scripts that allow uses to
change taxon names in tree files in a simple manner. They are based upon
the use of authority files, which are text files containing the original
name of the taxon and the desired name. Both scripts check for redundancy
and they will exit if either the original or new names are repeated in the
file.

unrooted_Hackett_xxx.tre files are trees from Hackett et al. (2008) 
without the crocodilian outgroups. Names are the "Early Bird" names.
unrooted_Hackett_etal_2008_trees.tre is a nexus format tree and it includes
both the Figure 2 and the Figure 3 topology, along with parameter estimates
for the GTR+I+G model given the Hackett et al. (2008) dataset. The other
trees are newick format trees.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
THE renameXXXX.pl PROGRAMS:

renametaxa.pl can be used with any file format in which the taxon names are
included, so it is useful for nexus format treefiles with a Translate table.
Because it is so general, you should be careful about names that may 
completely contained within other names. For example, if you have one taxon
named "Phaethon" that you plan to rename "PHRU" and one called
"Phaethon_leptura" that you plan to rename as "PHLE" the program may rename
"Phaethon_leptura" to "PHRU_leptura" if it encounters the "Phaethon" to
"PHRU" instruction before the "Phaethon_leptura" to "PHLE" instruction. You
should inspect the resulting files carefully to make sure the taxon names
have been changed appropriately.

renametaxa.pl can also be used with with many types of data files (e.g., a
nexus file with a data block). If used for this purpose, the left edge of
the characters in the data block are unlikely to line up since renametaxa.pl
does not consider the length of the original and new taxon names. However,
many files manipulated in this way will be read appropriately (i.e., PAUP*
should read a nexus file manipulated in this manner correctly).

renametree.pl assumes that the input tree is in newick (phylip) format. It
changes the names of the taxa in the authority file, but it will be more
robust to the problems described for renametaxa.pl because it only changes
a taxon name if the taxon name is followed by a ":", ")", or "," (as taxon
names should be in newick format trees).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
BASIC USE:

Both scripts are intended to be used from the command line. To use either
program in a unix/Mac OS X) environment, simply make the scripts executable:

$ chmod +x renametaxa.pl renametree.pl

Then run the desired script using a selected input tree and authority file:

$ renameXXXX.pl -i <intree> -o <outtree> -a <authority>

Since both programs are called in a similar manner, they are called 
"renameXXXX.pl" to indicate that either program can be run in this manner.
Depending upon your system your may need to specify a path (e.g., 
"./renameXXXX.pl" if you are in the same directory as the program) to
run the program. For more information, call either program as follows:

$ renameXXXX.pl --help

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
TROUBLESHOOTING:

If you want to check renametree.pl and renametaxa.pl, you can use them
to rename taxa in two specific files. To test renametree.pl in a unix/
Mac OS X environment type:

$ renametree.pl -i rooted_Hackett_Fig2.tre -a authority_eb2short.txt -o test_renametree.out
$ diff test_renametree.out rooted_Hackett_Fig2shortname.tre

To test renametaxa.pl type:

$ renametree.pl -i Hackett_etal2008_cladogram.tre -a authority_long2eb.txt -o test_renametaxa.out
$ diff test_renametaxa.out Hackett_etal2008_cladogramEB.tre

The folder also contains and authority file with duplicate names
(authority_dupnames.txt) that you can use to see the error message that
renameXXXX.pl reports when there are duplicate names in the authority
file.

--Edward Braun, University of Florida Biology


