Advanced topics#

Custom configuration#

There are a number of things you can do customise Taxonium. They all ultimately involve creating a “config” which Taxonium uses to define its behaviour. This config can be specified in several ways, which are listed here in rough order of the priority in which they are applied:

  1. As a config parameter supplied to the URL containing a JSON string, e.g. taxonium.org?protoUrl=xxxx&config={"title":"My tree"}

  2. As a configUrl supplied to the URL pointing to a JSON file, e.g. https://taxonium.org/?protoUrl=https%3A%2F%2Fmpx-tree.vercel.app%2Fmpx.jsonl.gz&configUrl=https://mpx-tree.vercel.app/config.json

  3. As one of several custom parameters to usher_to_taxonium, e.g. --title,--overlay_html.

  4. As a --config_json file passed to usher_to_taxonium.

What you can configure#

You can configure many things. We only discuss some here. For more information have a look at the config used for Cov2Tree.

Colors#

The way that Taxonium handles colurs by default is that they are computed as a hash of the text they represent. That has advantages, because it means that they are consistent over time. But sometimes values of interest can have very similar strings, or may have ugly colours that you wish to change. These can be overwritten using a colorMapping object, You need to supply a config, with a colorMapping which maps the string values you want to colors as RGB values. The object looks something like this:

{
  "AY.4": [
    255,
    0,
    0
  ],
  "B.1.1.7": [
    0,
    0,
    255
  ]
}

We can supply that config in the URL like this:

https://cov2tree.org/?config={"colorMapping":{"AY.4":[255,0,0],"B.1.1.7":[0,0,255]}}

or make a JSON file containing

{"colorMapping":
{"AY.4":[255,0,0],"B.1.1.7":[0,0,255]}
}

Title#

We can supply a title with the title key. It will display at the top.

About overlay#

You can replace the contents of the “about” section using the overlay property, into which you will supply HTML. This can be a bit unwieldy as JSON needs to have no linebreaks in strings (you can use \n so it’s easiest to do this in usher_to_taxonium by supplying the overlay_html parameter).

Deploying your own Taxonium backend#

All of the description above involves the full tree being processed wholly locally in your own browser. For very large trees, this can mean a lot of memory and that the initial loading process is quite slow. To solve this issue, you can deploy your own Taxonium backend which will run continually ready to receive traffic and emit a small part of the tree to a client.

This is probably most easily done with our Docker containers (though it is also possible to run without these):

docker run -p 80:80 -e "DATA_URL=https://cov2tree.nyc3.cdn.digitaloceanspaces.com/latest_public.jsonl.gz" -e "CONFIG_JSON=config_public.json" theosanderson/taxonium_backend:master

or if you locally have a file at /path/to/myfile.jsonl.gz, and want to use up to 12 GB of RAM:

docker run -p 80:80 -v "/path/to/myfile.jsonl.gz:/mnt/data/myfile.jsonl.gz" -e "DATA_FILE=/mnt/data/myfile.jsonl.gz" -e "CONFIG_JSON=config_public.json" -e "MAXMEM=12000" theosanderson/taxonium_backend:master

In either case, that should start a backend on http://localhost:80

To connect to the Taxonium backend you can go to https://taxonium.org?backend=http://localhost:80. Because Taxonium is served over HTTPS, in some deployments your backend might also need to be served over HTTPS.

docker run -p 80:80 theosanderson/taxonium_frontend:master