Tutorial

Authors

Filip Bielejec (filip.bielejec(sorry_spybots)rega.kuleuven.be)\ Guy Baele (guy.baele(sorry_spybots)rega.kuleuven.be)\ Bram Vrancken (bram.vrancken(sorry_spybots)rega.kuleuven.be)\ Marc Suchard (msuchard(sorry_spybots)ucla.edu)\ Andrew Rambaut (a.rambaut(sorry_spybots)ed.ac.uk)\ Philippe Lemey (philippe.lemey(sorry_spybots)rega.kuleuven.be)\

Contact

Filip Bielejec (filip.bielejec(sorry_spybots)rega.kuleuven.be)

Download

and its source code are freely available from https://github.com/phylogeography/SpreaD3. You can also clone the project with Git by running:\ $ git clone https://github.com/phylogeography/SpreaD3.\ cd into the base dir and compile by running\ $ ant jar\ This builds a executable jar-file in the directory ./dist, which can be run by double-clicking it.

Introduction

is a tool for analysing and visualising discrete and continuous trait evolutionary histories associated with phylogenies. It is designed primarily for use in conjunction with the popular Bayesian phylogenetics software BEAST [@drummond:2012zr]. However, it can also accommodate input generated by other phylogenetics inference tools (e.g. MrBayes and BEAST2 or maximum likelihood approaches) as long as the nodes and branches are annotated using the compatible syntax.

The user is offered great flexibility in and control over the visualisation process through two main innovations. First, each analysis is conceived as a two-step process. At the parsing step the inputs are analysed and converted to a JavaScript Object Notation (JSON) compliant data file. Nodes are translated to points, branches to lines and both can have associated annotations. Next, the JSON output file is used for rendering the visualisations. By separating the parsing from the rendering, the user can quickly test various image setups without the need for repeatedly parsing the same input. Note that because JSON is a language-independent data format, the output of the parsing step can be forked to utilities based on several programming languages through dedicated packages and libraries. Second, much of the versatility comes from the capability to combine several layers of visualisation in one illustration.

On the one hand this lifts the restriction of projecting phylogenies on a pre-specified canvas, and gives the user detailed control on the type of map and the displayed attributes (e.g. province borders, altitude contours, population density, …). At the same time this opens doors to mapping traits using any arbitrary coordinate system (see [sub:tips] for an example). A third advantage of the layered approach to image building is the ease with which complex stratified images can be constructed (see [sub:tips] for an example).

Alongside enhancing the flexibility in creating the visualisations, the other prime objective of is to drastically facilitate the on-line publishing of interactive visualisations. This is achieved by rendering the figures using the JavaScript Data Driven Documents (D3) libraries (see www.d3js.org and @Bostock:2011aa), to project the annotated phylogenies on a map in geoJSON data structure format (www.geojson.org).

To maintain consistency with the previous software version, and as an illustration of the branching to other renderers enabled by the versatile JSON data format as a go-between, also supports re-interpreting parsed input data in the Keyhole Markup Language (KLM) for visualisations in virtual globe software like Google Earth (www.google.com/earth/).

In this tutorial we give a detailed description of program functionalities, with an emphasis on using the Graphical User Interface (GUI), by presenting an example for the main genres of possible analyses. The data files used in the example can be found at https://rega.kuleuven.be/cev/ecv/software/\spreadname. The user is assumed to know how to run discrete and continuous trait analyses in BEAST, and how to build a Maximum Clade Credibility (MCC) tree. Good tutorials for this can be found at http://beast.bio.ed.ac.uk/tutorials.

Software requirements

needs Java Runtime environment in at least version 1.6 and a modern browser with built-in JavaScript to fully utilize its capabilities.

geoJSON maps

There are many places where ready-made geoJSON maps are available, and various ways in which tailor-made geoJSON maps can be made. We point out a few resources, but don’t even attempt to provide an exhaustive list.\ A good introduction to building geoJSON maps can be found here: http://bost.ocks.org/mike/map/. Large repositories for geoJSON maps can be found here: http://grokbase.com/t/gg/d3-js/1372gq18j9/geojson-maps and http://data.okfn.org/data/datasets/geo-boundaries-world-110m.\ There are a number of easy-to-use utilities for creating geoJSON maps starting from shapefiles. The latter can among others be found at http://www.naturalearthdata.com/downloads/ and http://www.gadm.org/. An example of a conversion utility is http://www.mapshaper.org/ or its command line version available at https://github.com/mbloch/mapshaper. Another alternative for converting shape files in geoJSON format can be found at http://ben.balter.com/2013/06/26/how-to-convert-shapefiles-to-geojson-for-use-on-github/.

