R/cloneTrack.R

In shashidhar22/LymphoSeq2: Analyze high-throughput sequencing of T and B cell receptors

#' Clone tracking line plot
#'
#' Creates line plot tracking amino acid frequencies across multiple samples
#'
#' @param study_table A tibble of productive amino acid sequences
#' generated by LymphoSeq2 function [productiveSeq()] where the aggregate
#' parameter was set to "junction_aa"
#' @param sample_list A character vector of one or more repertoire_ids to track.
#'  If set to NULL (the default), all repertoire_ids in the sequence matrix will
#'  be tracked.
#' @param sequence_track An optional character vector of one or more amino acid
#' sequences to track. If set to NULL (the default), will pull all junction_aa
#' sequences from the sequence matrix.
#' @return Returns a line plot showing the amino acid frequencies across
#' multiple samples in the sequence matrix where each line represents one
#' unique sequence.
#' @examples
#' file_path <- system.file("extdata", "TCRB_sequencing",
#'  package = "LymphoSeq2")
#' study_table <- LymphoSeq2::readImmunoSeq(path = file_path, threads = 1)
#' study_table <- LymphoSeq2::topSeqs(study_table, top = 100)
#' amino_table <- LymphoSeq2::productiveSeq(
#'   study_table = study_table,
#'   aggregate = "junction_aa"
#' )
#' top_freq <- LymphoSeq2::topFreq(amino_table, frequency = 0.001)
#' # Track clones without mapping or tracking specific sequences
#' LymphoSeq2::cloneTrack(amino_table)
#' # Track top 20 clones mapping to the CD4 and CD8 samples
#' LymphoSeq2::cloneTrack(amino_table,
#'   sample_list = c("TRB_CD4_949", "TRB_CD8_949"),
#'   sequence_track = top_freq$junction_aa[1:20]
#' )
#' # Track the top 10 clones from top.freq
#' LymphoSeq2::cloneTrack(
#'   study_table = amino_table,
#'   sequence_track = top_freq$junction_aa[1:10]
#' )
#' # Track clones mapping to the CD4 and CD8 samples while ignoring all others
#' LymphoSeq2::cloneTrack(
#'   study_table = amino_table,
#'   sample_list = c("TRB_CD4_949", "TRB_CD8_949")
#' )
#' # Track clones mapping to the CD4 and CD8 samples and track 2 specific 
#' #sequences
#' LymphoSeq2::cloneTrack(
#'   study_table = amino_table, sample_list = c("TRB_CD4_949", "TRB_CD8_949"),
#'   sequence_track = c("CASSPPTGERDTQYF", "CASSQDRTGQYGYTF")
#' )
#'
#' @export
cloneTrack <- function(study_table, sample_list = NULL, sequence_track = NULL) {
  if (base::is.null(sample_list)) {
    sample_list <- study_table |>
      dplyr::pull(repertoire_id) |>
      base::unique()
  }
  if (is.null(sequence_track)) {
    sequence_track <- study_table |>
      dplyr::pull(junction_aa) |>
      base::unique()
  }
  study_table <- study_table |>
    dtplyr::lazy_dt()
  tracker_table <- study_table |>
    dplyr::filter(repertoire_id %in% sample_list &
                  junction_aa %in% sequence_track) |>
    dplyr::group_by(junction_aa) |>
    dplyr::mutate(seen = dplyr::n()) |>
    dplyr::ungroup() |>
    dplyr::as_tibble()
  return(tracker_table)
}