Itol.toolkit

<img src="man/figures/itol.toolkit.gif" width="160" alt="itol.toolkit package logo and demonstration"/>

The itol.toolkit is an R package that provides helper functions for the Interactive Tree Of Life (iTOL). This package has been selected as a third-party tool in iTOL documentation and is recommended as one of the Top 40 New CRAN packages in January 2023 by the R Views channel of RStudio.

First version published in Bioinformatics journal, Please cite:

Zhou, T., Xu, K., Zhao, F., Liu, W., Li, L., Hua, Z., & Zhou, X. (2023). itol. toolkit accelerates working with iTOL (Interactive Tree of Life) by an automated generation of annotation files. Bioinformatics, 39(6), btad339. https://doi.org/10.1093/bioinformatics/btad339

Features

• Support all 114 themes among all 23 template types in iTOL v6

• High throughput generate templates in one command

• Learn published template themes and use theme

• Save all-in-one reproducible data locally

Installation

Based on the dependence packages from CRAN and Bioconductor source. We recommend to use pak to install itol.toolkit package automatically to avoid problems.

install.packages("pak")

# from CRAN
pak::pak('itol.toolkit')

# from GitHub
pak::pak('TongZhou2017/itol.toolkit')

If you prefer not to use the pak method, you can still use the traditional installation method.<details><summary>[Click to view] Traditional method</summary> To install the stable versions, you can use the CRAN official repository. For development versions, you can use the GitHub repository. However, if you need to install packages from Bioconductor, you'll need to use the BiocManager package.

# install Biostrings
# install.packages("BiocManager")
BiocManager::install("Biostrings")

# from CRAN
install.packages("itol.toolkit")

# from GitHub
# install.packages("devtools") # if you have not installed "devtools" package
devtools::install_github("TongZhou2017/itol.toolkit")

Please note that in order to use this software, you will need to manually install the required dependencies from Bioconductor. A complete list of the necessary packages and installation instructions can be found in the supplementary materials.</details>

If you encounter any issues during the installation process, such as problems caused by other systems, R versions, or dependency packages, please refer to the supplementary materials for a solution.

Quickstart

# load package
library(itol.toolkit)

# read data
tree <- system.file("extdata",
                    "tree_of_itol_templates.tree",
                    package = "itol.toolkit")
data("template_groups")
df_group <- data.frame(id = unique(template_groups$group), 
                       data = unique(template_groups$group))

# create hub
hub <- create_hub(tree = tree)

## create unit
unit <- create_unit(data = df_group, 
                    key = "Quickstart", 
                    type = "DATASET_COLORSTRIP", 
                    tree = tree)

## add unit into hub
hub <- hub + unit

## write template file
write_hub(hub,getwd())

Documents

We have documents for every single function and some important tips for users.

Single functions

• COLLAPSE: collapse branches by range id or node id.

• PRUNE: drop out branches.

• SPACING: adjust branch spacing.

• TREE_COLORS: set branch style at range, clade, branch, label, and background level.

• DATASET_STYLE: set branch style at branch and label level.

• LABELS: change node name.

• DATASET_TEXT: add text by HTML.

• DATASET_COLORSTRIP: add color strip with text.

• DATASET_BINARY: multi columns with one shape symbol.

• DATASET_GRADIENT: one column heatmap.

• DATASET_HEATMAP: heatmap with field tree.

• DATASET_SYMBOL: internal tree one column with multi shape symbol.

• DATASET_EXTERNALSHAPE: outside multi column with multi shape symbol.

• DATASET_DOMAINS: strucutre with multi shape symbol.

• DATASET_SIMPLEBAR: bar plot.

• DATASET_MULTIBAR: multi bar plot.

• DATASET_BOXPLOT: box plot.

• DATASET_LINECHART: line plot.

• DATASET_PIECHART: pie plot.

• DATASET_ALIGNMENT: sequence alignment.

• DATASET_CONNECTIONS: network between braches.

• DATASET_IMAGE: add image.

• POPUP_INFO: interactive external information.

Tips

• Overview: overview for all functions.

• Installation: FAQ about installation.

• Datasets: overview of 5 example datasets for demo.

• Colors: buildin color palette.

• Data reproduction: learn data from template files.

• VS table2itol: compare with the other iTOL helper tool, table2itol.

• Tree construction: create a tree by different data and methods.

Video

Gallery

We collected reproducible plots into a gallery page.

News

update history:

Version 1.2.2

• Added: DATASET_BINARY now supports third element color palette specification in dual-factor coloring.
• Added: Flexible separator syntax for attribute-based dual-factor coloring - support any string as separator (single/multi-character, special regex characters).
• Added: DATASET_BINARY now features flexible data conversion with a standalone convert_to_binary() function for precise control over binary data transformation.
• Added: Interactive RStudio Addin binary_data_conversion provides an intuitive graphical interface for binary data conversion with real-time preview and range controls.
• Added: DATASET_EXTERNALSHAPE now supports dual-factor coloring (main group + gradient) with customizable color palettes.
• Fixed: DATASET_PIECHART now supports single-column data input with intelligent range detection and automatic pie segment generation.

Version 1.2.1

• Added: DATASET_COLORSTRIP supports dual-factor coloring (main group + gradient) with customizable color palettes.
• Added: DATASET_STYLE supports dual-factor coloring (main group + gradient) for both branch and label subtypes.
• Added: DATASET_STYLE background colors support dual-factor coloring with smart contrast adjustment when background_color matches color parameter.
• Added: Enhanced darken_color() function with "enhanced" method for better color darkening while preserving hue and saturation.
• Added: The third element of color parameter can specify a color palette set for base hues in both DATASET_COLORSTRIP and DATASET_STYLE.
• Added: Support for background-only dual-factor coloring in DATASET_STYLE when color is single value and background_color is dual-factor.

Version 1.2.0

• Added: TREE_COLORS supports dual-factor coloring (main group + gradient).
• Added: The 3rd element of color can specify a color set for base hues.
• Fixed: Legend is now rebuilt from the final DATA right before output, ensuring LEGEND order matches the DATA block and paving the way for unified legend handling in future refactors.
• Fixed: write_unit() now reports output file paths for user confirmation.
• Fixed: TREE_COLORS label subtype accepts font_type = "normal" (and vectorization works). Previously, providi