A handy feature of the geoJSON format is that the latitude and longitude are treated as absolute values. Like this, the coordinates for a location (e.g. Leuven) remain valid when providing a more focused map (e.g. Belgium instead of the entire world). If no geoJSON map is provided, a bounding box based on the provided coordinates will be created automatically.

Usage examples

can process four distinct input types labelled MCC tree with DISCRETE traits ([discrete]), Log file from BSSVS analysis ([BayesFactor]), MCC tree with CONTINUOUS traits ([MCCcontinuous]), Tree distribution with CONTINUOUS traits ([contTreeDistr]). We provide an example for each of these basic analysis types, and also illustrate how more complex layered images can be constructed (e.g. [sub:tips]). We conclude this tutorial with a brief overview of how to render parsed input in KML format ([kmlRender]).

Visualizing a MCC tree annotated with discrete traits

In this example we turn to the recent Ebola virus outbreak in western Africa to show how a MCC tree summary created under a discrete diffusion model [@lemey:2009fk] can be used to visualise a pathogen’s spatiotemporal spread. Samples were collected from March to December 2014; BEAST [@drummond:2012zr] was used to co-estimate the temporal and spatial history.

Parsing the data

The GUI opens in the ‘Data’ tab. Select the option ‘MCC tree with DISCRETE traits’ (Figure [fig:parseDiscrete], nr.1), and browse to where you saved the example MCC tree to load it. will now set the working directory to the one from which the MCC tree was loaded. This means that all output generated by will be saved in this directory. To view the MCC tree in its geographic context, we have to associate each location with a particular latitude and longitude. To do this, indicate under which name the location trait is known (Figure [fig:parseDiscrete], nr.2) and associate the appropriate coordinates with each location. For this you can either use the editor supplied with (Figure [fig:parseDiscrete], nr.3) or load a previously prepared tab-delimited file including each location, its latitude and longitude ¹.

sets the most recent sampling date to the current date. In this example, the date should be set to 27/12/2014 (Figure [fig:parseDiscrete], nr.4). Leave the ‘Time scale multiplier’ (Figure [fig:parseDiscrete], nr.5) to its default value of 1 ². Next, browse to the location where the geoJSON file is stored and load it (Figure [fig:parseDiscrete], nr.6). The number of intervals equals the number of periods in which the phylogeny is partitioned (Figure [fig:parseDiscrete], nr.7). Specifically, all lineages of the tree are virtually intersected at each transition time and the the number of branches over which no trait state transition has occurred (e.g. no change in location between the branch’s parent and child node) contribute to the trait’s Markov reward counts at that time slice. The reward counts (‘Circular polygons’, cfr. infra) at slice $n$ will be plotted in the animation starting from period $n$. Save the file as ‘ebov.json’ (Figure [fig:parseDiscrete], nr.8).

[fig:parseDiscrete]

Rendering and specifying the visualisation options

The ‘Rendering’ tab in the GUI by default opens the D3 renderer. Load ‘ebov.json’ and specify the name of the folder in which the rendered output will be stored. Following the name-giving in Figure [fig:renderD3], this creates a folder ‘ebov_d3’ with several files. The most important one is ’index.html’, which can be opened by any modern internet browser by double-clicking.

The visualisation options can be set via menu’s in the left column of the window. The branches of the tree are represented by lines and the nodes by points. Each has particular properties (e.g. color, opacity, …) that can either be given a fixed value, or have values assigned by corresponding traits.

Double-clicking ‘index.html’ opens a web-page showing the tree and the sampling locations mapped in their geographical context. Let’s lay the visual focus for this example on the cross-country location transitions. Start by colouring the map by country. To concentrate on the pure geographical aspect of the picture, unselect the Polygons and Lines layer under ‘Toggle layer visibility’. Now set the ‘Map fill attribute’ to ’ISO’, which assigns a different color to Guinea, Sierra Leone and Liberia. Lower the ‘Map fill opacity’ to 0.2 to enhance the contrast with the branch colors (cfr. infra). Set the size of the ‘Point area’ to 4 and also color the sampling locations by country via the ‘Point color attribute’. Reselect the Lines layer. Setting the ‘Line color attribute’ to ‘country’ colours the lines by destination location, and attracts the eye to cross-country movements. Reselect the Polygons layer. Because the size of the polygons around a sampling location is proportional to the number of lineages that maintain that location, this captures the absolute and relative intensity of the local virus spread at any given point in time. For example, set the ‘Circular polygon color’ to the darkest red in combination with a low value for its opacity. After this, the figure should closely resemble Figure 1a in @Bielejec:2016aa (Figure [fig:ebov~f~inal]).

