README.org

birch-beer

Website

See https://github.com/GregorySchwartz/birch-beer for latest version.

Description

birch-beer is all about sweet trees. That is, visualizing hierarchical structures where the elements are stored in leaves and parent nodes represent all of the descendant leaves. Using branch scaling, weighted average color blending, distance markers, and more, we can all create some home brewed birch-beer together!

Installation

Use nix

Installing birch-beer using nix is the easiest way to install from source. First, install nix following the instructions on the website. Then run the commands:

git clone https://github.com/GregorySchwartz/birch-beer.git
cd birch-beer
nix-env -f default.nix -i birch-beer

Then the birch-beer command should be in your path! If you do not wish to use nix or docker, then you can continue reading for dependencies and stack installation (no longer supported).

Dependencies

You may require the following dependencies to build and run (from Ubuntu 16.04, use the appropriate packages from your distribution of choice):

• build-essential
• libgmp-dev
• libblas-dev
• liblapack-dev
• libgsl-dev
• libgtk2.0-dev
• libcairo2-dev
• libpango1.0-dev
• graphviz

Install stack

See https://docs.haskellstack.org/en/stable/README/ for more details.

curl -sSL https://get.haskellstack.org/ | sh
stack setup

Install birch-beer

Source

Probably the easiest method if you don’t want to mess with dependencies (outside of the ones above).

git clone https://github.com/GregorySchwartz/birch-beer.git
cd birch-beer
stack install

Online

We only require stack (or cabal), you do not need to download any source code (but you might need the stack.yaml dependency versions), just run the following command to place birch-beer in your ~/.local/bin/:

stack install birch-beer

If you run into errors like Error: While constructing the build plan, the following exceptions were encountered:, then follow it’s advice. Usually you just need to follow the suggestion and add the dependencies to the specified file. For a quick yaml configuration, refer to https://github.com/GregorySchwartz/birch-beer/blob/master/stack.yaml. Relies on eigen-3.3.4.1 right now.

Docker

Different computers have different setups, operating systems, and repositories. Do put the entire program in a container to bypass difficulties (with the other methods above), we user docker. So first, install docker.

To get birch-beer (replace 0.1.0.0 with any version needed):

docker pull gregoryschwartz/birch-beer:0.1.0.0

To run birch-beer in a docker container:

sudo docker run gregoryschwartz/birch-beer:0.1.0.0 -h

To build the birch-beer image yourself if you want:

git clone https://github.com/GregorySchwartz/birch-beer.git
cd birch-beer
docker build -t birch-beer -f ./Dockerfile .

Usage

For a more detailed look at many of the features, check out the too-many-cells README about make-tree, which uses birch-beer to plot single cell clades with examples. At any point, use birch-beer -h to see the help. The general usage would be:

birch-beer --input tree.json --labels-file labels.csv

Tree format

The input tree format should be a json file with a recursive structure. An object is represented by [{"_distance": DOUBLE, "_item": [STRING]}, [SUBFOREST]], where "_distance" and "_item" are optional (otherwise use {}), having "_distance" for inner nodes and "_item" for leaves. Supports rose trees as well! For example:

[{"_distance": 0.8}, [[{"_item": ["1", "2"]}, [[{"_item": ["3", "4", "5"]}, []], [{"_item": ["6", "7"]}, []]]], [{"_item": ["8", "9", "10", "11"]}, []]]]

Example conversion from R

To get to the required format, here is an example to get from an R hclust tree to the appropriate json.

library(dendextend)
library(data.tree)
library(jsonlite)

# Get hclust tree.
hc = hclust(dist(USArrests), "ave")
# Get dendrogram.
dend = as.dendrogram(hc)
# Get nicely formatted tree from dendrogram.
tree = as.Node(dend)
# Convert to JSON
json = toJSON(as.list(tree, mode = "explicit", unname = TRUE))
# Write to file
cat(json, file = "tree.json")

Saving this file as tree.json, we continue to format as such (this could be a single command, but was split to make clearer). Here, we use jq , the command line json processor.

cat tree.json \
    | jq -c 'walk( if (type == "object") then (if (has("leaf") | not) then del(.name) else . end) else . end)' \
    | jq -c 'walk( if (type == "object") then del(.members) | del(.midpoint) | del(.value) | del(.plotHeight) else . end)' \
    | jq -c 'walk( if (type == "object") then (if (has("leaf")) then ._item = .name | del(.name) else . end) else . end)' \
    | jq -c 'walk( if (type == "object") then (if (has("leaf") | not) then [{}, [.children[]]] else . end) else . end)' \
    | jq -c 'walk( if (type == "object") then (if (has("leaf")) then [{_item}, []] else . end) else . end)' \
    > formatted_tree.json

Then we can see the tree using birch-beer.

birch-beer -i formatted_tree.json

Labels format

To assign labels (and thus colors) to the elements within the tree, make a csv file with an item,label format. Both columns are treated as strings, so anything can be used as long as the item column matches the item strings in the tree. For example to go with the above tree:

item,label
1,1
2,1
3,2
4,2
5,2
6,3
7,1
8,1
9,3
10,3
11,2

Select examples

Large tree

Number overlay

Distance overlay

Continuous color saturation

Continuous multi-color saturation

Diversity of labels