Author: Paula Ruiz-Rodriguez

# Using mycolorsTB: A Guide and Gallery

#### Paula Ruiz-Rodriguez

## 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")