% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/clustering-methods.R
\name{canonicalize_cluster}
\alias{canonicalize_cluster}
\title{Find a canonical contig to represent a cluster}
\usage{
canonicalize_cluster(
  ccdb,
  contig_filter_args,
  tie_break_keys = character(),
  order = 1,
  representative = ccdb$cluster_pk[1],
  contig_fields = c("cdr3", "cdr3_nt", "chain", "v_gene", "d_gene", "j_gene"),
  overwrite = TRUE
)
}
\arguments{
\item{ccdb}{\code{\link[=ContigCellDB]{ContigCellDB()}}}

\item{contig_filter_args}{an expression passed to \code{\link[dplyr:filter]{dplyr::filter()}}.
Unlike \code{filter}, multiple criteria must be \code{&} together, rather than using
commas to separate. These act on \code{ccdb$contig_tbl}}

\item{tie_break_keys}{(optional) \code{character} naming fields in \code{contig_tbl}
that are used sort the contig table in descending order.
Used to break ties if \code{contig_filter_args} does not return a unique contig
for each cluster}

\item{order}{The rank order of the contig, based on \code{tie_break_keys}
to return.  If \code{tie_break_keys} included an ordered factor (such as chain)
this could be used to return the second chain.}

\item{representative}{an optional field from \code{contig_tbl} that will be made
unique. Serve as a surrogate \code{cluster_pk}.}

\item{contig_fields}{Optional fields from \code{contig_tbl} that will be copied into
the \code{cluster_tbl} from the canonical contig.}

\item{overwrite}{\code{logical} -- should non-key fields in y be overwritten using x, or should a suffix (".y") be added}
}
\value{
\code{\link[=ContigCellDB]{ContigCellDB()}} with some number of clusters/contigs/cells but with "canonical" values copied into \code{cluster_tbl}
}
\description{
Find a canonical contig to represent a cluster
}
\examples{
library(dplyr)
data(ccdb_ex)
ccdb_ex_small = ccdb_ex
ccdb_ex_small$cell_tbl = ccdb_ex_small$cell_tbl[1:200,]
ccdb_ex_small = 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')

# Canonicalize with the medoid contig is probably what is most common
ccdb_medoid = canonicalize_cluster(ccdb_ex_small)

# But there are other possibilities.
# To pass multiple "AND" filter arguments must use &
ccdb_umi = canonicalize_cluster(ccdb_ex_small,
contig_filter_args = chain == 'TRA' & length > 500, tie_break_keys = 'umis',
contig_fields = c('chain', 'length'))
ccdb_umi$cluster_tbl \%>\% dplyr::select(chain, length) \%>\% summary()
}
\seealso{
\code{\link[=canonicalize_cell]{canonicalize_cell()}} \code{\link[=left_join_warn]{left_join_warn()}}
}
