Get_Start

In this tutorial, we use the iTOL template structure and usage data to show itol.toolkit basic workflow. The tree file is generated by weighted clustering based on template parameters.

The following packages are used.

library(itol.toolkit) # main package
library(dplyr) # data manipulation
library(data.table) # file read
library(ape) # tree operation
library(stringr) # string operation
library(tidyr) # data manipulation

Data paraperation

The tree file is a built-in file in the package, which can be located by the system.file function. Users can find the file in the path and upload it to iTOL as the main tree.

The template_groups data contains the 23 templates’ name and their types. We cluster the template types based on the parameter similarity and function type.

The template_parammeters_count data contains the template usage count in public papers. We searched the data from GitHub or requests from authors.

Here is an example of 9 annotation datasets. Run the code block to get the datasets.

tree <- system.file("extdata","tree_of_itol_templates.tree",package = "itol.toolkit")
data("template_groups")
data("template_parameters_count")
hub <- create_hub(tree = tree)

## 1,7 data
df_group <- data.frame(id = unique(template_groups$group), 
                       data = unique(template_groups$group))

## 2 data
df_count <- cbind(template_groups,as.data.frame(rowSums(template_parameters_count)))

## 3 data
df_rename <- data.frame(id = template_groups$template, 
                        new_label = str_to_title(str_replace_all(template_groups$template,"_"," ")))

## 5 data
tab_tmp_01 <- as.data.frame(t(template_parameters_count))
tab_tmp_connect <- convert_01_to_connect(tab_tmp_01)
tab_tmp_connect <- full_join(tab_tmp_connect, template_groups, by=c("row" = "template"))
tab_tmp_connect <- tab_tmp_connect %>% filter(val > 10) %>% filter(row != col)

## 6 data
tab_tmp <- fread(system.file("extdata","parameter_groups.txt",package = "itol.toolkit"))
tab_id_group <- tab_tmp[,c(1,2)]
tab_tmp <- tab_tmp[,-c(1,2)]
tab_tmp_01 <- convert_01(object = tab_tmp)
tab_tmp_01 <- cbind(tab_id_group,tab_tmp_01)

order <- c("type","separator","profile","field","common themes","specific themes","data")

tab_tmp_01_long <- tab_tmp_01 %>% tidyr::gather(key = "variable",value = "value",c(-parameter,-group))

template_start_group <- tab_tmp_01_long %>% group_by(group,variable) %>% summarise(sublen = sum(value)) %>% tidyr::spread(key=variable,value=sublen)
template_start_group$group <- factor(template_start_group$group,levels = order)
template_start_group <- template_start_group %>% arrange(group)
start_group <- data.frame(Var1 = template_start_group$group, Freq = apply(template_start_group[,-1], 1, max))
start_group$start <- 0
for (i in 2:nrow(start_group)) {
  start_group$start[i] <- sum(start_group$Freq[1:(i-1)])
}
template_start_group[template_start_group == 0] <- NA
template_end_group <- template_start_group[,2:(ncol(template_start_group)-1)] + start_group$start
template_end_group <- data.frame(group = order,template_end_group)
template_end_group_long <- template_end_group %>% tidyr::gather(key = "variable",value = "value",-group)
names(template_end_group_long)[3] <- "end"
template_end_group_long$start <- rep(start_group$start,length(unique(template_end_group_long$variable)))
template_end_group_long <- template_end_group_long %>% na.omit()
template_end_group_long$length <- sum(start_group$Freq)
template_end_group_long <- template_end_group_long[,c(2,5,4,3,1)]
template_end_group_long$group <- factor(template_end_group_long$group,levels = order)

