Getting started with tinselR


tinselR (pronounced tinsel-er) at its' most basic level is a graphical viewer of newick phylogenetic trees and as a program for producing publication-ready figures. The power of tinselR comes with combining a genetic distance matrix for annotating a tree for epidemological outbreak analyses. A genetic distance matrix contains the number of snp differences for all pairwise comparisons. Note that the data you upload is only held within the application while launched (i.e. no data is stored.) When you are happy with the way your tree looks scroll to the bottom and press Download.

If there is a bug, feature request, or documentation needed, please file an issue


Data Upload

Please click on the 'Data Upload' tab to upload your files. Alternatively, take a look at the 'Example Data' tab to test out the application. A brief description about the example data is provided in the About the Example Data tab.


There is only one differences between the 'Example Data' and the 'Data Upload' tabs: the 'Example Data' tab has pre-loaded data, while the 'Data Upload' tab is where you, the user, can upload your own files (i.e. phylogenetic tree, genetic distance file, and metadata file). By that we mean, in the 'Example Data' tab, the user only has three options to select from - example data 1, example data 2, and example data 3 - displayed in one drop down menu. While in the 'Data Upload' tab, there are three drop down menus - 1) tree upload, 2) genetic upload, and 3) meta upload.


Both 'Example Data' and 'Data Upload' tabs provide error messages as a user either uploads all three files or selects a data set. Types of file checks that occur inform the user of the correctly selected delimiter, if the tips are concordant across all three files, or if there is a column to use the add heatmap functionality. This file checking happens independently of if the user wants the information. By that, we mean a user can ignore the file check messages if they do not need them and proceed using the application.


Beyond that the application is exactly the same between user and example data, thus this is why we highly encourage users to play with the example data first just to familiarize yourself with the application. Below we describe the three types of data files and what can be done within the application to alter your tree image after they have been uploaded.


