Branch Manager ReadMe File

########## What You Need ##########

The BranchManager ("BM") is a java application.
You need the BranchManager.jar file and a tree file as input.


########## How Get What You Need ###########

Download the BM.zip file (link below the link on which you clicked to read this document).
Unzip the BM.zip file.
You should see a folder/directory, BM_Folder, containing two files:
1. BranchManager.jar
2. BM_Tree_Test.txt
3. A copy of this file, BM_ReadMe.txt

See "To Run" below to understand how to run the program.


########## Java and Windows ##########

On windows computers, the .jar extension of the BranchManager.jar file may sometimes go missing, and execution of the program as detailed below may not work.
If, upon unzipping BM.zip, you see a file called BranchManager (without .jar appended), see how windows lists that file on the command prompt.
If it doesn't show the .jar extension, add it manually.  If you don't know what that means, seek help.


########## The Tree File ##########

The supplied tree must conform to Newick format and can be unrooted or rooted;  it must contain branch lengths.
If you supply a rooted tree, BM will unroot it.

Here is a sample tree that is correctly formatted. This is the same tree as supplied in BM_Tree_Test.txt.

(zf:0.46,xen:0.36,(ch:0.19,(pla:0.21,(arm:0.05,(ele:0.05,((mou:0.02,rat:0.02):0.08,(hum:0.0,chim:0.0):0.03):0.01):0.02):0.07):0.06):0.04);

The BM can tolerate whitespace, including empty lines, anywhere within that tree.
Avoid spaces in your organism or gene names; they will be removed.


########## To Run ##########

You must run the BranchManager from the command line.
Clicking on the icon does not make it run.
If you don't know how to run a program from the command line seek help.

If you're in the same directory as the branch manager:
java -cp Branchmanager.jar BM <tree_file>

If you're not in the same directory:
java -cp <path_to_jar>Branchmanager.jar BM <tree_file>

We recommend running the BM with the verbose flag, like this:
java -cp Branchmanager.jar BM -v <tree_file>

This outputs a text representation of the tree and therefore allows you to visually check whether the tree you supplied is correct.

Running BM without the -v flag only outputs the weights for each sequence, for example:

Node    Weight
zf      0.2034
xen     0.1883
ch      0.1733
pla     0.1362
arm     0.0988
ele     0.0541
mou     0.0528
rat     0.0528
hum     0.0202
chim    0.0202

Caution: The weights may sum to a little more or a little less than 1 due to rounding.


###########  How The *&%$#@ Is This Output Useful?  ############

The BM does not do your science for you.  All it does is supply the weight of each sequence.
How to use those weights for constructing phylogenetic averages of your favorite metric is up to you.


########### End of ReadMe ############