## 8 data
df_values <- fread(system.file("extdata","templates_frequence.txt",package = "itol.toolkit"))
names(df_values) <- c("id","Li,S. et al. (2022) J. Hazard. Mater.","Zheng,L. et al. (2022) Environ. Pollut.","Welter,D.K. et al. (2021) mSystems","Zhang,L et al. (2022) Nat. Commun.","Rubbens,P. et al. (2019) mSystems","Laidoudi,Y. et al. (2022) Pathogens","Wang,Y. et al. (2022) Nat. Commun.","Ceres,K.M. et al. (2022) Microb. Genomics","Youngblut,N.D. et al. (2019) Nat. Commun.","Balvín,O. et al. (2018) Sci. Rep.","Prostak,S.M. et al. (2021) Curr. Biol.","Dijkhuizen,L.W. et al. (2021) Front. Plant Sci.","Zhang,X. et al. (2022) Microbiol. Spectr.","Peris,D. et al. (2022) PLOS Genet.","Denamur,E. et al. (2022) PLOS Genet.","Dezordi,F.Z. et al. (2022) bioRxiv","Lin,Y. et al. (2021) Microbiome","Wang,Y. et al. (2022) bioRxiv","Qi,Z. et al. (2022) Food Control","Zhou,X. et al. (2022) Food Res. Int.","Zhou,X. et al. (2022) Nat. Commun.")
names(df_values) <- str_remove_all(names(df_values),"[()]")
names(df_values) <- str_replace_all(names(df_values),",","-")

## 9 data
df_value <- fread(system.file("extdata","templates_frequence.txt",package = "itol.toolkit"))
df_value <- df_value %>% tidyr::pivot_longer(-templates) %>% na.omit() %>% select(templates,value) %>% as.data.frame()
df_value$value <- log(df_value$value)

Create unit

Using default themes to create the unit object by the create_unit function. For most template types only need two columns of data. The other data can be defined by parameter or auto-identified by programming.

The data is for annotation datasets in data frame format. The key is for the output file name if all units are merged into the hub and written out by the hub object. The type is for the template name. The tree is for the main tree path or phylo object. The other parameters are used relating to the different template types.

unit_1 <- create_unit(data = df_group, 
                      key = "E1_template_types", 
                      type = "TREE_COLORS", 
                      subtype = "clade", 
                      line_type = c(rep("normal",4),"dashed"),
                      size_factor = 5, 
                      tree = tree)

unit_2 <- create_unit(data = df_count, 
                      key = "E2_parameter_number", 
                      type = "DATASET_SYMBOL",
                      position = 1, 
                      tree = tree)

unit_3 <- create_unit(data = df_rename, 
                      key = "E3_template_rename", 
                      type = "LABELS",
                      tree = tree)

unit_4 <- create_unit(data = template_groups, 
                      key = "E4_template_name_color", 
                      type = "DATASET_STYLE", 
                      subtype = "label",
                      position = "node",
                      size_factor = 1.5,
                      tree = tree)

unit_5 <- create_unit(data = tab_tmp_connect[,1:4], 
                      key = "E5_template_similarity", 
                      type = "DATASET_CONNECTION", 
                      tree = tree)

unit_6 <- create_unit(data = template_end_group_long, 
                      key = "E6_template_parameters_structure", 
                      type = "DATASET_DOMAINS", 
                      tree = tree)

unit_7 <- create_unit(data = df_group, 
                      key = "E7_template_types", 
                      type = "DATASET_COLORSTRIP", 
                      tree = tree)

unit_8 <- create_unit(data = df_values, 
                      key = "E8_usage_count_among_publications", 
                      type = "DATASET_HEATMAP", 
                      tree = tree)

unit_9 <- create_unit(data = df_value, 
                      key = "E9_log_transformed_usage_count", 
                      type = "DATASET_BOXPLOT", 
                      tree = tree)

Theme setup

In the unit and hub object, we can change the theme setup. The theme parameters in 23 templates have 114 kinds. We cluster the parameters based on their function and specification.

unit_2@specific_themes$basic_plot$size_max <- 40

unit_5@specific_themes$basic_plot$size_max <- 100

unit_8@specific_themes$heatmap$color$min <- "#ffd966"
unit_8@specific_themes$heatmap$color$max <- "#cc0000"
unit_8@specific_themes$heatmap$use_mid <- 0

unit_9@specific_themes$basic_plot$size_max <- 100

Merge

For multi levels annotation, we can merge the units in one hub. This hub object can be saved locally or output template files by the write_hub function.

hub <- hub + 
  unit_1 + 
  unit_2 + 
  unit_3 + 
  unit_4 + 
  unit_5 + 
  unit_6 + 
  unit_7 + 
  unit_8 + 
  unit_9

write_hub(hub,getwd())