Data files to upload


  • 1. Phylogenetic Tree - required; a newick formatted tree

  • 2. Genetic Distance Data - optional for use with the annotation function.
    A tsv/txt/csv file of SNP differences. See image below for example.


  • 3. Meta Data - optional for easy correction of tip labels and addition of a heatmap;
    a tsv/txt/csv file - requires column headers of Display.labels and Tip.labels for easy change of tip labels, while the heatmap column may be titled whatever you decide. See image below for example.


    • Ways to alter your tree image


  • Once the phylogenetic tree is uploaded you can -
    • Alter visualization parameters. See below for a tree with right aligned tip labels.

  • Once the genetic distance file is uploaded you can -
    • Add annotation to the visual representation of the tree. If you want to add annotations then highlight the tip labels to their most recent common ancestor, MRCA , and press the 'Add Annotations' button. Repeat until you are satisfied.

  • If column for heatmap included in metadata file you can -
    • add a heatmap with or without annotations

  • When you are happy with the image, you can download it as a pdf, png, or tiff.


    • Description of Example Data


    Three example datasets are included to test out the application.

    The three datasets hopefully highlight how to best use the application. Data descriptions below -

    How to test with example data

    The best way to get going with the example data is to select a dataset (e.g. examle data 1 ) and press the 'Add Tree button'. This will display the tree and allow you to start adjusting the tree visualization paramters, add annotation, and add a heatmap.

  • If you want to add annotations then highlight the tip labels to their most recent common ancestor, MRCA , and press the 'Add Annotations' button. Repeat until you are satisfied.

  • If you want to remove previously placed annotations, just press the 'Remove Annotations' button, this will step your annotations back one by one by removing the last placed annotation. For the 'Remove Annotations' there is no need for highlighting.

  • Adding a heatmap is only a possibility for example data 1 and 3 and will automatically load/unload if you press the 'Add Heatmap/ Remove Heatmap' buttons. You may need to adjust the position of the heatmap relative to the spacing of the plot.


    • Data set 1
    This data set will automatically be seen when a user presses the 'Add Tree' button. This dataset includes only one column in the metadata for the heatmap.
  • example tree 1
    • This is a newick formatted tree with 16 tip labels.
  • example gene 1
    • This is a genetic distance matrix imported from a tsv file with the same corresponding tips in the example tree 1.
  • example meta 1
    • This is a meta data file used for correcting the tip labels and plotting a heatmap and was imported from a txt file.



    Data set 2
    This data set will automatically be seen when a user presses the 'Add Tree' button. This dataset does not have metadata for adding the heatmap but does do automatic tip label correction.
  • example tree 2
    • This is a newick formatted tree with 19 tip labels
  • example gene 2
    • This is a genetic distance matrix imported from a tsv file with the same corresponding tips in the example tree 2.
  • example meta 2
    • This is a meta data file used for correcting the tip labels which contains two columns and imported from a csv file.



    Data set 3
    This data set will not automatically be seen when a user presses the 'Add Tree' button because the user needs to change the spacing on the plot; we suggest 0.09. The metadata has two columns that can be plotted with the heatmap button. One of the columns plotted has missing values (NA). If you press 'Add Heatmap' make sure to adjust the position of the heatmap to be less than the spacing on the plot. We suggest this value to be 0.02. Both of these options are located in the alter tree parameters box.
  • example tree 3
    • This is a newick formatted tree with 15 tip labels generated by RAxML.
  • example gene 3
    • This is a genetic distance matrix imported from a tsv file with the same corresponding tips in the example tree 3.
  • example meta 3
    • This is a meta data file used for correcting the tip labels, has two columns for adding two columns of heatmap, and imported from a tsv file.

    Description of Tree Parameters


    Below are defined the tree parameters that a user may adjust. Please note that these parameters are those that are found in the package ggtree or ggplot2.

  • Add spacing to plot - This will adjust the plot spacing for the tree image essentially allocating more space to the plot. Can be useful to adjust when adding annotations or heatmap.

  • Align the tips - This will allow for tip labels to either be aligned to the right of the tree or not.

  • Annotation Label Color - This will change the color of the annotation label to either 'red', 'blue', 'black', or 'grey'

  • Bootstrap Positions - This will move over the bootstrap values to the left or right of the intial position.

  • Font format - This will allow the font to be changed from 'bold', 'italic', or 'bold and italic'

  • Heatmap Color Options - This will allow the color of the heatmap to be changed, using the viridis color options. Options include 'A - magma', 'B - inferno', 'C - plasma', 'D - viridis', or 'E - cividis'.

  • Label for Annotation: Range - If nothing is adjusted here, annotations will include the word range above the displayed range of SNP differences. If nothing is in the text box then a blank will be on the tree image above the range of SNPs.

  • Label for Annotation: Median - If nothing is adjusted here, annotations will include the word median above the displayed median of SNP differences. If nothing is in the text box then a blank will be on the tree image above the median of SNPs.

  • Midpoint Root - This will either allow the tree to be midpoint rooted or not.

  • Min. Value of Bootstrap - This is the minimum value which should be displayed for bootstraps

  • Move All Annotations - This will move all annotations over. Can be useful if spacing has been adjusted for the plot.

  • Move Heatmap - Adjust the position of the heatmap, this value needs to be less than the 'Add spacing to plot' parameter for the heatmap to be seen.

  • Size of Scale Bar - This will convert the size of the scale bar that is displayed.

  • Tree Layout - This provides the user the option for the tree layout to be either 'rectangular', 'slanted', or 'circular'.
    • File check messages -
    Alter Tree Visual Parameters
    Tree Display



    Download Options
    Download Plot
    File check messages -
    Alter Tree Visual Parameters
    Tree Display



    Download Options
    Download Plot

    Frequently Asked Questions:


    Below is a list of questions you may have when using the application with your own data.

  • Cannot see tree? Please try adjusting the parameter 'Add spacing to plot'.

  • Cannot see heatmap? Please try adjusting the parameter 'Move Heatmap '.