@@ -5,3 +5,4 @@ extdata/.*\.json$

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

 ^doc$

 ^Meta$

+manuscript/

@@ -8,3 +8,4 @@ data-raw/*.json

 inst/doc

 doc

 Meta

+*.dll

@@ -1,31 +1,41 @@

-Package: CellaRepertorium

 Type: Package

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

-Version: 0.3.0

-Author: Andrew McDavid

+Package: CellaRepertorium

+Title: Methods for clustering and analyzing high-throughput

+    single cell immune cell repertoires (RepSeq)

+Version: 0.3.1

+Authors@R: 

+    c(person(given = "Andrew",

+             family = "McDavid",

+             role = c('aut', 'cre'),

+             email = "Andrew_McDavid@urmc.rochester.edu"),

+      person(given = "Yu",

+             family = "Gu",

+             role = "aut",

+             email = "Yu_Gu@urmc.rochester.edu"))

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

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

-    especially from the 10X Genomics VDJ solution. 

-    Contains an R interface to CD-HIT (Li and Godzik 2006).

-    Tests for specific expansion, as well as omnibus oligoclonality under hypergeometric models.

+Description: Methods to cluster and analyze high-throughput

+    single cell immune cell repertoires, especially from the 10X Genomics

+    VDJ solution. Contains an R interface to CD-HIT (Li and Godzik 2006).   

+    Methods to visualize and analyze paired heavy-light chain data.

+    Tests for specific expansion, as well as omnibus oligoclonality under

+    hypergeometric models.

 License: GPL-3

-Encoding: UTF-8

-LazyData: true

-Depends: R (>= 3.5.0)

+Depends: 

+    R (>= 3.5.0)

 Imports:

-   dplyr,

-   tibble,

-   stringr,

-   Biostrings,

-   Rcpp,

-   reshape2,

-   methods,

-   rlang,

-   purrr,

-   Matrix,

-   S4Vectors,

-   tidyr,

-   forcats

+    dplyr,

+    tibble,

+    stringr,

+    Biostrings,

+    Rcpp,

+    reshape2,

+    methods,

+    rlang,

+    purrr,

+    Matrix,

+    S4Vectors,

+    tidyr,

+    forcats

 Suggests: 

     testthat,

     readr,

@@ -33,8 +43,15 @@ Suggests:

     rmarkdown,

     ggplot2,

     BiocStyle,

-    ggdendro

-RoxygenNote: 6.1.1

-LinkingTo: Rcpp

+    ggdendro,

+    broom,

+    lme4,

+    RColorBrewer

+LinkingTo: 

+    Rcpp

+VignetteBuilder: 

+    knitr

+Encoding: UTF-8

+LazyData: true

 NeedsCompilation: yes

-VignetteBuilder: knitr

+RoxygenNote: 6.1.1

@@ -4,6 +4,7 @@ export(ContigCellDB)

 export(ContigCellDB_10XVDJ)

 export(canonicalize_by_chain)

 export(canonicalize_by_prevalence)

+export(canonicalize_by_subset)

 export(cdhit)

 export(cdhit_ccdb)

 export(cluster_permute_test)

@@ -12,7 +13,6 @@ export(enumerate_pairing)

 export(fancy_name_contigs)

 export(fine_cluster_seqs)

 export(fine_clustering)

-export(get_canonical_representative)

 export(ig_chain_recode)

 export(modal_category)

 export(np)

@@ -28,14 +28,17 @@ importFrom(dplyr,anti_join)

 importFrom(dplyr,bind_cols)

 importFrom(dplyr,bind_rows)

 importFrom(dplyr,case_when)

+importFrom(dplyr,do)

 importFrom(dplyr,filter)

 importFrom(dplyr,group_by)

 importFrom(dplyr,left_join)

 importFrom(dplyr,mutate)

 importFrom(dplyr,right_join)

+importFrom(dplyr,rowwise)

 importFrom(dplyr,select)

 importFrom(dplyr,semi_join)

 importFrom(dplyr,summarize)

+importFrom(dplyr,transmute)

 importFrom(dplyr,ungroup)

 importFrom(methods,"slot<-")

 importFrom(methods,as)

@@ -28,7 +28,7 @@ valid_KeyedTbl = function(tbl, keys){

 #' @param cell_tbl a data frame of cell barcodes, and (optional) additional fields describing their properties

 #' @param cell_pk character vector naming fields in `cell_tbl` that uniquely identify a cell barcode

 #' @param cluster_tbl A data frame that provide cluster assignments for each contig

-#' @param cluster_pk If `cluster_tbl` was provided, a list of character vector naming fields in `cluster_tbl` that uniquely identify a cluster

+#' @param cluster_pk If `cluster_tbl` was provided, a character vector naming fields in `cluster_tbl` that uniquely identify a cluster

 #'

 #' @return \code{ContigCellDB}

 #' @export

@@ -39,7 +39,8 @@ valid_KeyedTbl = function(tbl, keys){

 #'

 #' @examples

 #' data(contigs_qc)

-#' ContigCellDB(contigs_qc, contig_pk = c('barcode', 'pop', 'sample', 'contig_id'), cell_pk = c('barcode', 'pop', 'sample'))

+#' ContigCellDB(contigs_qc, contig_pk = c('barcode', 'pop', 'sample', 'contig_id'),

+#'  cell_pk = c('barcode', 'pop', 'sample'))

 ContigCellDB = function(contig_tbl, contig_pk, cell_tbl, cell_pk, cluster_tbl, cluster_pk = character()){

     valid_KeyedTbl(contig_tbl, contig_pk)

     equalized = FALSE

@@ -68,12 +69,14 @@ ContigCellDB_10XVDJ = function(contig_tbl, contig_pk = c('barcode', 'contig_id')

 #' Creat a method for ContigCellDB object to access its slots

 #'

 #' @param x A ContigCellDB object

-#' @param name Name of a slot for a ContigCellDB object

+#' @param name a slot of a ContigCellDB object (one of  `c('contig_tbl', 'cell_tbl', 'contig_pk', 'cell_pk', 'cluster_tbl', 'cluster_pk')`)

 #'

 #' @return Slots of ContigCellDB

 #' @export

 #'

 #' @examples

+#' ccdb_ex$contig_tbl

+#' ccdb_ex$cell_tbl

 #' ccdb_ex$cluster_tbl

 setMethod("$", signature = c(x = 'ContigCellDB'), function(x, name){

     if(name %in% c('contig_tbl', 'cell_tbl', 'contig_pk', 'cell_pk', 'cluster_tbl', 'cluster_pk')){

@@ -83,17 +86,21 @@ setMethod("$", signature = c(x = 'ContigCellDB'), function(x, name){

     }

 })

-#' Creat a function of ContigCellDB object to replace values of its slots

+#' Create a function of ContigCellDB object to replace values of its slots

 #'

 #' @param x A ContigCellDB object

-#' @param name Name of a slot for a ContigCellDB object

+#' @param name Name of a slot for a ContigCellDB object (one of  `c('contig_tbl', 'cell_tbl', 'contig_pk', 'cell_pk', 'cluster_tbl', 'cluster_pk')`)

 #' @param value The value assigned to a slot of ContigCellDB object

 #'

 #' @return A ContigCellDB object

 #' @export

 #'

 #' @examples

-#' ccdb_ex$contig_pk <- c("pop","barcode","contig_id")

+#' ccdb_ex$contig_pk = c("sample","barcode","contig_id") # 'pop' is technically redundant with 'sample'

+#' # Take a subset of ccdb_ex

+#' ccdb_ex

+#' ccdb_ex$contig_tbl = dplyr::filter(ccdb_ex$contig_tbl, pop == 'b6')

+#' ccdb_ex

 setReplaceMethod("$", signature = c(x = 'ContigCellDB'), function(x, name, value){

     if(name %in% c('contig_tbl', 'cell_tbl', 'contig_pk', 'cell_pk', 'cluster_tbl', 'cluster_pk')){

         slot(x, name) <- value

@@ -82,8 +82,14 @@ cdhit = function(seqs, identity = NULL, kmerSize = NULL, min_length = 6, s = 1,

 ##' @param object An object of class `ClusterContigDB`

 ##' @param sequence_key `character` naming the column in the `contig_tbl` containing the sequence to be clustered

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

-##' @param cluster_name What index should the clustering be stored in?  By default, a new, unnamed cluster is added.

+##' @param cluster_name `character` specifying key, and name for the clustering.

 ##' @export

+##' @examples

+##' res = CellaRepertorium:::cdhit_ccdb(ccdb_ex, 'cdr3_nt', type = 'DNA',

+##' cluster_name = 'DNA97', identity = .965, min_length = 12, G = 1)

+##' res$cluster_tbl

+##' res$contig_tbl

+##' res$cluster_pk

 cdhit_ccdb = function(object, sequence_key, type = c('DNA', 'AA'), cluster_name = 'cluster_idx', ...){

     seqs = object$contig_tbl[[sequence_key]]

     if(length(seqs) < 1) stop("No sequences were provided")

@@ -7,6 +7,7 @@ cluster_germline = function(ccdb, segment_keys = c('v_gene', 'j_gene', 'chain'),

     replace_cluster_tbl(ccdb, cluster_tbl, cl_con_tbl, cluster_pk = cluster_name)

 }

+globalVariables(c('fc', 'd(medoid)', 'is_medoid', 'n_cluster'))

 # Also canonicalize..

 #' Perform additional clustering of sequences within groups

@@ -146,8 +147,8 @@ fine_cluster_seqs = function(seqs, type = 'AA', big_memory_brute = FALSE, method

     }

     medoid = which.min(colMeans(sd))

-    homology = sd[medoid,]

-    list(cluster = hc, distance = sd, homology = homology, medoid = medoid, max_dist = max(sd))

+    distance = sd[medoid,]

+    list(cluster = hc, distance_mat = sd, distance = distance, medoid = medoid, max_dist = max(sd))

 }

@@ -1,3 +1,4 @@

+globalVariables(c('prev'))

 #' For each cell, return a single, canonical chain-cluster

 #'

 #' In single cell data, multiple chains (heavy-light or alpha-beta) are expected.  In some cases, there could be more than two (eg multiple alpha alleles for T cells).

@@ -19,7 +20,7 @@ canonicalize_by_prevalence = function(tbl, cell_identifiers = 'barcode', cluster

-

+# I believe this function is obsoleted by `canonicalize_by_subset``

 #' @param sort_factors `character` vector naming columns in `tbl` to sorted on, within  `cell_identifier`. Sorted by first element first, then ties broken by subsequent elements.  Sorted in decreasing order for each element.

 #' @param chain_levels an optional `character` vector providing the sort order of the `chain` column in `tbl`.  Set to length zero to disable.

 #' @export

@@ -35,12 +36,40 @@ canonicalize_by_chain = function(tbl,  cell_identifiers = 'barcode', sort_factor

 }

-canonicalize_by_subset = function(ccdb, tie_break_keys = c('umis', 'reads'), contig_fields = tie_break_keys, ...){

+#' Return single contig for each cell based on filtering and sorting

+#'

+#' @param ccdb `ContigCellDB`

+#' @param ... unquoted expressions passed to `dplyr::filter` that will be applied to the `contig_tbl`

+#' @param tie_break_keys columns used to sort the `contig_tbl` in **decreasing** order

+#' @param order `integer` specifying which entry (ordinal) will be selected from the sorted contig_tbl, within each cell

+#' @param contig_fields columns in the `contig_tbl` that will be copied over to the `cell_tbl`

+#'

+#' @return `ContigCellDB` with additional fields in `cell_tbl`

+#' @export

+#'

+#' @examples

+#' # Report beta chain with highest umi-count, breaking ties with reads

+#' beta = canonicalize_by_subset(ccdb_ex, chain == 'TRB',

+#' tie_break_keys = c('umis', 'reads'),

+#' contig_fields = c('umis', 'reads', 'chain', 'v_gene', 'd_gene', 'j_gene'))

+#' head(beta$cell_tbl)

+#' # Only adds fields to `cell_tbl`

+#' stopifnot(all.equal(beta$cell_tbl[ccdb_ex$cell_pk],

+#' ccdb_ex$cell_tbl[ccdb_ex$cell_pk]))

+#' #Report cdr3 with highest UMI count, but only when > 5 UMIs support it

+#' umi5 = canonicalize_by_subset(ccdb_ex, umis > 5,

+#' tie_break_keys = c('umis', 'reads'), contig_fields = c('umis', 'cdr3'))

+#' stopifnot(all(umi5$cell_tbl$umis > 5, na.rm = TRUE))

+canonicalize_by_subset = function(ccdb, ...,  tie_break_keys = c('umis', 'reads'), contig_fields = tie_break_keys, order = 1){

     tbl = ccdb$contig_tbl

-    ft = filter(tbl, quos(...))

+    # Filter with expressions in ...

+    ft = filter(.data = tbl, !!!rlang::quos(...))

+    # setup quosures to arrange the data

     arranging = purrr::map(tie_break_keys, ~ rlang::quo(desc(!!sym(.x))))

-    ft2 = ft %>% group_by(!!!syms(ccdb$cell_pk)) %>% dplyr::arrange(!!!arranging)

+    # take first row of each cell

+    ft2 = ft %>% group_by(!!!syms(ccdb$cell_pk)) %>% dplyr::arrange(!!!arranging) %>% dplyr::do(dplyr::slice(., order))

     cell_tbl = ccdb$cell_tbl

+    # join with cell tbl (so same number of cells)

     ccdb$cell_tbl = right_join_warn(ft2[unique(c(contig_fields, ccdb$cell_pk))], cell_tbl, by = ccdb$cell_pk)

     ccdb

 }

@@ -52,6 +81,7 @@ canonicalize_by_subset = function(ccdb, tie_break_keys = c('umis', 'reads'), con

 #' Given a family of similar sequences, return a "representative"

 #'

+#' This function can be deprecated.

 #' @param seqs character vector

 #' @param medoid_idx optional index into seqs

 #' @param warn_if_distinct Should a warning be emitted if there are distinct elements in seqs?

@@ -60,10 +90,9 @@ canonicalize_by_subset = function(ccdb, tie_break_keys = c('umis', 'reads'), con

 #' sequence is returned

 #'

 #' @return character vector

-#' @export

 #'

 #' @examples

-#' get_canonical_representative(c('apple', 'manzana', 'pomme'))

+#' CellaRepertorium:::get_canonical_representative(c('apple', 'manzana', 'pomme'))

 get_canonical_representative = function(seqs, medoid_idx, warn_if_distinct = FALSE){

     if(!missing(medoid_idx)){

         if(!is.integer(medoid_idx) || medoid_idx < 1 || medoid_idx > length(seqs)) stop("Illegal `medoid_idx`")

@@ -79,6 +108,7 @@ get_canonical_representative = function(seqs, medoid_idx, warn_if_distinct = FAL

     return(rep)

 }

+# This should return a ccdb or a subclass?

 #' Generate a list of tables representing clusters paired in cells

 #'

 #' A contingency table of every combination of `cluster_idx` up to `table_order` is generated.

@@ -115,31 +145,37 @@ get_canonical_representative = function(seqs, medoid_idx, warn_if_distinct = FAL

 #' @importFrom rlang sym syms :=

 #' @examples

 #' library(dplyr)

-#' cluster_tbl = data_frame(clust_idx = gl(3, 2), cell_idx = rep(1:3, times = 2))

+#' tbl = tibble(clust_idx = gl(3, 2), cell_idx = rep(1:3, times = 2), contig_idx = 1:6)

+#' ccdb = ContigCellDB(tbl, contig_pk = c('cell_idx', 'contig_idx'),

+#' cell_pk = 'cell_idx', cluster_pk = 'clust_idx')

 #' # no pairs found twice

-#' pt1 = pairing_tables(cluster_tbl, 'cell_idx', 'clust_idx', canonicalize_by_prevalence)

+#' pt1 = pairing_tables(ccdb, canonicalize_by_prevalence)

 #' # all pairs found, found once.

-#' pt2 = pairing_tables(cluster_tbl, 'cell_idx', 'clust_idx',

-#'     canonicalize_by_prevalence, min_expansion = 1)

+#' pt2 = pairing_tables(ccdb, canonicalize_by_prevalence, min_expansion = 1)

 #' pt2$cell_tbl

-#' cluster_tbl2 = bind_rows(cluster_tbl, cluster_tbl %>% mutate(cell_idx = rep(4:6, times = 2)))

+#' tbl2 = bind_rows(tbl, tbl %>% mutate(cell_idx = rep(4:6, times = 2)))

+#' ccdb2 = ContigCellDB(tbl2, contig_pk = c('cell_idx', 'contig_idx'), cell_pk = 'cell_idx',

+#' cluster_pk = 'clust_idx')

 #' #all pairs found twice

-#' pt3 = pairing_tables(cluster_tbl2, 'cell_idx', 'clust_idx', canonicalize_by_prevalence, min_expansion = 1)

+#' pt3 = pairing_tables(ccdb2, canonicalize_by_prevalence, min_expansion = 1)

 #' pt3$cell_tbl

 #' # `canonicalize_by_chain` expects fields `umis`, `reads`

 #' # to break ties,  wrap the function to change this

-#' cluster_tbl3 = cluster_tbl2 %>%

+#' ccdb2$contig_tbl = ccdb2$contig_tbl %>%

 #'     mutate(umis = 1, reads = 1, chain = rep(c('TRA', 'TRB'), times = 6))

-#' pt4 = pairing_tables(cluster_tbl3, 'cell_idx', 'clust_idx',

-#'     canonicalize_by_chain, min_expansion = 1, table_order = 2)

-pairing_tables = function(cluster_tbl, cell_identifiers = 'barcode', cluster_idx = 'cluster_idx', canonicalize_fun = canonicalize_by_chain, table_order = 2, min_expansion = 2,  orphan_level = 1, cluster_whitelist = NULL, cluster_blacklist = NULL, cell_tbl = NULL, feature_tbl = NULL ){

+#' pt4 = pairing_tables(ccdb2, canonicalize_by_chain, min_expansion = 1, table_order = 2)

+pairing_tables = function(ccdb,  canonicalize_fun = canonicalize_by_chain, table_order = 2, min_expansion = 2,  orphan_level = 1, cluster_keys = character(), cluster_whitelist = NULL, cluster_blacklist = NULL){

     if(orphan_level > table_order) stop('`ophan_level` must be less than or equal to `table_order`')

     if(table_order < 1) stop('Table order must be at least 1')

     # get `table_order` most common clusters for each cell

     # forcibly rename cluster_idx -> "cluster_idx"

-    bar_chain_tbls = purrr::map(seq_len(table_order), function(i) canonicalize_fun(cluster_tbl, cell_identifiers = cell_identifiers, cluster_idx = cluster_idx, order = i) %>% dplyr::select(!!!c(syms(cell_identifiers), rlang::quo(cluster_idx))) %>% dplyr::rename( !!paste0('cluster_idx.', i) := !!cluster_idx))

+    contig_tbl = ccdb$contig_tbl

+    cell_identifiers = ccdb$cell_pk

+    cluster_idx = ccdb$cluster_pk

+    cell_tbl = ccdb$cell_tbl

+    bar_chain_tbls = purrr::map(seq_len(table_order), function(i) canonicalize_fun(contig_tbl, cell_identifiers = cell_identifiers, cluster_idx = cluster_idx, order = i) %>% dplyr::select(!!!c(syms(cell_identifiers), rlang::quo(cluster_idx))) %>% dplyr::rename( !!paste0('cluster_idx.', i) := !!cluster_idx))

     # for each cell, what clusters are present

     oligo_cluster_pairs = purrr::reduce(bar_chain_tbls, left_join, by = cell_identifiers)

@@ -52,7 +52,7 @@ get_gaps = function(ca){

     data_frame(vd_gap, dj_gap, vj_gap)

 }

-read_contig_json = function(file, seq_cols = c('quals', 'aa_sequence', '')){

+read_contig_json = function(anno_file, seq_cols = c('quals', 'aa_sequence', '')){

     jsn = fromJSON(file(anno_file), flatten = TRUE)

     # contig sequences and gaps

 }

@@ -22,7 +22,7 @@ ContigCellDB_10XVDJ(contig_tbl, contig_pk = c("barcode", "contig_id"),

 \item{cluster_tbl}{A data frame that provide cluster assignments for each contig}

-\item{cluster_pk}{If `cluster_tbl` was provided, a list of character vector naming fields in `cluster_tbl` that uniquely identify a cluster}

+\item{cluster_pk}{If `cluster_tbl` was provided, a character vector naming fields in `cluster_tbl` that uniquely identify a cluster}

 }

 \value{

 \code{ContigCellDB}

@@ -37,5 +37,6 @@ Construct a ContigCellDB

 \examples{

 data(contigs_qc)

-ContigCellDB(contigs_qc, contig_pk = c('barcode', 'pop', 'sample', 'contig_id'), cell_pk = c('barcode', 'pop', 'sample'))

+ContigCellDB(contigs_qc, contig_pk = c('barcode', 'pop', 'sample', 'contig_id'),

+ cell_pk = c('barcode', 'pop', 'sample'))

 }

new file mode 100644

@@ -0,0 +1,40 @@

+% Generated by roxygen2: do not edit by hand

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

+\name{canonicalize_by_subset}

+\alias{canonicalize_by_subset}

+\title{Return single contig for each cell based on filtering and sorting}

+\usage{

+canonicalize_by_subset(ccdb, ..., tie_break_keys = c("umis", "reads"),

+  contig_fields = tie_break_keys, order = 1)

+}

+\arguments{

+\item{ccdb}{`ContigCellDB`}

+

+\item{...}{unquoted expressions passed to `dplyr::filter` that will be applied to the `contig_tbl`}

+

+\item{tie_break_keys}{columns used to sort the `contig_tbl` in **decreasing** order}

+

+\item{contig_fields}{columns in the `contig_tbl` that will be copied over to the `cell_tbl`}

+

+\item{order}{`integer` specifying which entry (ordinal) will be selected from the sorted contig_tbl, within each cell}

+}

+\value{

+`ContigCellDB` with additional fields in `cell_tbl`

+}

+\description{

+Return single contig for each cell based on filtering and sorting

+}

+\examples{

+# Report beta chain with highest umi-count, breaking ties with reads

+beta = canonicalize_by_subset(ccdb_ex, chain == 'TRB',

+tie_break_keys = c('umis', 'reads'),

+contig_fields = c('umis', 'reads', 'chain', 'v_gene', 'd_gene', 'j_gene'))

+head(beta$cell_tbl)

+# Only adds fields to `cell_tbl`

+stopifnot(all.equal(beta$cell_tbl[ccdb_ex$cell_pk],

+ccdb_ex$cell_tbl[ccdb_ex$cell_pk]))

+#Report cdr3 with highest UMI count, but only when > 5 UMIs support it

+umi5 = canonicalize_by_subset(ccdb_ex, umis > 5,

+tie_break_keys = c('umis', 'reads'), contig_fields = c('umis', 'cdr3'))

+stopifnot(all(umi5$cell_tbl$umis > 5, na.rm = TRUE))

+}

@@ -10,7 +10,7 @@

 \arguments{

 \item{x}{A ContigCellDB object}

-\item{name}{Name of a slot for a ContigCellDB object}

+\item{name}{a slot of a ContigCellDB object (one of  `c('contig_tbl', 'cell_tbl', 'contig_pk', 'cell_pk', 'cluster_tbl', 'cluster_pk')`)}

 }

 \value{

 Slots of ContigCellDB

@@ -19,5 +19,7 @@ Slots of ContigCellDB

 Creat a method for ContigCellDB object to access its slots

 }

 \examples{

+ccdb_ex$contig_tbl

+ccdb_ex$cell_tbl

 ccdb_ex$cluster_tbl

 }

@@ -3,14 +3,14 @@

 \docType{methods}

 \name{$<-,ContigCellDB-method}

 \alias{$<-,ContigCellDB-method}

-\title{Creat a function of ContigCellDB object to replace values of its slots}

+\title{Create a function of ContigCellDB object to replace values of its slots}

 \usage{

 \S4method{$}{ContigCellDB}(x, name) <- value

 }

 \arguments{

 \item{x}{A ContigCellDB object}

-\item{name}{Name of a slot for a ContigCellDB object}

+\item{name}{Name of a slot for a ContigCellDB object (one of  `c('contig_tbl', 'cell_tbl', 'contig_pk', 'cell_pk', 'cluster_tbl', 'cluster_pk')`)}

 \item{value}{The value assigned to a slot of ContigCellDB object}

 }

@@ -18,8 +18,12 @@

 A ContigCellDB object

 }

 \description{

-Creat a function of ContigCellDB object to replace values of its slots

+Create a function of ContigCellDB object to replace values of its slots

 }

 \examples{

-ccdb_ex$contig_pk <- c("pop","barcode","contig_id")

+ccdb_ex$contig_pk = c("sample","barcode","contig_id") # 'pop' is technically redundant with 'sample'

+# Take a subset of ccdb_ex

+ccdb_ex

+ccdb_ex$contig_tbl = dplyr::filter(ccdb_ex$contig_tbl, pop == 'b6')

+ccdb_ex

 }

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

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

-\item{cluster_name}{What index should the clustering be stored in?  By default, a new, unnamed cluster is added.}

+\item{cluster_name}{`character` specifying key, and name for the clustering.}

 }

 \value{

 vector of \code{integer} of length \code{seqs} providing the cluster ID for each sequence, or a `tibble`.  See details.

@@ -73,4 +73,9 @@ cdhit(aaseq,identity = 1, G = 0, aL = 1, aS = 1,  only_index = TRUE)[1:10]

 cdhit(aaseq,identity = 1, G = 0, aL = .9, aS = .9,  only_index = TRUE)[1:10]

 # a tibble

 tbl = cdhit(aaseq, identity = 1, G = 0, aL = .9, aS = .9, only_index = FALSE)

+res = CellaRepertorium:::cdhit_ccdb(ccdb_ex, 'cdr3_nt', type = 'DNA',

+cluster_name = 'DNA97', identity = .965, min_length = 12, G = 1)

+res$cluster_tbl

+res$contig_tbl

+res$cluster_pk

 }

@@ -27,6 +27,10 @@ fine_clustering(ccdb, sequence_key, type, max_affinity = NULL,

 Perform additional clustering of sequences within groups

 }

 \examples{

-ccdb_ex = CellaRepertorium:::cdhit_ccdb(ccdb_ex, 'cdr3_nt', type = 'DNA', cluster_name = 'DNA97', identity = .965, min_length = 12, G = 1)

-ccdb_ex = fine_clustering(ccdb_ex, sequence_key = 'cdr3_nt', type = 'DNA') 

+ccdb_ex_small = ccdb_ex

+ccdb_ex_small$cell_tbl = ccdb_ex_small$cell_tbl[1:200,]

+ccdb_ex_small = CellaRepertorium:::cdhit_ccdb(ccdb_ex_small,

+sequence_key = 'cdr3_nt', type = 'DNA', cluster_name = 'DNA97',

+identity = .965, min_length = 12, G = 1)

+ccdb_ex_small = fine_clustering(ccdb_ex_small, sequence_key = 'cdr3_nt', type = 'DNA')

 }

@@ -20,8 +20,8 @@ sequence is returned}

 character vector

 }

 \description{

-Given a family of similar sequences, return a "representative"

+This function can be deprecated.

 }

 \examples{

-get_canonical_representative(c('apple', 'manzana', 'pomme'))

+CellaRepertorium:::get_canonical_representative(c('apple', 'manzana', 'pomme'))

 }

@@ -4,20 +4,15 @@

 \alias{pairing_tables}

 \title{Generate a list of tables representing clusters paired in cells}

 \usage{

-pairing_tables(cluster_tbl, cell_identifiers = "barcode",

-  cluster_idx = "cluster_idx",

-  canonicalize_fun = canonicalize_by_chain, table_order = 2,

-  min_expansion = 2, orphan_level = 1, cluster_whitelist = NULL,

-  cluster_blacklist = NULL, cell_tbl = NULL, feature_tbl = NULL)

+pairing_tables(ccdb, canonicalize_fun = canonicalize_by_chain,

+  table_order = 2, min_expansion = 2, orphan_level = 1,

+  cluster_keys = character(), cluster_whitelist = NULL,

+  cluster_blacklist = NULL)

 }

 \arguments{

-\item{cluster_tbl}{a table with all combinations of clusters in all cells}

+\item{ccdb}{`ContigCellDB`}

-\item{cell_identifiers}{character vector naming fields that key a cell}

-

-\item{cluster_idx}{character naming a single field IDing the clusters}

-

-\item{canonicalize_fun}{a function with signature `canonicalize_fun(cluster_tbl, cell_identifiers, cluster_idx, order = i)` that for each `cell_identifier` returns a single contig that depends on the `order`.  For instance \link{canonicalize_by_prevalence} or \link{canonicalize_by_chain}.}

+\item{canonicalize_fun}{a function with signature `canonicalize_fun(ContigCellDB, order = i)` that for each cell, returns a single contig that depends on the `order`.  For instance \link{canonicalize_by_prevalence} or \link{canonicalize_by_chain}.}

 \item{table_order}{Integer larger than 1. What order of cluster_idx will be paired, eg, order = 2 means that the most common and second most common cluster_idx will be sought for each cell}

@@ -25,13 +20,11 @@ pairing_tables(cluster_tbl, cell_identifiers = "barcode",

 \item{orphan_level}{Integer larger than 0 and less than or equal to `table_order`.  Given that at least `min_expansion` cells are found that have `table_order` chains identical, how many `cluster_idx` pairs will we match on to select other cells.  Example: `ophan_level=1` means that cells that share just a single chain with the}

-\item{cluster_whitelist}{a table of "cluster_idx" that should always be reported.  In contrast to the `cluster_tbl`, here the clusters must be named "cluster_idx.1", "cluster_idx.2" (if order-2 pairs are being selected).}

-

-\item{cluster_blacklist}{a table of "cluster_idx" that will never be reported.  Must be named as per `cluster_whitelist`.}

+\item{cluster_keys}{optional `character` naming additional columns in `ccdb$cluster_tbl` to be reported in the pairing}

-\item{cell_tbl}{optional, ancillary table with additional cell features.  Must also be keyed by `cell_identifiers`}

+\item{cluster_whitelist}{a table of pairings or clusters that should always be reported.  Here the clusters must be named "cluster_idx.1", "cluster_idx.2" (if order-2 pairs are being selected) rather than with `ccdb$cluster_pk``}

-\item{feature_tbl}{optional, ancillary table with additional cluster features.  Must also be keyed by `cluster_idx`}

+\item{cluster_blacklist}{a table of pairings or clusters that will never be reported.  Must be named as per `cluster_whitelist`.}

 }

 \value{

 list of tables.  The `cell_tbl` is keyed by the `cell_identifiers`, with fields "cluster_idx.1", "cluster_idx.2", etc, IDing the contigs present in each cell. "cluster_idx.1_fct" and "cluster_idx.2_fct" cast these fields to factors and are reordered to maximize the number of pairs along the diagonal. The `idx1_tbl` and `idx2_tbl` report information (passed in about the `cluster_idx` by `feature_tbl`.)  The `cluster_pair_tbl` reports all pairings found of contigs, and the number of times observed.

@@ -54,23 +47,25 @@ This facilitates plotting.

 \examples{

 library(dplyr)

-cluster_tbl = data_frame(clust_idx = gl(3, 2), cell_idx = rep(1:3, times = 2))

+tbl = tibble(clust_idx = gl(3, 2), cell_idx = rep(1:3, times = 2), contig_idx = 1:6)

+ccdb = ContigCellDB(tbl, contig_pk = c('cell_idx', 'contig_idx'),

+cell_pk = 'cell_idx', cluster_pk = 'clust_idx')

 # no pairs found twice

-pt1 = pairing_tables(cluster_tbl, 'cell_idx', 'clust_idx', canonicalize_by_prevalence)

+pt1 = pairing_tables(ccdb, canonicalize_by_prevalence)

 # all pairs found, found once.

-pt2 = pairing_tables(cluster_tbl, 'cell_idx', 'clust_idx',

-    canonicalize_by_prevalence, min_expansion = 1)

+pt2 = pairing_tables(ccdb, canonicalize_by_prevalence, min_expansion = 1)

 pt2$cell_tbl

-cluster_tbl2 = bind_rows(cluster_tbl, cluster_tbl \%>\% mutate(cell_idx = rep(4:6, times = 2)))

+tbl2 = bind_rows(tbl, tbl \%>\% mutate(cell_idx = rep(4:6, times = 2)))

+ccdb2 = ContigCellDB(tbl2, contig_pk = c('cell_idx', 'contig_idx'), cell_pk = 'cell_idx',

+cluster_pk = 'clust_idx')

 #all pairs found twice

-pt3 = pairing_tables(cluster_tbl2, 'cell_idx', 'clust_idx', canonicalize_by_prevalence, min_expansion = 1)

+pt3 = pairing_tables(ccdb2, canonicalize_by_prevalence, min_expansion = 1)

 pt3$cell_tbl

 # `canonicalize_by_chain` expects fields `umis`, `reads`

 # to break ties,  wrap the function to change this

-cluster_tbl3 = cluster_tbl2 \%>\%

+ccdb2$contig_tbl = ccdb2$contig_tbl \%>\%

     mutate(umis = 1, reads = 1, chain = rep(c('TRA', 'TRB'), times = 6))

-pt4 = pairing_tables(cluster_tbl3, 'cell_idx', 'clust_idx',

-    canonicalize_by_chain, min_expansion = 1, table_order = 2)

+pt4 = pairing_tables(ccdb2, canonicalize_by_chain, min_expansion = 1, table_order = 2)

 }

 \seealso{

 canonicalize_by_prevalence, canonicalize_by_chain

deleted file mode 100644

Binary files a/src/CellaRepertorium.dll and /dev/null differ

new file mode 100644

@@ -0,0 +1,339 @@

+                    GNU GENERAL PUBLIC LICENSE

+                       Version 2, June 1991

+

+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,

+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

+ Everyone is permitted to copy and distribute verbatim copies

+ of this license document, but changing it is not allowed.

+

+                            Preamble

+

+  The licenses for most software are designed to take away your

+freedom to share and change it.  By contrast, the GNU General Public

+License is intended to guarantee your freedom to share and change free

+software--to make sure the software is free for all its users.  This

+General Public License applies to most of the Free Software

+Foundation's software and to any other program whose authors commit to

+using it.  (Some other Free Software Foundation software is covered by

+the GNU Lesser General Public License instead.)  You can apply it to

+your programs, too.

+

+  When we speak of free software, we are referring to freedom, not

+price.  Our General Public Licenses are designed to make sure that you

+have the freedom to distribute copies of free software (and charge for

+this service if you wish), that you receive source code or can get it

+if you want it, that you can change the software or use pieces of it

+in new free programs; and that you know you can do these things.

+

+  To protect your rights, we need to make restrictions that forbid

+anyone to deny you these rights or to ask you to surrender the rights.

+These restrictions translate to certain responsibilities for you if you

+distribute copies of the software, or if you modify it.

+

+  For example, if you distribute copies of such a program, whether

+gratis or for a fee, you must give the recipients all the rights that

+you have.  You must make sure that they, too, receive or can get the

+source code.  And you must show them these terms so they know their

+rights.

+

+  We protect your rights with two steps: (1) copyright the software, and

+(2) offer you this license which gives you legal permission to copy,

+distribute and/or modify the software.

+

+  Also, for each author's protection and ours, we want to make certain

+that everyone understands that there is no warranty for this free

+software.  If the software is modified by someone else and passed on, we

+want its recipients to know that what they have is not the original, so

+that any problems introduced by others will not reflect on the original

+authors' reputations.

+

+  Finally, any free program is threatened constantly by software

+patents.  We wish to avoid the danger that redistributors of a free

+program will individually obtain patent licenses, in effect making the

+program proprietary.  To prevent this, we have made it clear that any

+patent must be licensed for everyone's free use or not licensed at all.

+

+  The precise terms and conditions for copying, distribution and

+modification follow.

+

+                    GNU GENERAL PUBLIC LICENSE

+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

+

+  0. This License applies to any program or other work which contains

+a notice placed by the copyright holder saying it may be distributed

+under the terms of this General Public License.  The "Program", below,

+refers to any such program or work, and a "work based on the Program"

+means either the Program or any derivative work under copyright law:

+that is to say, a work containing the Program or a portion of it,

+either verbatim or with modifications and/or translated into another

+language.  (Hereinafter, translation is included without limitation in

+the term "modification".)  Each licensee is addressed as "you".

+

+Activities other than copying, distribution and modification are not

+covered by this License; they are outside its scope.  The act of

+running the Program is not restricted, and the output from the Program

+is covered only if its contents constitute a work based on the

+Program (independent of having been made by running the Program).

+Whether that is true depends on what the Program does.

+

+  1. You may copy and distribute verbatim copies of the Program's

+source code as you receive it, in any medium, provided that you

+conspicuously and appropriately publish on each copy an appropriate

+copyright notice and disclaimer of warranty; keep intact all the

+notices that refer to this License and to the absence of any warranty;

+and give any other recipients of the Program a copy of this License

+along with the Program.

+

+You may charge a fee for the physical act of transferring a copy, and

+you may at your option offer warranty protection in exchange for a fee.

+

+  2. You may modify your copy or copies of the Program or any portion

+of it, thus forming a work based on the Program, and copy and

+distribute such modifications or work under the terms of Section 1

+above, provided that you also meet all of these conditions:

+

+    a) You must cause the modified files to carry prominent notices

+    stating that you changed the files and the date of any change.

+

+    b) You must cause any work that you distribute or publish, that in

+    whole or in part contains or is derived from the Program or any

+    part thereof, to be licensed as a whole at no charge to all third

+    parties under the terms of this License.

+

+    c) If the modified program normally reads commands interactively

+    when run, you must cause it, when started running for such

+    interactive use in the most ordinary way, to print or display an

+    announcement including an appropriate copyright notice and a

+    notice that there is no warranty (or else, saying that you provide

+    a warranty) and that users may redistribute the program under

+    these conditions, and telling the user how to view a copy of this

+    License.  (Exception: if the Program itself is interactive but

+    does not normally print such an announcement, your work based on

+    the Program is not required to print an announcement.)

+

+These requirements apply to the modified work as a whole.  If

+identifiable sections of that work are not derived from the Program,

+and can be reasonably considered independent and separate works in

+themselves, then this License, and its terms, do not apply to those

+sections when you distribute them as separate works.  But when you

+distribute the same sections as part of a whole which is a work based

+on the Program, the distribution of the whole must be on the terms of

+this License, whose permissions for other licensees extend to the

+entire whole, and thus to each and every part regardless of who wrote it.

+

+Thus, it is not the intent of this section to claim rights or contest

+your rights to work written entirely by you; rather, the intent is to

+exercise the right to control the distribution of derivative or

+collective works based on the Program.

+

+In addition, mere aggregation of another work not based on the Program

+with the Program (or with a work based on the Program) on a volume of

+a storage or distribution medium does not bring the other work under

+the scope of this License.

+

+  3. You may copy and distribute the Program (or a work based on it,

+under Section 2) in object code or executable form under the terms of

+Sections 1 and 2 above provided that you also do one of the following:

+

+    a) Accompany it with the complete corresponding machine-readable

+    source code, which must be distributed under the terms of Sections

+    1 and 2 above on a medium customarily used for software interchange; or,

+

+    b) Accompany it with a written offer, valid for at least three

+    years, to give any third party, for a charge no more than your

+    cost of physically performing source distribution, a complete

+    machine-readable copy of the corresponding source code, to be

+    distributed under the terms of Sections 1 and 2 above on a medium

+    customarily used for software interchange; or,

+

+    c) Accompany it with the information you received as to the offer

+    to distribute corresponding source code.  (This alternative is

+    allowed only for noncommercial distribution and only if you

+    received the program in object code or executable form with such

+    an offer, in accord with Subsection b above.)

+

+The source code for a work means the preferred form of the work for

+making modifications to it.  For an executable work, complete source

+code means all the source code for all modules it contains, plus any

+associated interface definition files, plus the scripts used to

+control compilation and installation of the executable.  However, as a

+special exception, the source code distributed need not include

+anything that is normally distributed (in either source or binary

+form) with the major components (compiler, kernel, and so on) of the

+operating system on which the executable runs, unless that component

+itself accompanies the executable.

+

+If distribution of executable or object code is made by offering

+access to copy from a designated place, then offering equivalent

+access to copy the source code from the same place counts as

+distribution of the source code, even though third parties are not

+compelled to copy the source along with the object code.

+

+  4. You may not copy, modify, sublicense, or distribute the Program

+except as expressly provided under this License.  Any attempt

+otherwise to copy, modify, sublicense or distribute the Program is

+void, and will automatically terminate your rights under this License.

+However, parties who have received copies, or rights, from you under

+this License will not have their licenses terminated so long as such

+parties remain in full compliance.

+

+  5. You are not required to accept this License, since you have not

+signed it.  However, nothing else grants you permission to modify or

+distribute the Program or its derivative works.  These actions are

+prohibited by law if you do not accept this License.  Therefore, by

+modifying or distributing the Program (or any work based on the

+Program), you indicate your acceptance of this License to do so, and

+all its terms and conditions for copying, distributing or modifying

+the Program or works based on it.

+

+  6. Each time you redistribute the Program (or any work based on the

+Program), the recipient automatically receives a license from the

+original licensor to copy, distribute or modify the Program subject to

+these terms and conditions.  You may not impose any further

+restrictions on the recipients' exercise of the rights granted herein.

+You are not responsible for enforcing compliance by third parties to

+this License.

+

+  7. If, as a consequence of a court judgment or allegation of patent

+infringement or for any other reason (not limited to patent issues),

+conditions are imposed on you (whether by court order, agreement or

+otherwise) that contradict the conditions of this License, they do not

+excuse you from the conditions of this License.  If you cannot

+distribute so as to satisfy simultaneously your obligations under this

+License and any other pertinent obligations, then as a consequence you

+may not distribute the Program at all.  For example, if a patent

+license would not permit royalty-free redistribution of the Program by

+all those who receive copies directly or indirectly through you, then

+the only way you could satisfy both it and this License would be to

+refrain entirely from distribution of the Program.

+

+If any portion of this section is held invalid or unenforceable under

+any particular circumstance, the balance of the section is intended to

+apply and the section as a whole is intended to apply in other

+circumstances.

+

+It is not the purpose of this section to induce you to infringe any

+patents or other property right claims or to contest validity of any

+such claims; this section has the sole purpose of protecting the

+integrity of the free software distribution system, which is

+implemented by public license practices.  Many people have made

+generous contributions to the wide range of software distributed

+through that system in reliance on consistent application of that

+system; it is up to the author/donor to decide if he or she is willing

+to distribute software through any other system and a licensee cannot

+impose that choice.

+

+This section is intended to make thoroughly clear what is believed to

+be a consequence of the rest of this License.

+

+  8. If the distribution and/or use of the Program is restricted in

+certain countries either by patents or by copyrighted interfaces, the

+original copyright holder who places the Program under this License

+may add an explicit geographical distribution limitation excluding

+those countries, so that distribution is permitted only in or among

+countries not thus excluded.  In such case, this License incorporates

+the limitation as if written in the body of this License.

+

+  9. The Free Software Foundation may publish revised and/or new versions

+of the General Public License from time to time.  Such new versions will

+be similar in spirit to the present version, but may differ in detail to

+address new problems or concerns.

+

+Each version is given a distinguishing version number.  If the Program

+specifies a version number of this License which applies to it and "any

+later version", you have the option of following the terms and conditions

+either of that version or of any later version published by the Free

+Software Foundation.  If the Program does not specify a version number of

+this License, you may choose any version ever published by the Free Software

+Foundation.

+

+  10. If you wish to incorporate parts of the Program into other free

+programs whose distribution conditions are different, write to the author

+to ask for permission.  For software which is copyrighted by the Free

+Software Foundation, write to the Free Software Foundation; we sometimes

+make exceptions for this.  Our decision will be guided by the two goals

+of preserving the free status of all derivatives of our free software and

+of promoting the sharing and reuse of software generally.

+

+                            NO WARRANTY

+

+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY

+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN

+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES

+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED

+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF