Using mycolorsTB: A Guide and Gallery

Introduction

This vignette serves as a comprehensive guide to the mycolorsTB package. It explains the available color palettes and provides a gallery of examples to demonstrate how they can be used to create distinctive and attractive visualizations for Mycobacterium tuberculosis data.

1. Viewing Available Palettes

The package includes three main palettes. You can preview any of them using the view_palette() function.

mycolors: A palette with 14 colors, named according to TB lineages (L1, A2, etc.).
classicTB: The same 14 colors, but without names, for general use.
pathogenomics: A smaller palette with 8 colors from the PathoGenOmics Lab theme.

# View the main palette with lineage names
view_palette(palette_name = "mycolors")


# View the pathogenomics palette
view_palette(palette_name = "pathogenomics")

2. Usage with ggplot2

The primary purpose of mycolorsTB is to integrate seamlessly with ggplot2. The package provides helper functions like scale_color_* and scale_fill_* to simplify this process.

library(ggplot2)
#> Warning: package 'ggplot2' was built under R version 4.3.3

# To ensure the vignette builds correctly, we define the lineage names locally.
# The functions from the package will use the actual package data.
local_mycolors <- c("A1"="#d1ae00", "A2"="#8ef5c8", "A3"="#73c2ff", "A4"="#ff9cdb",
                    "L1"="#ff3091", "L2"="#001aff", "L3"="#8a0bd2", "L4"="#ff0000",
                    "L5"="#995200", "L6"="#1eb040", "L7"="#fbff00", "L8"="#ff9d00",
                    "L9"="#37ff30", "L10"="#8fbda1")

# Example data using the local color vector
data <- data.frame(
  x = factor(names(local_mycolors), levels = names(local_mycolors)),
  y = abs(rnorm(14, mean = 10, sd = 3)),
  group = names(local_mycolors)
)

# Create a bar plot using the fill scale
ggplot(data, aes(x = x, y = y, fill = group)) +
  geom_bar(stat = "identity") +
  scale_fill_mycolors() +
  theme_minimal() +
  labs(title = "Bar Plot with scale_fill_mycolors()", x = "Lineage", y = "Value") +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))

3. Plotting Trees and Cladograms

The package includes helper functions to directly plot phylogenetic trees and cladograms from a Newick format string.

Phylogenetic Tree

The plot_tb_tree() function visualizes the tree with branch lengths representing evolutionary distance.

tree_text <- "(L8,((L1,(L7,(L4,(L2,L3)))),(L5,((A2,(A3,A4)),(A1,(L10,(L6,L9)))))));"
plot_tb_tree(tree_text)

Cladogram

The plot_tb_cladogram() function visualizes the tree topology, ignoring branch lengths. This is useful for focusing on the relationships between lineages.

plot_tb_cladogram(tree_text)

4. Generating Custom Palettes

What if you need more colors than are available in a palette? The tb_palette() function uses color interpolation to generate any number of colors you need.

# Generate 25 colors from the 'classicTB' palette
my_custom_colors <- tb_palette(25, "classicTB")
#> Warning in tb_palette(25, "classicTB"): Number of requested colors is greater
#> than the palette size. Colors are interpolated.

# Create a plot to display the interpolated colors
plot(1:25, 
     rep(1, 25),
     col = my_custom_colors, 
     pch = 19, 
     cex = 5,
     xlab = "",
     ylab = "",
     axes = FALSE,
     main = "25 Interpolated Colors from 'classicTB' Palette")