Skip to content
Generate a tree for displaying a hierarchy of groups with colors, scaling, and more.
Haskell HTML Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app
img
src/BirchBeer
Dockerfile
LICENSE
README.html
README.org
Setup.hs
birch-beer.cabal
index.html
stack.yaml

README.org

birch-beer

Website

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

Description

img/piechart_pruned_tree.png

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

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

img/complete_default_tree.png

Number overlay

img/numbered_pruned_tree.png

Distance overlay

img/modularity_pruned_tree.png

Continuous color saturation

img/cd4_saturated_10_dendrogram.png

Continuous multi-color saturation

img/cd4_cd8_sat_10_dendrogram.png

Diversity of labels

img/diversity_pruned_tree.png

You can’t perform that action at this time.