feat: segmant usage

NAMESPACE

@@ -2,12 +2,14 @@
 
 export("%>%")
 export(get_study)
-export(plot_clonal_prop_per_group)
+export(plot_reads_group_abundance)
 export(plot_clonal_prop_per_sample)
+export(plot_clonal_prop_per_group)
 export(plot_clonotype_abundance)
+export(get_bottom_n_clonotypes)
+export(get_top_n_clonotypes)
 export(plot_diversity_index)
 export(plot_motif_counts)
-export(plot_reads_group_abundance)
 exportClasses(Basic)
 exportClasses(Clonality)
 exportClasses(Diversity)

R/get_study.R

@@ -1,6 +1,6 @@
-source("R/utils-basic.R")
 source("R/utils-diversity.R")
 source("R/utils-clonality.R")
+source("R/utils-basic.R")
 source("R/utils-hill.R")
 
 #' Get pyTCR data of a project
@@ -14,9 +14,8 @@ source("R/utils-hill.R")
 #'
 #' @examples
 #' \dontrun{
-#' proj <- reTCR::get_study(id="PRJNA473147", attr_col="cmv_status")
+#' proj <- reTCR::get_study(id = "PRJNA473147", attr_col = "cmv_status")
 #' }
-
 get_study <- function(id, attr_col) {
   stopifnot(is.character(id) && nchar(id) > 0)
   filename <- paste0(id, "_mixcr_metadata_file.csv")

R/plot_clonotype_abundance.R

@@ -3,7 +3,6 @@
 #' This function plots the relative abundance for all clonotypes.
 #'
 #' @param data A data frame of relative abundance for all clonotypes.
-#' @param attr_col Character. Attribute column name.
 #'
 #' @return A ggplot2 plot of relative abundance for all clonotypes.
 #' @export

R/plot_reads_group_abundance.R

@@ -3,7 +3,6 @@
 #' This function plots reads group abundance for top 100 clonotypes.
 #'
 #' @param data A data frame of relative abundance for top 100 clonotypes.
-#' @param attr_col Character. Attribute column name.
 #'
 #' @return A ggplot2 plot of reads group abundance for top 100 clonotypes.
 #' @export

R/retcr_proj_class.R

@@ -70,7 +70,7 @@ setClass("Clonality",
 
 #' Class "Motif"
 #'
-#' A class to represent motif data
+#' A class to represent motif metrics
 #'
 #' @slot aa_spectratype aa spectratype data
 #' @slot aa_max_spectratype aa max spectratype data

R/utils-segment.R

@@ -0,0 +1,52 @@
+#' Plot top n clonotypes
+#'
+#' This function plots the top n clonotypes.
+#'
+#' @param data A data frame of the main data.
+#' @param n Integer. Number of top clonotypes to select.
+#' @param attr_col Character. Attribute column name.
+#'
+#' @return A data frame of top n clonotypes.
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#' proj <- reTCR::get_study("PRJNA473147", "cmv_status")
+#' reTCR::get_top_n_clonotypes(proj@data, 10, "cmv_status")
+#' }
+get_top_n_clonotypes <- function(data, n, attr_col) {
+  stopifnot(n > 0)
+  top <- data %>%
+    dplyr::arrange(sample, freq) %>%
+    dplyr::group_by(sample) %>%
+    dplyr::slice_tail(n = n) %>%
+    dplyr::select(freq, cdr3aa, sample, !!rlang::sym(attr_col))
+  return(top)
+}
+
+
+#' Plot bottom n clonotypes
+#'
+#' This function plots the top n clonotypes.
+#'
+#' @param data A data frame of the main data.
+#' @param n Integer. Number of top clonotypes to select.
+#' @param attr_col Character. Attribute column name.
+#'
+#' @return A data frame of bottom n clonotypes.
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#' proj <- reTCR::get_study("PRJNA473147", "cmv_status")
+#' reTCR::get_bottom_n_clonotypes(proj@data, 10, "cmv_status")
+#' }
+get_bottom_n_clonotypes <- function(data, n, attr_col) {
+  stopifnot(n > 0)
+  bottom <- data %>%
+    dplyr::arrange(sample, freq) %>%
+    dplyr::group_by(sample) %>%
+    dplyr::slice_head(n = n) %>%
+    dplyr::select(freq, cdr3aa, sample, !!rlang::sym(attr_col))
+  return(bottom)
+}

README.md

@@ -156,7 +156,17 @@ reTCR::plot_reads_group_abundance(proj@clonality@abundance_top)
 reTCR::plot_reads_group_abundance(proj@clonality@abundance_rare)
 ```
 
-## 4. Hill numbers
+## 4. Segment usage metrics
+
+```r
+# Top n highest clonotypes
+reTCR::get_top_n_clonotypes(proj@data, 15, "cmv_status")
+
+# Bottom n lowest clonotypes
+reTCR::get_bottom_n_clonotypes(proj@data, 20, "cmv_status")
+```
+
+## 5. Hill numbers
 
 ```r
 # get hill numbers