% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pairing-methods.R
\name{pairing_tables}
\alias{pairing_tables}
\title{Generate a list of tables representing clusters paired in cells}
\usage{
pairing_tables(
  ccdb,
  ranking_key = "grp_rank",
  table_order = 2,
  min_expansion = 2,
  orphan_level = 1,
  cluster_keys = character(),
  cluster_whitelist = NULL,
  cluster_blacklist = NULL
)
}
\arguments{
\item{ccdb}{\code{ContigCellDB}}

\item{ranking_key}{field in \code{ccdb$contig_tbl} giving the ranking of each contig per cell.  Probably generated by a call to \code{\link[=rank_prevalence_ccdb]{rank_prevalence_ccdb()}} or \code{\link[=rank_chain_ccdb]{rank_chain_ccdb()}}.}

\item{table_order}{Integer larger than 1. What order of cluster_idx will be
paired, eg, order = 2 means that the first and second highest ranked contigs will be sought and paired in each cell}

\item{min_expansion}{the minimal number of times a pairing needs to occur for
it to be reported}

\item{orphan_level}{Integer in interval [1, \code{table_order}].  Given that at least \code{min_expansion} cells are found that have \code{table_order} chains identical, how many \code{cluster_idx} pairs will we match on to select other cells.  Example: \code{ophan_level=1} means that cells that share just a single chain with an expanded pair will be reported.}

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

\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{cluster_blacklist}{a table of pairings or clusters that will never be reported.  Must be named as per \code{cluster_whitelist}.}
}
\value{
list of tables.  The \code{cell_tbl} is keyed by the \code{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 \code{idx1_tbl} and \code{idx2_tbl} report information (passed in about the \code{cluster_idx} by \code{feature_tbl}.)  The \code{cluster_pair_tbl} reports all pairings found of contigs, and the number of times observed.
}
\description{
A contingency table of every combination of \code{cluster_idx} up to \code{table_order}
is generated. Combinations that are found in at least \code{min_expansion} number
of cells are reported.  All cells that have these combinations are returned,
as well as cells that only have \code{orphan_level} of matching \code{cluster_idx}.
}
\details{
For example, if \code{table_order=2} and \code{min_expansion=2} then heavy/light or
alpha/beta pairs found two or more times will be returned
(as well as alpha-alpha pairs, etc, if those are present).
If \code{orphan_level=1} then all cells that share just a single chain with an
expanded clone will be returned.

The \code{cluster_idx.1_fct} and \code{cluster_idx.2_fct} fields in \code{cell_tbl},
\code{idx1_tbl}, \code{idx2_tbl} are cast to factors and ordered such that pairings will
tend to occur along the diagonal when they are cross-tabulated.
This facilitates plotting.
}
\examples{
library(dplyr)
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')
# add `grp_rank` to ccdb$contig_tbl indicating how frequent a cluster is
ccdb = rank_prevalence_ccdb(ccdb, tie_break_keys = character())
# using `grp_rank` to determine pairing
# no pairs found twice
pt1 = pairing_tables(ccdb)
# all pairs found, found once.
pt2 = pairing_tables(ccdb, min_expansion = 1)
pt2$cell_tbl
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') \%>\% rank_prevalence_ccdb(tie_break_keys = character())
#all pairs found twice
pt3 = pairing_tables(ccdb2, min_expansion = 1)
pt3$cell_tbl
ccdb2$contig_tbl = ccdb2$contig_tbl \%>\%
    mutate(umis = 1, reads = 1, chain = rep(c('TRA', 'TRB'), times = 6))
ccdb2 = rank_chain_ccdb(ccdb2, tie_break_keys = character())
pt4 = pairing_tables(ccdb2, min_expansion = 1, table_order = 2)
}
\seealso{
\code{\link[=rank_prevalence_ccdb]{rank_prevalence_ccdb()}}
}
