% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pairing-methods.R
\name{canonicalize_cell}
\alias{canonicalize_cell}
\title{Find a canonical contig to represent a cell}
\usage{
canonicalize_cell(
  ccdb,
  contig_filter_args = TRUE,
  tie_break_keys = c("umis", "reads"),
  contig_fields = tie_break_keys,
  order = 1,
  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{contig_fields}{Optional fields from \code{contig_tbl} that will be copied into
the \code{cluster_tbl} from the canonical contig.}

\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{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{cell_tbl}
}
\description{
Using filtering in \code{contig_filter_args} and sorting in \code{tie_break_keys} and \code{order} find a
single, canonical contig to represent each cell
Fields in \code{contig_fields} will be copied over to the \code{cell_tbl}.
}
\examples{
# Report beta chain with highest umi-count, breaking ties with reads
data(ccdb_ex)
beta = canonicalize_cell(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)

# Stable: only adds fields to `cell_tbl`
stopifnot(dplyr::all_equal(beta$cell_tbl[ccdb_ex$cell_pk],
ccdb_ex$cell_tbl[ccdb_ex$cell_pk], ignore_row_order = TRUE))

#Report cdr3 with highest UMI count, but only when > 5 UMIs support it
umi5 = canonicalize_cell(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))
}
\seealso{
\code{\link[=canonicalize_cluster]{canonicalize_cluster()}}
}