offers an export option to a vector graphics in a Scalable Vector Graphics (SVG) format. The easiest way to save the image to disk is by exporting (printing) the webpage in the required format (e.g. PDF/SVG) or using on-line tools like SVG crowbar (https://nytimes.github.io/svg-crowbar/). Any post-processing, if required, can then be handled by e.g. Adobe Illustrator or programs alike.

[fig:renderD3]

[fig:ebov~f~inal]

Identifying well-supported rates through Bayes factors tests

To identify well supported rates between locations in standard discrete phylogeographic reconstructions we turn to a subset of the avian influenza type A H5N1 data that was also used by @lemey:2009fk in the original paper on Bayesian phylogeographic inference in BEAST. We will identify the subset of location exchange rates that dominate the diffusion process using the Bayesian stochastic search variable selection (BSSVS) procedure [@lemey:2009fk].

In the BSSVS procedure, the standard phylogeographical model is augmented with a matrix of indicator variables $\delta_{i{\rightarrow}j}$. When the rate $q$ between locations $i$ and $j$ is non-zero, the indicator variable $\delta_{i{\rightarrow}j}$ takes the value of 1, and otherwise $\delta_{i{\rightarrow}j}$ equals 0. The indicator variables are parameters of the model, and are hence also treated as random variables associated with statistical distributions (that is, the so-called priors). In the BSSVS procedure, the prior is a truncated Poisson prior with mean $\eta = log2$, which assigns 50% prior probability on the minimal rate configuration. For a model with $K$ location states, this translates to a 50% prior probability on a model with $K-1$ non-zero rates. Because of this, the prior expectation for each exchange rate $q_{i{\rightarrow}j}$ equals

Just as for other parameters in the model, the fraction of time the Markov chain Monte Carlo (MCMC) chain spends in a state $\delta_{i{\rightarrow}j} = 0$ or $\delta_{i{\rightarrow}j} = 1$ equals its steady state probability. In other words, the frequency with which $\delta_{i{\rightarrow}j}$ is included in the model in the sample of the stationary distribution equals the odds with which transitions between locations $i$ and $j$ help explain the observed distribution of locations at the tips of the tree, or equals the odds that $q_{i{\rightarrow}j}$ is non-zero. Intuitively it should be clear that if this frequency is higher than the prior expectation, location transitions between $i$ and $j$ help explain the diffusion process. To distinguish between inclusion probabilities that are just a little higher than expected and those that indicate the concerning exchange rate really matters, we make use of Bayes factors.

Bayes factors provide a sense of how much the posterior (i.e. the outcome of the analysis) deviates from the prior beliefs, and are defined as the ratio of the posterior odds over the prior odds [@kass:1995a]. Thanks to the prior specification we can write:

which means we can directly obtain the Bayes factor support for each pairwise rate of diffusion between locations from samples collected from the posterior.

Parsing the data

To obtain the Bayes factors from a BSSVS analysis, select ‘Log file form BSSVS analysis’ in the Data tab (Figure [fig:parseBF], nr 1). Browse to the log file (H5N1_HA_discrete_rateMatrix.log) and open it to load it into (Figure [fig:parseBF], nr 2). There are two options when specifying the location coordinates (Figure [fig:parseBF], nr 3). Either a set of longitude and latitude coordinates is passed, and these are afterwards coupled to the geoJSON formatted map that can be given along (Figure [fig:parseBF], nr 4), or the locations are represented by equally spaced points on a circle³ (Figure [fig:parseBF], nr 5). To set up the latter visualisation, select ‘Generate’ and enter the number of location states (Figure [fig:parseBF], nr 6), which is 7 for this example. The locations are now referred to as location1, location2 etc. Change this to the actual location names by updating the names in the same order as the location states are declared in the XML⁴. Save as BF_circle.json. We’ll also map the BSSVS outcome on a world map, for which you’ll have to load ‘locationCoordinates_H5N1’, and the provided geoJSON map (world_countries.geojson). Save this as BF_world.json. In addition to the *.json files, creates a text file with the Bayes factors for all possible transitions between locations. For this example these are named BF_circle.json.txt and BF_world.json.txt.

Rendering and specifying the visualisation options

Open the Rendering tab and load BF_circle.json. Change the Line color attribute start color to light green (color code #b2df8a) and the end color to red (color code #e31a1c). The changes take effect after toggling between ‘posteriorProbability’ and ’bayesFactor’. The location dots can be better contrasted from the lines by setting the Point color to blue (color code #4575b4), and adjusting the Point Area to 5. By leaving the Line cut-off to its default value it is possible to visualise the Bayes factor support for all location transitions. To include the legend in the image, print the page and copy-paste the legend in the image with e.g. Illustrator. In the default plot the location names may be overlaid with the lines; this too can be easily adjusted in e.g. Illustrator. The result should look similar to Figure [fig:BFcircle].

To plot the Bayes factor support on a geographical map, again start by selecting an appropriate background color. Give China another shade of blue than its neighbouring countries by setting the Map fill attribute to `adm0_dif. For this example let’s use the same colour scheme for the lines and points as above. It is possible to lay focus on the significant location transitions by changing the Line cut-off to e.g. 4. Including the legend in the same way as above should result in a similar image as Figure [fig:BFmap].

[fig:parseBF]

[fig:BFcircle]

[fig:BFmap]

Visualising a MCC tree annotated with continuous traits

For the example using an MCC tree annotated with continuous traits we revisit the work of @Bouckaert:2012aa in which the origin and spread of Indo-European languages was investigated with well-established phylogenetic methods. We will here use the MCC tree summary to visualise their origin in and spread from Anatolia (a region in present day Turkey). This maps all branches of a continuous diffusion phylogeographic reconstruction and allows plotting the uncertainty of geographic coordinates at the internal nodes through their annotated highest posterior density contours.

Parsing the data

In the Data tab, select ‘MCC tree with CONTINUOUS traits’ and browse to where the example tree is saved (Figure [fig:parseMCCcont], nr 1). Because the latitude and longitude are by default annotated as ‘trait1’ and ‘trait2’ by BEAST, we adhere to this ordering and first provide the y-coordinate (latitude, trait1), and than the x-coordinate (longitude, trait2) (Figure [fig:parseMCCcont], nr 2). The option ‘External annotations’ is to be used when the child node trait values have an associated uncertainty (Figure [fig:parseMCCcont], nr 3). Because the locations at the tips in this example cover the areas where the language is spoken this options should be selected. On the other hand, one can safely ignore this option whenever the tips traits have no associated uncertainty (e.g. exact longitude and latitude). When the MCC tree is annotated with multiple levels of trait uncertainty (that is, multiple HPD levels), the level of interest can be chosen (Figure [fig:parseMCCcont], nr 4). The provided example tree only has 1 HPD level annotation (80%). You can leave the most recent sampling date for this example to its default value, just as the Time scale multiplier (Figure [fig:parseMCCcont], nr 5). To conclude the parsing step, select the world.geojson file and generate ‘language.json’ (Figure [fig:parseMCCcont], nr 6 and 7.

[fig:parseMCCcont]

Rendering and specifying the visualisation options

Open the Rendering tab, load language.json and save as language_D3 (Figure [fig:renderMCCcont]). As before, we start by giving the geographical map on which the tree is projected an appropriate color. Let’s keep the white color for the seas, and contrast this with grey for the land masses. For this, set the Map fill color to #000000 and the Map fill opacity to 0.2. Note that, depending on the loaded geoJSON map, this may also be achieve by selecting the appropriate Map fill attribute. Next, color the Points and Lines according to the time. For this, set the Point/Line color attribute to height (measured from the tips to the root), and the start and end color to respectively #a6cee3 and #cab2d6. Finally, let’s visualise the uncertainty on the internal nodes by setting the Polygon color attribute to ‘posterior’. By setting the start color to light orange (color code #fdbf6f) and the end color to green (color code #b2df8a), nodes with higher posterior support will be surrounded by progressively more intense green polygons. Try several values for the Polygon opacity to see how this affects the To include the legend in the image, print the web page and copy-paste the legend in the image with e.g. Illustrator.

[fig:renderMCCcont]

[fig:imageMCCcont]

Visualising a distribution of trees annotated with continuous traits

For this example we use the West Nile virus dataset previously analysed by @Pybus:2012aa. This analysis allows one to summarise and visualise the full posterior distribution of trees obtained in continuous phylogeographic analysis. To achieve this creates a time line by slicing through each phylogeny at particular points in time, and imputes the unobserved descendant locations for those ancestral infections. Uncertainty on these estimates is reflected by contouring them with polygons, which provides a natural representation of the uncertainty in these inferences.

Parsing the data

Select ‘Tree distribution with CONTINUOUS traits’ from the Data tab, load the trees, set the 2D trait to ‘location’ and load the MCC tree summary (Figure [fig:parsePosterior], nr 1, 2 and 3). The time slices are based on the MCC tree length, but it is also possible to supply a file with custom slice heights in a single column and in ascending order (from the tips to the root of the phylogeny) . For this, set ‘time slices’ to Custom (Figure [fig:customTimeSlices], nr 1) and load the time slice file (Figure [fig:customTimeSlices], nr 2). The most recent sampling tine in this dataset is 2007.63 - reset the date format to decimal (Figure [fig:parsePosterior], nr 4). The trees distribution has been subsampled with LogCombiner (a tool distributed with BEAST) to reduce its size, at which stage the burnin was removed. Hence, set the burnin to zero (Figure [fig:parsePosterior], nr 5). Leave the other options at their default values, select the provided geojson map (Figure [fig:parsePosterior], nr 6) and generate wnv_trees.json. This may take a few moments for large trees-files.

We also visualise the MCC tree which gave rise to the time slices by drawing its branches. For this, parse the West Nile virus MCC tree as before and save as wnv_mcc.json (Figure [fig:parsePosteriorMCC]). Before rendering, the time slice JSON file and the MCC tree JSON file need to be combined. Open the ‘Merge’ tab and double click in the ‘Choose file…’ box to browse to and load the JSON files (Figure [fig:mergeTimeSlice], nr 1). To add a JSON file, select the ‘+’ button in the bottom left corner of the screen (Figure [fig:mergeTimeSlice], nr 2). Keep the Points and Lines layers from wnv_cc.json, and the other layers from wnv_trees.json (Figure [fig:mergeTimeSlice], nr 3). To save the merged file as ag_combined.json, select File $\rightarrow$ Merge.

[fig:parsePosterior]

[fig:customTimeSlices]

[fig:parsePosteriorMCC]

[fig:mergeTimeSlice]

Rendering and specifying the visualisation options

There are only a few steps required to arrive at the final image for this example (Figure [fig:TimeSliceFigure]). First give the seas a grey colour by setting the Backgound color to grey. Next, colour the land mass dark grey by setting the Map color to black (colour code #000000) and the Map fill opacity to .7. Update the colour of the contours: set the Polygon color to #74add1 and the Polygon opacity to .4. Finally, color the poins and lines by the time by setting the Poins/Lines color attribute to ‘heigth’, and their start and end colours to #b2df8a and #fdbf6f respectively.

[fig:TimeSliceFigure]

Tips & tricks[sub:tips]

We illustrate the use of for data mapped to other coordinates than longitude and latitude with an antigenic coordinate ancestral reconstruction for an influenza A/H3N2 virus dataset taken from @Bedford:2014aa. Antigenic distances are a quantitative measure of how antigenically dissimilar virus strains are, and are projected on a 2D map. When no underlying map is provided, simply draws a bounding box around the data points. The idea here is to visualise three layers of uncertainty by combining the polygons of the 50%, 75% and 95% Highest Posterior Density interval.

Parsing the data

The parsing is fully analogous to the parsing explained in [MCCcontParse], with the exception that the x and y coordinates now are antigenic1 and antigenic2 respectively. Don’t forget to select ‘External annotations’ (Figure [fig:parseTipsTricks], nr 1 and 2). Save the files as ‘ag_95.json’, ‘ag_75.json’ and ‘ag_50.json’ (one output file per HPD annotation). Now combine these files (Figure [fig:mergeTipsTricks]) and save as `ag_combined.json.

[fig:parseTipsTricks]

[fig:mergeTipsTricks2]

Rendering and specifying the visualisation options

Do the following to obtain Figure [fig:mergeTipsTricks]. Set the Line color attribute to antigenic1 and its start and end colors to #1f78b4 and #fb9a99 respectively. Do the same for the Point color attribute. The HPD layers, which take 3 discrete values, can be given a separate colour by setting the Polygon attribute color to HPD. Lower the Polygon opacity to .1 to visualise the contours of the wider HPDs.

[fig:mergeTipsTricks]

Changing the start and end colors of the Polygon attribute color via the GUI has no effect because the HPD attribute is a categorical variable rather than a continous one. However, the color palettes⁵ can be changed using the Java Script command line. In FireFox, this is accessible via the Webconsole (Figure [fig:overridePalette]). For example, to select a palette of blues, set\ The changes take effect after toggling the attribute between another variable and HPD. Note that the color scheme for continuous variables and fixed values can also be manually set in this way. E.g. for continuous variables the syntax is\ and for fixed colors this becomes:\

[fig:overridePalette]

KML rendering

The previously generated JSON files can also be used to render the images in KML. As an example, open ebov.json and select ‘render as KML’. Several panels that enable the user to fine-tune the appearance of the elements used to represent all facets of the phylogeny and its associated traits appear⁶ (Figure [fig:KMLrender]). The output of this rendering can be viewed in virtual globe software (e.g. Google Earth).

[fig:KMLrender]

Command line interface[CLI]

We have found it easiest to use the command line interface with an alias added to .bash_profile:

alias spread=‘java -jar <absolute path to .jar>’

The alias will become active when you open another session in Terminal, or it can be used in the current session after executing

in the current session [assuming your bash_profile resides at $HOME].

To parse trees, the following syntax should be used:

A) discrete traits, with map:

B) discrete traits, without map:

