@@ -3,3 +3,5 @@

 extdata/.*\.json$

 ^data-raw$

 extdata/refdata-cellranger-vdj-GRCh38-alts-ensembl-2.0.0/

+^doc$

+^Meta$

@@ -6,3 +6,5 @@

 data-raw/*.csv

 data-raw/*.json

 inst/doc

+doc

+Meta

@@ -1,7 +1,7 @@

 Package: CellaRepertorium

 Type: Package

 Title: Methods for clustering and analyzing high-throughput single cell immune cell repertoires (RepSeq)

-Version: 0.2.3

+Version: 0.2.4

 Author: Andrew McDavid

 Maintainer: Andrew McDavid <Andrew_McDavid@urmc.rochester.edu>

 Description: Methods to cluster and analyze high-throughput single cell immune cell repertoires,

@@ -23,7 +23,8 @@ Imports:

    rlang,

    purrr,

    Matrix,

-   S4Vectors

+   S4Vectors,

+   tidyr

 Suggests: 

     testthat,

     readr,

@@ -31,7 +32,7 @@ Suggests:

     rmarkdown,

     ggplot2,

     BiocStyle,

-    tidyr

+    ggdendro

 RoxygenNote: 6.1.1

 LinkingTo: Rcpp

 NeedsCompilation: yes

@@ -8,24 +8,34 @@ export(cdhit)

 export(cdhit_ccdb)

 export(cluster_permute_test)

 export(entropy)

+export(enumerate_pairing)

 export(fancy_name_contigs)

-export(fine_cluster)

+export(fine_cluster_seqs)

+export(fine_clustering)

 export(get_canonical_representative)

+export(ig_chain_recode)

 export(modal_category)

 export(np)

 export(pairing_tables)

+export(tcr_chain_recode)

+exportMethods("cluster_tbls<-")

+exportMethods(cluster_tbls)

 import(Biostrings)

 importFrom(S4Vectors,List)

 importFrom(S4Vectors,SimpleList)

 importFrom(dplyr,"%>%")

 importFrom(dplyr,anti_join)

 importFrom(dplyr,bind_rows)

+importFrom(dplyr,case_when)

 importFrom(dplyr,group_by)

 importFrom(dplyr,left_join)

 importFrom(dplyr,mutate)

 importFrom(dplyr,summarize)

 importFrom(dplyr,ungroup)

+importFrom(methods,"slot<-")

 importFrom(methods,as)

+importFrom(methods,new)

+importFrom(methods,slot)

 importFrom(rlang,":=")

 importFrom(rlang,sym)

 importFrom(rlang,syms)

@@ -40,5 +50,6 @@ importFrom(stringr,str_replace_all)

 importFrom(tibble,as_data_frame)

 importFrom(tibble,as_tibble)

 importFrom(tibble,data_frame)

+importFrom(tibble,tibble)

 importFrom(utils,data)

 useDynLib(CellaRepertorium)

@@ -1,7 +1,12 @@

+setGeneric('cluster_tbls', function(x, ...) standardGeneric('cluster_tbls'))

+setGeneric('cluster_tbls<-', function(x, ..., value) standardGeneric('cluster_tbls<-'),  signature=c("x", "value"))

+

+

 get_cluster_tbls = function(x, index){

     if(missing(index)) x@cluster_tbls else x@cluster_tbls[[index]]

 }

-setGeneric('cluster_tbls', function(x, ...) standardGeneric('cluster_tbls'))

+

+#' @export

 setMethod('cluster_tbls', signature = c(x = 'ContigCellDB'), get_cluster_tbls)

 set_cluster_tbls = function(x, index, value){

@@ -9,6 +14,6 @@ set_cluster_tbls = function(x, index, value){

     x

 }

-setGeneric('cluster_tbls<-', function(x, ..., value) standardGeneric('cluster_tbls<-'),  signature=c("x", "value"))

+#' @export

 setReplaceMethod('cluster_tbls', signature = c(x = 'ContigCellDB'), set_cluster_tbls)

@@ -46,26 +46,24 @@ cluster_germline = function(ccdb, segment_keys = c('v_gene', 'j_gene', 'chain'),

 #' Perform additional clustering of sequences within groups

 #'

-#' @param clustering `Clustering`

-#' @param sequence_key 

+#' @param clustering `Clustering` object

+#' @param sequence_key `character` naming column in `contig_tbl` with sequence

 #' @param type 'AA' or 'DNA'

-#' @param max_affinity 

-#' @param keep_clustering_details 

-#' @param ... passed to `clustering``

+#' @param max_affinity `numeric` naming the maximal affinity for the sparse affinity matrix that is constructed.  Not currently used.

+#' @param keep_clustering_details `logical` -- should output of `fine_cluster_seqs` be kept as a list column

+#' @param ... passed to `fine_cluster_seqs`

 #'

-#' @return

+#' @return `Clustering` object with updated `contig_tbl` and `cluster_tbl`

 #' @export

-#'

-#' @examples

 fine_clustering = function(clustering, sequence_key = 'seq', type = clustering$type, max_affinity = NULL, keep_clustering_details = FALSE, ...){

     cctb = clustering$contig_tbl

     message('Calculating intradistances on ', nrow(clustering$cluster_tbl), ' clusters.')

-    # run `fine_cluster` within each cluster_pk

-    cluster_tbl = cctb %>% group_by(!!!syms(clustering$cluster_pk)) %>% summarize(fc = list(fine_cluster(!!sym(sequence_key), type = type, ...)), n_cluster = n())

+    # run `fine_cluster_seqs` within each cluster_pk

+    cluster_tbl = cctb %>% group_by(!!!syms(clustering$cluster_pk)) %>% summarize(fc = list(fine_cluster_seqs(!!sym(sequence_key), type = type, ...)), n_cluster = n())

     message('Summarizing')

-    contig_by_cluster = cctb[union(clustering$contig_pk, clustering$cluster_pk)] %>% nest(!!!syms(clustering$contig_pk)) %>% 

+    contig_by_cluster = cctb[union(clustering$contig_pk, clustering$cluster_pk)] %>% nest(!!!syms(clustering$contig_pk)) %>%

         right_join(cluster_tbl %>% select(!!!syms(clustering$cluster_pk)), by=clustering$cluster_pk) # need to make sure these are in the same order!

-    

+

     if(is.null(max_affinity)){

         max_max = max(purrr::map_dbl(cluster_tbl$fc, 'max_dist'))

     } else {

@@ -100,15 +98,15 @@ fine_clustering = function(clustering, sequence_key = 'seq', type = clustering$t

 #' @param cluster_method character passed to `hclust`

 #'

 #' @seealso hclust, stringDist

-#' @return dendrogram of class `hclust`

+#' @return `list` containing

 #' @export

 #' @import Biostrings

 #' @examples

 #' fasta_path = system.file('extdata', 'demo.fasta', package='CellaRepertorium')

 #' aaseq = Biostrings::readAAStringSet(fasta_path)[1:100]

-#' cls = fine_cluster(aaseq)

+#' cls = fine_cluster_seqs(aaseq)

 #' plot(cls$cluster)

-fine_cluster = function(seqs, type = 'AA', big_memory_brute = FALSE, method = 'levenshtein', substitution_matrix = 'BLOSUM100', cluster_fun = 'hclust', cluster_method = 'complete'){

+fine_cluster_seqs = function(seqs, type = 'AA', big_memory_brute = FALSE, method = 'levenshtein', substitution_matrix = 'BLOSUM100', cluster_fun = 'hclust', cluster_method = 'complete'){

     if(length(seqs) > 4000 & !big_memory_brute) stop("Won't try to cluster ", length(seqs), " sequences unless `big_memory_brute` = TRUE.  (Make sure you actually have lots of memory!)")

     type = match.arg(type, choices = c('AA', 'DNA'))

     cluster_fun = match.arg(cluster_fun, c('hclust', 'none'))

@@ -1,9 +1,17 @@

 #' Filtered and annotated contigs of TCR from mice

 #'

 #' The details of how these are generated are shown in the vignette mouse_tcell_qc

-#' and are serialied to serve as an examples for other vignettes and documentation.

+#' and are serialized to serve as an examples for other vignettes and documentation.

 #' @format A data frame of 3399 contigs and 22 fields,

 #'  all except 4 are originally defined in https://support.10xgenomics.com/single-cell-vdj/software/pipelines/latest/output/annotation#contig

 #'  The following fields were defined ex post facto. anno_file: Path to original csv file, pop: Mouse strain. sample: An artificial "replicate" from the original data defined by subsampling with replacement, celltype:The putative cell type of the contig.

 #'

 "contigs_qc"

+

+#' A preconstructed `ContigClusterDB` from the `contigs_qc` data

+#'

+#' Used in various examples.

+#' @format

+#' \code{ccdb_ex = ContigCellDB_10XVDJ(contigs_qc, contig_pk = c('pop',   'sample', 'barcode', 'contig_id'), cell_pk = c('pop',   'sample', 'barcode'))}

+#'

+"ccdb_ex"

@@ -207,7 +207,10 @@ plot_pairing = function(pairing_list, color_labels_by){

 }

-

+#' @export

+#' @describeIn enumerate_pairing Recode a table with IG chains

+#' @importFrom dplyr case_when

+#' @importFrom tibble tibble

 ig_chain_recode = function(tbl){

     pairing = case_when(tbl$IGH>0 & (tbl$IGK>0 | tbl$IGL>0) ~ 'paired',

                         tbl$IGH>0 ~ 'heavy',

@@ -220,13 +223,16 @@ ig_chain_recode = function(tbl){

     dplyr::bind_cols(tbl, tibble(pairing, canonical))

 }

+#' @export

+#' @describeIn enumerate_pairing Recode a table with TCR chains

+#' @param tbl output from enumerate_pairing containing TRA/TRB or IGH/IHK/IHL columns

 tcr_chain_recode = function(tbl){

     pairing = case_when(tbl$TRA>0 & tbl$TRB>0 ~ 'paired',

                         tbl$TRB>0 ~ 'beta',

                         tbl$TRA>0 ~ 'alpha')

     canonical = case_when(tbl$TRB==2 ~ 'double-beta',

                           tbl$TRA==2  ~ 'double-alpha',

-                          (tbl$TRB + tbl$TRA) > 1 ~ 'other',

+                          (tbl$TRB + tbl$TRA) > 2 ~ 'other',

                           TRUE ~ 'classical')

     dplyr::bind_cols(tbl, tibble(pairing, canonical))

 }

@@ -238,7 +244,7 @@ tcr_chain_recode = function(tbl){

 #' Return a tibble, keyed by cells that includes the counts of the chains, the `raw_chain_type` and any additional output from running `chain_recode_fun`.

 #' @param ccdb `ContigCellDB`

 #' @param chain_key `character` naming the field in the `contig_tbl` identifying chain

-#' @param chain_recode_fun a function that operates on the output of this function that further reduces the chain combinations to some other summary.  Set to 'guess' to apply functions that may work for 10X data or `NULL` to skip.  See `CellaRepertorium:::tcr_chain_recode` for an example.

+#' @param chain_recode_fun a function that operates on the output of this function that further reduces the chain combinations to some other summary.  Set to 'guess' to apply functions that may work for 10X data or `NULL` to skip.  See `CellaRepertorium::tcr_chain_recode` for an example.

 #'

 #' @return a `tibble` keyed by cells.

 #' @export

@@ -261,7 +267,7 @@ enumerate_pairing = function(ccdb, chain_key = 'chain', chain_recode_fun = NULL)

     if(!is.function(chain_recode_fun)) stop("`chain_recode_fun` must be a function, NULL, or 'guess'")

     chain_keys = union(chain_key, ccdb$cell_pk)

-    chain_count = ccdb$contig_tbl %>% group_by(!!!syms(chain_keys)) %>% summarize(n_chains = n()) %>% spread(chain_key, 'n_chains', fill = 0)

+    chain_count = ccdb$contig_tbl %>% group_by(!!!syms(chain_keys)) %>% summarize(n_chains = n()) %>% tidyr::spread(chain_key, 'n_chains', fill = 0)

     chain_type = ccdb$contig_tbl %>% group_by(!!!syms(ccdb$cell_pk)) %>% summarize(raw_chain_type = paste(sort(!!sym(chain_key)), collapse = '_'))

     chain_summary = left_join(chain_type, chain_count, by = ccdb$cell_pk) %>% ungroup()

     chain_recode_fun(chain_summary)

@@ -69,9 +69,9 @@ jsn_ss %>% rowwise() %>% do({

     tibble()

 })

-knitr::purl('vignettes/mouse_tcell_qc.Rmd', output = 'data-raw/mouse_tcells.R')

-source('data-raw/mouse_tcell_qc.R')

+knitr::purl('vignettes/mouse_tcell_qc.Rmd', output = 'data-raw/mouse_tcells_qc.R')

+source('data-raw/mouse_tcells_qc.R')

 ccdb_ex = ContigCellDB_10XVDJ(contigs_qc, contig_pk = c('pop',   'sample', 'barcode', 'contig_id'), cell_pk = c('pop',   'sample', 'barcode'))

-use_data(contigs_qc)

-use_data(ccdb_ex)

+use_data(contigs_qc, overwrite = TRUE)

+use_data(ccdb_ex, overwrite = TRUE)

 unlink('data-raw/mouse_tcell_qc.R')

new file mode 100644

Binary files /dev/null and b/data/ccdb_ex.rda differ

Binary files a/data/contigs_qc.rda and b/data/contigs_qc.rda differ

new file mode 100644

@@ -0,0 +1,14 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/data.R

+\docType{data}

+\name{ccdb_ex}

+\alias{ccdb_ex}

+\title{A preconstructed `ContigClusterDB` from the `contigs_qc` data}

+\format{\code{ccdb_ex = ContigCellDB_10XVDJ(contigs_qc, contig_pk = c('pop',   'sample', 'barcode', 'contig_id'), cell_pk = c('pop',   'sample', 'barcode'))}}

+\usage{

+ccdb_ex

+}

+\description{

+Used in various examples.

+}

+\keyword{datasets}

@@ -9,7 +9,7 @@ cdhit(seqs, identity = NULL, kmerSize = NULL, min_length = 6,

   s = 1, name = "CD-Hit", only_index = FALSE,

   showProgress = interactive(), ...)

-cdhit_ccdb(object, sequence_col, type = c("DNA", "AA"),

+cdhit_ccdb(object, sequence_key, type = c("DNA", "AA"),

   cluster_tbl_name = length(cluster_tbls(object)) + 1, ...)

 }

 \arguments{

@@ -32,7 +32,9 @@ You may need to lower it below 5 for AAseq with identity less than .7.}

 \item{...}{other arguments that can be passed to cdhit, see https://github.com/weizhongli/cdhit/wiki/3.-User's-Guide#CDHIT for details.  These will override any default values.}

-\item{sequence_col}{`character` naming the column in the `contig_tbl` containing the sequence to be clustered}

+\item{object}{An object of class `ClusterContigDB`}

+

+\item{sequence_key}{`character` naming the column in the `contig_tbl` containing the sequence to be clustered}

 \item{type}{one of 'DNA' or 'AA'}

@@ -12,6 +12,6 @@ contigs_qc

 }

 \description{

 The details of how these are generated are shown in the vignette mouse_tcell_qc

-and are serialied to serve as an examples for other vignettes and documentation.

+and are serialized to serve as an examples for other vignettes and documentation.

 }

 \keyword{datasets}

@@ -1,5 +1,5 @@

 % Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/fine-cluster.R

+% Please edit documentation in R/clustering-methods.R

 \name{entropy}

 \alias{entropy}

 \alias{np}

new file mode 100644

@@ -0,0 +1,43 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/pairing-methods.R

+\name{ig_chain_recode}

+\alias{ig_chain_recode}

+\alias{tcr_chain_recode}

+\alias{enumerate_pairing}

+\title{Categorize the pairing present in a cell}

+\usage{

+ig_chain_recode(tbl)

+

+tcr_chain_recode(tbl)

+

+enumerate_pairing(ccdb, chain_key = "chain", chain_recode_fun = NULL)

+}

+\arguments{

+\item{tbl}{output from enumerate_pairing containing TRA/TRB or IGH/IHK/IHL columns}

+

+\item{ccdb}{`ContigCellDB`}

+

+\item{chain_key}{`character` naming the field in the `contig_tbl` identifying chain}

+

+\item{chain_recode_fun}{a function that operates on the output of this function that further reduces the chain combinations to some other summary.  Set to 'guess' to apply functions that may work for 10X data or `NULL` to skip.  See `CellaRepertorium::tcr_chain_recode` for an example.}

+}

+\value{

+a `tibble` keyed by cells.

+}

+\description{

+For each cell (defined by `ccdb$cell_pk`) count the number of each level of `chain_key` occurs, and cross tabulate.

+Also for each cell, paste together all values `chain_key`.

+Return a tibble, keyed by cells that includes the counts of the chains, the `raw_chain_type` and any additional output from running `chain_recode_fun`.

+}

+\section{Functions}{

+\itemize{

+\item \code{ig_chain_recode}: Recode a table with IG chains

+

+\item \code{tcr_chain_recode}: Recode a table with TCR chains

+}}

+

+\examples{

+data(ccdb_ex)

+enumerate_pairing(ccdb_ex)

+enumerate_pairing(ccdb_ex, chain_recode_fun = 'guess')

+}

similarity index 86%

rename from man/fine_cluster.Rd

rename to man/fine_cluster_seqs.Rd

@@ -1,10 +1,10 @@

 % Generated by roxygen2: do not edit by hand

-% Please edit documentation in R/fine-cluster.R

-\name{fine_cluster}

-\alias{fine_cluster}

+% Please edit documentation in R/clustering-methods.R

+\name{fine_cluster_seqs}

+\alias{fine_cluster_seqs}

 \title{Calculate distances and perform hierarchical clustering on a set of sequences}

 \usage{

-fine_cluster(seqs, type = "AA", big_memory_brute = FALSE,

+fine_cluster_seqs(seqs, type = "AA", big_memory_brute = FALSE,

   method = "levenshtein", substitution_matrix = "BLOSUM100",

   cluster_fun = "hclust", cluster_method = "complete")

 }

@@ -24,7 +24,7 @@ fine_cluster(seqs, type = "AA", big_memory_brute = FALSE,

 \item{cluster_method}{character passed to `hclust`}

 }

 \value{

-dendrogram of class `hclust`

+`list` containing

 }

 \description{

 The distances between AA sequences is defined to be 1-score/max(score) times the median length of the input sequences.

@@ -33,7 +33,7 @@ The distances between nucleotide sequences is defined to be edit_distance/max(ed

 \examples{

 fasta_path = system.file('extdata', 'demo.fasta', package='CellaRepertorium')

 aaseq = Biostrings::readAAStringSet(fasta_path)[1:100]

-cls = fine_cluster(aaseq)

+cls = fine_cluster_seqs(aaseq)

 plot(cls$cluster)

 }

 \seealso{

new file mode 100644

@@ -0,0 +1,29 @@

+% Generated by roxygen2: do not edit by hand

+% Please edit documentation in R/clustering-methods.R

+\name{fine_clustering}

+\alias{fine_clustering}

+\title{Perform additional clustering of sequences within groups}

+\usage{

+fine_clustering(clustering, sequence_key = "seq",

+  type = clustering$type, max_affinity = NULL,

+  keep_clustering_details = FALSE, ...)

+}

+\arguments{

+\item{clustering}{`Clustering` object}

+

+\item{sequence_key}{`character` naming column in `contig_tbl` with sequence}

+

+\item{type}{'AA' or 'DNA'}

+

+\item{max_affinity}{`numeric` naming the maximal affinity for the sparse affinity matrix that is constructed.  Not currently used.}

+

+\item{keep_clustering_details}{`logical` -- should output of `fine_cluster_seqs` be kept as a list column}

+

+\item{...}{passed to `fine_cluster_seqs`}

+}

+\value{

+`Clustering` object with updated `contig_tbl` and `cluster_tbl`

+}

+\description{

+Perform additional clustering of sequences within groups

+}