---
title: "Clonal Analysis Utilities in APackOfTheClones"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Clonal Analysis Utilities in APackOfTheClones}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
data: 'Compiled: `r format(Sys.Date(), "%B %d, %Y")`'
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

knitr::opts_chunk$set(echo = FALSE)
options(repos = c(CRAN = "http://cran.rstudio.com"))

quiet_load_all_CRAN <- function(...) {
  for (pkg in list(...)) {
    if (require(pkg, quietly = TRUE, character.only = TRUE)) next
    invisible(install.packages(
      pkg, quiet = TRUE, verbose = FALSE, character.only = TRUE
    ))
    suppressPackageStartupMessages(invisible(
      require(pkg, quietly = TRUE, character.only = TRUE)
    ))
  }
}

# load packages
quiet_load_all_CRAN("ggplot2", "Seurat", "dplyr", "APackOfTheClones")

# load data
pbmc <- get(data("combined_pbmc"))
```

## Introduction

Here is a small collection of potentially useful functions to modify clonal expansion plots and work with clonal data that may be relevant.

## Seperately Modifying the Clone Size Legend

The `removeLegend` and `overlayLegend` functions both takes in an existing APackOfTheClones plot to either remove or change its position/aesthetics on the plot by directly modifying the ggplot object.

## Getting Clone Sizes as a List

`scRepertoire` counts and store the clone sizes in a column of the seurat object metadata. The `countCloneSizes` function returns this information in a list where each element is a table object corresponding to the clonotype frequencies for that cluster, and a cluster with no clonotypes will have an empty table at its index. Alternatively, it can also get the aggregate clone sizes. It also allows for the same filtering arguments as seen in `RunAPOTC()` and `vizAPOTC()`.

## Getting Clonotypes Common Across Seurat Clusters

The `getSharedClones` is a convenience function does this with the subsetting arguments, and returns the shared clonotypes as a named list where the names are the clonotypes and the elements are numeric vectors where each number is one of the clusters that the clonotype name at its index correspond to. A combined seurat object is loaded with the variable name `pbmc`::

```{r, shared_clones, echo = TRUE}
getSharedClones(pbmc, clonecall = "aa")
```

## Getting Geometric Centroids For Seurat Reductions

The `getReductionCentroids` function is a shortcut for getting the centroids as a list of numeric vectors of length 2 based on some existing reduction in a seurat object.

```{r, reduction_centroid, echo = TRUE}
head(getReductionCentroids(pbmc, "umap"))
```

## Highlighting Specific Clonotypes

The `scRepertoire` package has a function `scRepertoire::highlightClones` that highlights specific points in the dimensional reduction plot that correspond to user clonotype inputs and darkening everything else. `showCloneHighlight` is the APackOfTheClones equivalent that does so for each clonotype circle:

```R
showCloneHighlight(
    apotc_ggplot,
    clonotype,
    color_each = TRUE,
    default_color = "#808080",
    scale_bg = 1,
    fill_legend = TRUE
)
```

The function takes in a plot `apotc_ggplot` generated by `APOTCPlot()`/`vizAPOTC()` and modifies its underlying ggplot data to highlight/dim clones in `clonotype`. Read the function level docs for more information on how to customize the coloring of highlights with `color_each` and `default_color`.

A potentially useful application is to inspect the shared clonotypes:

```{r, highlight, echo = TRUE}
# create the APackOfTheClones plot
apotc_plot <- pbmc %>%
    vizAPOTC(clonecall = "aa", show_labels = TRUE, verbose = FALSE)

# get the shared clonotypes
shared_clonotypes <- pbmc %>%
    getSharedClones(clonecall = "aa") %>%
    names()

# highlight the first 3 shared clones
apotc_plot %>%
    showCloneHighlight(shared_clonotypes[1:3])
```