C) Bayes factor, with map:

D) continuous trait MCC tree, without map:

E) continuous trait MCC tree, with map:

F) continuous trait posterior tree distribution, with slices according to MCC tree:

G) continuous trait posterior tree distribution, with predefined slices:

To merge JSON files, the following syntax should be used:

To render, the following syntax should be used:

Parsing and rendering options can also be set via the command line (see Table [tab:options] for an overview of the syntax and a concise description).

ll\ \ color: &\ &\ override default points color & -pointColor 0 255 255\ map point colors to a continuous attribute & -pointColor 0 255 255 -pointColorMapping attribute\ override default start-end colors & -pointStartColor 250 0 0 -pointEndColor 0 0 150\ map point colors to a discrete attribute: &\ -same color for all states &-pointColor 0 255 255 -pointColorMapping attribute\ -state-specific colors: via color sheet$\dagger$&-pointcolors traitColors.txt -pointColorMapping attribute\ &\ area: &\ &\ override default points area & -pointArea number\ map point areas to a continuous attribute & -pointAreaMapping attribute\ map point areas to a discrete attribute & -pointAreaMapping attribute\ \ color: &\ &\ adjust width & -lineWidth number\ override default lines color & -lineColor 250 0 0\ map line colors to a continuous attribute & -lineColorMapping attribute\ override default start-end colors & -lineStartColor 250 0 0 -lineEndColor 0 0 150\ map line colors to a discrete attribute: &\ -same color for all states & -lineColor 250 0 0 -lineColorMapping attribute\ -state-specific colors: via color sheet$\dagger$&-linecolors traitColors.txt -lineColorMapping attribute\

&\ width: &\ &\ override default lines width &-lineWidth number\ &\ &\ altitude (curvature): KML only? &\ &\ override default lines altitude &-lineAltitude number\ map line altitude to a continuous attribute &-lineAltitudeMapping attribute\ map line altitude to a discrete attribute &-lineAltitudeMapping attribute\ \ color: &\ &\ override default count color & -countColor 0 0 250\ \ color: &\ &\ override default area color & -areaColor 0 0 250\ map area colors to a continuous attribute & -areaColorMapping attribute\ override default start-end colors & -areaStartColor 250 0 0 -areaEndColor 0 0 150\ map area colors to a discrete attribute: &\ -same color for all states &-areaColor 0 255 255 -areaColorMapping attribute\ -state-specific colors: via color sheet$\dagger$&-areacolors traitColors.txt -areaColorMapping attribute\

$\dagger$: a file with per line only the trait state name and its color code, separated by a tab. The colors should be supplied in RGB or RGBA values.

[tab:options]